/*
- * "$Id$"
+ * API versioning definitions for CUPS.
*
- * API versioning definitions for CUPS.
+ * Copyright © 2007-2019 by Apple Inc.
*
- * Copyright 2007-2013 by Apple Inc.
- *
- * These coded instructions, statements, and computer programs are the
- * property of Apple Inc. and are protected by Federal copyright
- * law. Distribution and use rights are outlined in the file "LICENSE.txt"
- * which should have been included with this file. If this file is
- * file is missing or damaged, see the license at "http://www.cups.org/".
- *
- * This file is subject to the Apple OS-Developed Software exception.
+ * Licensed under Apache License v2.0. See the file "LICENSE" for more
+ * information.
*/
#ifndef _CUPS_VERSIONING_H_
# define _CUPS_VERSIONING_H_
/*
- * This header defines several constants - _CUPS_DEPRECATED,
- * _CUPS_DEPRECATED_MSG, _CUPS_INTERNAL_MSG, _CUPS_API_1_1, _CUPS_API_1_1_19,
- * _CUPS_API_1_1_20, _CUPS_API_1_1_21, _CUPS_API_1_2, _CUPS_API_1_3,
- * _CUPS_API_1_4, _CUPS_API_1_5, _CUPS_API_1_6, and _CUPS_API_1_7 - which add
- * compiler-specific attributes that flag functions that are deprecated, added
- * in particular releases, or internal to CUPS.
+ * This header defines several macros that add compiler-specific attributes for
+ * functions:
*
- * On OS X, the _CUPS_API_* constants are defined based on the values of
- * the MAC_OS_X_VERSION_MIN_ALLOWED and MAC_OS_X_VERSION_MAX_ALLOWED constants
- * provided by the compiler.
+ * - _CUPS_API_major_minor[_patch]: Specifies when an API became available by
+ * CUPS version.
+ * - _CUPS_DEPRECATED: Function is deprecated with no replacement.
+ * - _CUPS_DEPRECATED_MSG("message"): Function is deprecated and has a
+ * replacement.
+ * - _CUPS_FORMAT(format-index, additional-args-index): Function has a
+ * printf-style format argument followed by zero or more additional
+ * arguments. Indices start at 1.
+ * - _CUPS_INTERNAL: Function is internal with no replacement API.
+ * - _CUPS_INTERNAL_MSG("msg"): Function is internal - use specified API
+ * instead.
+ * - _CUPS_NONNULL((arg list)): Specifies the comma-separated argument indices
+ * are assumed non-NULL. Indices start at 1.
+ * - _CUPS_NORETURN: Specifies the function does not return.
+ * - _CUPS_PRIVATE: Specifies the function is private to CUPS.
+ * - _CUPS_PUBLIC: Specifies the function is public API.
*/
-# if defined(__APPLE__) && !defined(_CUPS_SOURCE)
-# include <AvailabilityMacros.h>
-# ifndef AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER
-# define AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER __attribute__((unavailable))
-# endif /* !AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER */
-# ifndef AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER
-# define AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER __attribute__((unavailable))
-# endif /* !AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER */
-# ifndef AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER
-# define AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER __attribute__((unavailable))
-# endif /* !AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER */
-# ifndef AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER
-# define AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER __attribute__((unavailable))
-# endif /* !AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER */
-# ifndef AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER
-# define AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER __attribute__((unavailable))
-# endif /* !AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER */
-# ifndef AVAILABLE_MAC_OS_X_VERSION_10_8_AND_LATER
-# define AVAILABLE_MAC_OS_X_VERSION_10_8_AND_LATER __attribute__((unavailable))
-# endif /* !AVAILABLE_MAC_OS_X_VERSION_10_8_AND_LATER */
-# ifndef AVAILABLE_MAC_OS_X_VERSION_10_9_AND_LATER
-# define AVAILABLE_MAC_OS_X_VERSION_10_9_AND_LATER __attribute__((unavailable))
-# endif /* !AVAILABLE_MAC_OS_X_VERSION_10_9_AND_LATER */
-# define _CUPS_API_1_1_19 AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER
-# define _CUPS_API_1_1_20 AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER
-# define _CUPS_API_1_1_21 AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER
-# define _CUPS_API_1_2 AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER
-# define _CUPS_API_1_3 AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER
-# define _CUPS_API_1_4 AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER
-# define _CUPS_API_1_5 AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER
-# define _CUPS_API_1_6 AVAILABLE_MAC_OS_X_VERSION_10_8_AND_LATER
-# define _CUPS_API_1_7 AVAILABLE_MAC_OS_X_VERSION_10_9_AND_LATER
-# else
-# define _CUPS_API_1_1_19
-# define _CUPS_API_1_1_20
-# define _CUPS_API_1_1_21
-# define _CUPS_API_1_2
-# define _CUPS_API_1_3
-# define _CUPS_API_1_4
-# define _CUPS_API_1_5
-# define _CUPS_API_1_6
-# define _CUPS_API_1_7
-# endif /* __APPLE__ && !_CUPS_SOURCE */
-
/*
- * With GCC and Clang we can mark old APIs as "deprecated" or "unavailable" with
- * messages so you get warnings/errors are compile-time...
+ * Determine which compiler is being used and what annotation features are
+ * available...
*/
+# ifdef __APPLE__
+# include <os/availability.h>
+# endif /* __APPLE__ */
+
# ifdef __has_extension /* Clang */
# define _CUPS_HAS_DEPRECATED
+# define _CUPS_HAS_FORMAT
+# define _CUPS_HAS_NORETURN
+# define _CUPS_HAS_VISIBILITY
# if __has_extension(attribute_deprecated_with_message)
# define _CUPS_HAS_DEPRECATED_WITH_MESSAGE
# endif
# elif defined(__GNUC__) /* GCC and compatible */
# if __GNUC__ >= 3 /* GCC 3.0 or higher */
# define _CUPS_HAS_DEPRECATED
+# define _CUPS_HAS_FORMAT
+# define _CUPS_HAS_NORETURN
+# define _CUPS_HAS_VISIBILITY
# endif /* __GNUC__ >= 3 */
# if __GNUC__ >= 5 /* GCC 5.x */
# define _CUPS_HAS_DEPRECATED_WITH_MESSAGE
/* GCC 4.5 or higher */
# define _CUPS_HAS_DEPRECATED_WITH_MESSAGE
# endif /* __GNUC__ >= 5 */
+# elif defined(_WIN32)
+# define __attribute__(...)
# endif /* __has_extension */
+
+/*
+ * Define _CUPS_INTERNAL, _CUPS_PRIVATE, and _CUPS_PUBLIC visibilty macros for
+ * internal/private/public functions...
+ */
+
+# ifdef _CUPS_HAS_VISIBILITY
+# define _CUPS_INTERNAL __attribute__ ((visibility("hidden")))
+# define _CUPS_PRIVATE __attribute__ ((visibility("default")))
+# define _CUPS_PUBLIC __attribute__ ((visibility("default")))
+# elif defined(_WIN32) && defined(LIBCUPS2_EXPORTS) && 0
+# define _CUPS_INTERNAL
+# define _CUPS_PRIVATE __declspec(dllexport)
+# define _CUPS_PUBLIC __declspec(dllexport)
+# else
+# define _CUPS_INTERNAL
+# define _CUPS_PRIVATE
+# define _CUPS_PUBLIC
+# endif /* _CUPS_HAS_VISIBILITY */
+
+
+/*
+ * Define _CUPS_API_major_minor[_patch] availability macros for CUPS.
+ *
+ * Note: Using any of the _CUPS_API macros automatically adds _CUPS_PUBLIC.
+ */
+
+# if defined(__APPLE__) && !defined(_CUPS_SOURCE) && TARGET_OS_OSX
+/*
+ * On Apple operating systems, the _CUPS_API_* constants are defined using the
+ * API_ macros in <os/availability.h>.
+ *
+ * On iOS, we don't actually have libcups available directly, but the supplied
+ * libcups_static target in the Xcode project supports building on iOS 11.0 and
+ * later.
+ */
+# define _CUPS_API_1_1_19 API_AVAILABLE(macos(10.3), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_1_20 API_AVAILABLE(macos(10.4), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_1_21 API_AVAILABLE(macos(10.4), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_2 API_AVAILABLE(macos(10.5), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_3 API_AVAILABLE(macos(10.5), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_4 API_AVAILABLE(macos(10.6), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_5 API_AVAILABLE(macos(10.7), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_6 API_AVAILABLE(macos(10.8), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_1_7 API_AVAILABLE(macos(10.9), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_2_0 API_AVAILABLE(macos(10.10), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_2_2 API_AVAILABLE(macos(10.12), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_2_2_4 API_AVAILABLE(macos(10.13), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_2_2_7 API_AVAILABLE(macos(10.14), ios(11.0)) _CUPS_PUBLIC
+# define _CUPS_API_2_3 _CUPS_PUBLIC
+# else
+# define _CUPS_API_1_1_19 _CUPS_PUBLIC
+# define _CUPS_API_1_1_20 _CUPS_PUBLIC
+# define _CUPS_API_1_1_21 _CUPS_PUBLIC
+# define _CUPS_API_1_2 _CUPS_PUBLIC
+# define _CUPS_API_1_3 _CUPS_PUBLIC
+# define _CUPS_API_1_4 _CUPS_PUBLIC
+# define _CUPS_API_1_5 _CUPS_PUBLIC
+# define _CUPS_API_1_6 _CUPS_PUBLIC
+# define _CUPS_API_1_7 _CUPS_PUBLIC
+# define _CUPS_API_2_0 _CUPS_PUBLIC
+# define _CUPS_API_2_2 _CUPS_PUBLIC
+# define _CUPS_API_2_2_4 _CUPS_PUBLIC
+# define _CUPS_API_2_2_7 _CUPS_PUBLIC
+# define _CUPS_API_2_3 _CUPS_PUBLIC
+# endif /* __APPLE__ && !_CUPS_SOURCE */
+
+
+/*
+ * Define _CUPS_DEPRECATED and _CUPS_INTERNAL macros to mark old APIs as
+ * "deprecated" or "unavailable" with messages so you get warnings/errors are
+ * compile-time...
+ *
+ * Note: Using any of the _CUPS_DEPRECATED macros automatically adds
+ * _CUPS_PUBLIC.
+ */
+
# if !defined(_CUPS_HAS_DEPRECATED) || (defined(_CUPS_SOURCE) && !defined(_CUPS_NO_DEPRECATED))
/*
* Don't mark functions deprecated if the compiler doesn't support it
* or we are building CUPS source that doesn't care.
*/
-# define _CUPS_DEPRECATED
-# define _CUPS_DEPRECATED_MSG(m)
-# define _CUPS_DEPRECATED_1_6_MSG(m)
-# define _CUPS_DEPRECATED_1_7_MSG(m)
-# define _CUPS_INTERNAL_MSG(m)
+# define _CUPS_DEPRECATED _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_MSG(m) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_2_MSG(m) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_6_MSG(m) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_7_MSG(m) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_2_2_MSG(m) _CUPS_PUBLIC
+# elif defined(__APPLE__) && defined(_CUPS_NO_DEPRECATED)
+ /*
+ * Compiler supports the unavailable attribute, so use it when the code
+ * wants to exclude the use of deprecated API.
+ */
+# define _CUPS_DEPRECATED __attribute__ ((unavailable)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_2_MSG(m) API_DEPRECATED(m, macos(10.2,10.5), ios(11.0,11.0)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_6_MSG(m) API_DEPRECATED(m, macos(10.2,10.8), ios(11.0,11.0)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_7_MSG(m) API_DEPRECATED(m, macos(10.2,10.9), ios(11.0,11.0)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_2_2_MSG(m) API_DEPRECATED(m, macos(10.2,10.12), ios(11.0,11.0)) _CUPS_PUBLIC
+
+# elif defined(__APPLE__)
+ /*
+ * Just mark things as deprecated...
+ */
+# define _CUPS_DEPRECATED __attribute__ ((deprecated)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_2_MSG(m) API_DEPRECATED(m, macos(10.2,10.5), ios(11.0,11.0)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_6_MSG(m) API_DEPRECATED(m, macos(10.2,10.8), ios(11.0,11.0)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_7_MSG(m) API_DEPRECATED(m, macos(10.2,10.9), ios(11.0,11.0)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_2_2_MSG(m) API_DEPRECATED(m, macos(10.2,10.12), ios(11.0,11.0)) _CUPS_PUBLIC
+
# elif defined(_CUPS_HAS_UNAVAILABLE_WITH_MESSAGE) && defined(_CUPS_NO_DEPRECATED)
/*
* Compiler supports the unavailable attribute, so use it when the code
* wants to exclude the use of deprecated API.
*/
-# define _CUPS_DEPRECATED __attribute__ ((unavailable))
-# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((unavailable(m)))
-# define _CUPS_DEPRECATED_1_6_MSG(m) __attribute__ ((unavailable(m)))
-# define _CUPS_DEPRECATED_1_7_MSG(m) __attribute__ ((unavailable(m)))
-# define _CUPS_INTERNAL_MSG(m) __attribute__ ((unavailable(m)))
+# define _CUPS_DEPRECATED __attribute__ ((unavailable)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_2_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_6_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_7_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_2_2_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC
# else
/*
* Compiler supports the deprecated attribute, so use it.
*/
-# define _CUPS_DEPRECATED __attribute__ ((deprecated))
+# define _CUPS_DEPRECATED __attribute__ ((deprecated)) _CUPS_PUBLIC
# ifdef _CUPS_HAS_DEPRECATED_WITH_MESSAGE
-# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated(m)))
+# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_2_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_6_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_7_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_2_2_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC
# else
-# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated))
+# define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_2_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_6_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_1_7_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC
+# define _CUPS_DEPRECATED_2_2_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC
# endif /* _CUPS_HAS_DEPRECATED_WITH_MESSAGE */
-# if defined(MAC_OS_X_VERSION_10_8) && MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_8
-# define _CUPS_DEPRECATED_1_6_MSG(m) _CUPS_DEPRECATED_MSG(m)
-# else
-# define _CUPS_DEPRECATED_1_6_MSG(m)
-# endif /* MAC_OS_X_VERSION_MIN_REQUIRED > MAC_OS_X_VERSION_10_8 */
-# if defined(MAC_OS_X_VERSION_10_9) && MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_9
-# define _CUPS_DEPRECATED_1_7_MSG(m) _CUPS_DEPRECATED_MSG(m)
-# else
-# define _CUPS_DEPRECATED_1_7_MSG(m)
-# endif /* MAC_OS_X_VERSION_MIN_REQUIRED > MAC_OS_X_VERSION_10_9 */
-# ifdef _CUPS_SOURCE
-# define _CUPS_INTERNAL_MSG(m)
-# elif defined(_CUPS_HAS_UNAVAILABLE_WITH_MESSAGE)
-# define _CUPS_INTERNAL_MSG(m) __attribute__ ((unavailable(m)))
-# elif defined(_CUPS_HAS_DEPRECATED_WITH_MESSAGE)
-# define _CUPS_INTERNAL_MSG(m) __attribute__ ((deprecated(m)))
-# else
-# define _CUPS_INTERNAL_MSG(m) __attribute__ ((deprecated))
-# endif /* _CUPS_SOURCE */
# endif /* !_CUPS_HAS_DEPRECATED || (_CUPS_SOURCE && !_CUPS_NO_DEPRECATED) */
-# ifndef __GNUC__
-# define __attribute__(x)
-# endif /* !__GNUC__ */
-#endif /* !_CUPS_VERSIONING_H_ */
+/*
+ * Define _CUPS_FORMAT macro for printf-style functions...
+ */
+
+# ifdef _CUPS_HAS_FORMAT
+# define _CUPS_FORMAT(a,b) __attribute__ ((__format__(__printf__, a,b)))
+# else
+# define _CUPS_FORMAT(a,b)
+# endif /* _CUPS_HAS_FORMAT */
+
/*
- * End of "$Id$".
+ * Define _CUPS_INTERNAL_MSG macro for private APIs that have (historical)
+ * public visibility.
+ *
+ * Note: Using the _CUPS_INTERNAL_MSG macro automatically adds _CUPS_PUBLIC.
*/
+
+# ifdef _CUPS_SOURCE
+# define _CUPS_INTERNAL_MSG(m) _CUPS_PUBLIC
+# elif defined(_CUPS_HAS_UNAVAILABLE_WITH_MESSAGE)
+# define _CUPS_INTERNAL_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC
+# elif defined(_CUPS_HAS_DEPRECATED_WITH_MESSAGE)
+# define _CUPS_INTERNAL_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC
+# else
+# define _CUPS_INTERNAL_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC
+# endif /* _CUPS_SOURCE */
+
+
+/*
+ * Define _CUPS_NONNULL macro for functions that don't expect non-null
+ * arguments...
+ */
+
+# ifdef _CUPS_HAS_NONNULL
+# define _CUPS_NONNULL(...) __attribute__ ((nonnull(__VA_ARGS__)))
+# else
+# define _CUPS_NONNULL(...)
+# endif /* _CUPS_HAS_FORMAT */
+
+
+/*
+ * Define _CUPS_NORETURN macro for functions that don't return.
+ */
+
+# ifdef _CUPS_HAS_NORETURN
+# define _CUPS_NORETURN __attribute__ ((noreturn))
+# else
+# define _CUPS_NORETURN
+# endif /* _CUPS_HAS_NORETURN */
+
+
+#endif /* !_CUPS_VERSIONING_H_ */
projects / thirdparty / cups.git / blobdiff