Utilities

+telepathy-glib/telepathy-glib.h base-connection TpBaseConnection TP_INTERNAL_CONNECTION_STATUS_NEW diff --git a/telepathy-glib/Makefile.am b/telepathy-glib/Makefile.am index 8c504f2..30efdb6 100644 --- a/telepathy-glib/Makefile.am +++ b/telepathy-glib/Makefile.am @@ -146,6 +146,10 @@ BUILT_SOURCES = $(codegen_sources) CLEANFILES = \ $(BUILT_SOURCES) +nodist_tpginclude_HEADERS = \ + version.h \ + $(NULL) + distclean-local: rm -rf _gen diff --git a/telepathy-glib/defs.h b/telepathy-glib/defs.h index 979b817..e39b517 100644 --- a/telepathy-glib/defs.h +++ b/telepathy-glib/defs.h @@ -23,6 +23,7 @@ #define __TP_DEFS_H__ #include +#include G_BEGIN_DECLS @@ -149,13 +150,120 @@ G_BEGIN_DECLS */ #define TP_USER_ACTION_TIME_CURRENT_TIME (G_MAXINT64) -/* telepathy-glib-specific version of G_GNUC_DEPRECATED so our regression +#define _TP_ENCODE_VERSION(major, minor) (((major) << 16) | ((minor) << 8)) + +#define TP_VERSION_0_16 (_TP_ENCODE_VERSION (0, 16)) +#define TP_VERSION_0_18 (_TP_ENCODE_VERSION (0, 18)) +#define TP_VERSION_0_20 (_TP_ENCODE_VERSION (0, 20)) +#define TP_VERSION_1_0 (_TP_ENCODE_VERSION (1, 0)) + +#if (TP_MINOR_VERSION == 99) + /* special case for telepathy-glib 1.0 prereleases */ +# define _TP_VERSION_CUR_STABLE (_TP_ENCODE_VERSION (TP_MAJOR_VERSION + 1, 0)) +# define _TP_VERSION_PREV_STABLE (_TP_ENCODE_VERSION (TP_MAJOR_VERSION + 1, 0)) +#elif (TP_MINOR_VERSION == 0) + /* special case for telepathy-glib 1.0 itself */ +# define _TP_VERSION_CUR_STABLE (_TP_ENCODE_VERSION (TP_MAJOR_VERSION, 0)) +# define _TP_VERSION_PREV_STABLE (_TP_ENCODE_VERSION (TP_MAJOR_VERSION, 0)) +#elif (TP_MINOR_VERSION % 2) + /* development branch */ +# define _TP_VERSION_CUR_STABLE \ + (_TP_ENCODE_VERSION (TP_MAJOR_VERSION, TP_MINOR_VERSION + 1)) +# define _TP_VERSION_PREV_STABLE \ + (_TP_ENCODE_VERSION (TP_MAJOR_VERSION, TP_MINOR_VERSION - 1)) +#else + /* stable branch */ +# define _TP_VERSION_CUR_STABLE \ + (_TP_ENCODE_VERSION (TP_MAJOR_VERSION, TP_MINOR_VERSION)) +# define _TP_VERSION_PREV_STABLE \ + (_TP_ENCODE_VERSION (TP_MAJOR_VERSION, TP_MINOR_VERSION - 2)) +#endif + +#ifndef TP_VERSION_MIN_REQUIRED +# define TP_VERSION_MIN_REQUIRED (TP_VERSION_PREV_STABLE) +#endif + +#ifndef TP_VERSION_MAX_ALLOWED +# define TP_VERSION_MAX_ALLOWED (TP_VERSION_CUR_STABLE) +#endif + +#if TP_VERSION_MAX_ALLOWED < TP_VERSION_MIN_REQUIRED +# error "TP_VERSION_MAX_ALLOWED must be >= TP_VERSION_MIN_REQUIRED" +#endif +#if TP_VERSION_MIN_REQUIRED < TP_VERSION_0_10 +# error "TP_VERSION_MIN_REQUIRED must be >= TP_VERSION_0_16" +#endif + +#if TP_VERSION_MIN_REQUIRED >= TP_VERSION_0_16 +# define _TP_DEPRECATED_IN_0_16 _TP_DEPRECATED +# define _TP_DEPRECATED_IN_0_16_FOR(f) _TP_DEPRECATED_FOR(f) +#else +# define _TP_DEPRECATED_IN_0_16 /* nothing */ +# define _TP_DEPRECATED_IN_0_16_FOR(f) /* nothing */ +#endif + +#if TP_VERSION_MIN_REQUIRED >= TP_VERSION_0_18 +# define _TP_DEPRECATED_IN_0_18 _TP_DEPRECATED +# define _TP_DEPRECATED_IN_0_18_FOR(f) _TP_DEPRECATED_FOR(f) +#else +# define _TP_DEPRECATED_IN_0_18 /* nothing */ +# define _TP_DEPRECATED_IN_0_18_FOR(f) /* nothing */ +#endif + +#if TP_VERSION_MIN_REQUIRED >= TP_VERSION_0_20 +# define _TP_DEPRECATED_IN_0_20 _TP_DEPRECATED +# define _TP_DEPRECATED_IN_0_20_FOR(f) _TP_DEPRECATED_FOR(f) +#else +# define _TP_DEPRECATED_IN_0_20 /* nothing */ +# define _TP_DEPRECATED_IN_0_20_FOR(f) /* nothing */ +#endif + +#if TP_VERSION_MIN_REQUIRED >= TP_VERSION_1_0 +# define _TP_DEPRECATED_IN_1_0 _TP_DEPRECATED +# define _TP_DEPRECATED_IN_1_0_FOR(f) _TP_DEPRECATED_FOR(f) +#else +# define _TP_DEPRECATED_IN_1_0 /* nothing */ +# define _TP_DEPRECATED_IN_1_0_FOR(f) /* nothing */ +#endif + +#if TP_VERSION_MAX_ALLOWED < TP_VERSION_0_16 +# define _TP_AVAILABLE_IN_0_16 _TP_UNAVAILABLE(0, 16) +#else +# define _TP_AVAILABLE_IN_0_16 /* nothing */ +#endif + +#if TP_VERSION_MAX_ALLOWED < TP_VERSION_0_18 +# define _TP_AVAILABLE_IN_0_18 _TP_UNAVAILABLE(0, 18) +#else +# define _TP_AVAILABLE_IN_0_18 /* nothing */ +#endif + +#if TP_VERSION_MAX_ALLOWED < TP_VERSION_0_20 +# define _TP_AVAILABLE_IN_0_20 _TP_UNAVAILABLE(0, 20) +#else +# define _TP_AVAILABLE_IN_0_20 /* nothing */ +#endif + +#if TP_VERSION_MAX_ALLOWED < TP_VERSION_1_0 +# define _TP_AVAILABLE_IN_1_0 _TP_UNAVAILABLE(1, 0) +#else +# define _TP_AVAILABLE_IN_1_0 /* nothing */ +#endif + +/* telepathy-glib-specific macros so our regression * tests can continue to test deprecated functionality, while avoiding * deprecated bits of other libraries */ #ifdef _TP_IGNORE_DEPRECATIONS +#define _TP_DEPRECATED /* nothing */ +#define _TP_DEPRECATED_FOR(f) /* nothing */ +#define _TP_UNAVAILABLE(major, minor) /* nothing */ #define _TP_GNUC_DEPRECATED /* nothing */ #define _TP_GNUC_DEPRECATED_FOR(f) /* nothing */ #else +#define _TP_DEPRECATED G_DEPRECATED +#define _TP_DEPRECATED_FOR(f) G_DEPRECATED_FOR(f) +#define _TP_UNAVAILABLE(major, minor) G_UNAVAILABLE(major, minor) + /* Available for typedefs etc., not just functions, but gcc-specific */ #define _TP_GNUC_DEPRECATED G_GNUC_DEPRECATED #define _TP_GNUC_DEPRECATED_FOR(f) G_GNUC_DEPRECATED_FOR(f) #endif diff --git a/telepathy-glib/extra-gtkdoc.h b/telepathy-glib/extra-gtkdoc.h index 11c624c..8402dc5 100644 --- a/telepathy-glib/extra-gtkdoc.h +++ b/telepathy-glib/extra-gtkdoc.h @@ -380,6 +380,125 @@ */ /** + * SECTION:version + * @title: Version information + * @short_description: Checking the telepathy-glib version + * + * Since 0.UNRELEASED, telepathy-glib provides version information similar + * to that used in GLib. + * + * Typical usage from configure.ac is similar to GLib's: + * + * |[ + * AC_DEFINE([TP_VERSION_MIN_REQUIRED], [TP_VERSION_0_18], + * [Ignore deprecations newer than this branch]) + * AC_DEFINE([TP_VERSION_MAX_ALLOWED], [TP_VERSION_0_20], + * [Prevent use of APIs newer than this branch]) + * ]| + * + * or you can define the macros directly on the compiler command line + * if required: + * + * |[ + * cc -o foo foo.c \ + * -DTP_VERSION_MIN_REQUIRED=TP_VERSION_0_18 \ + * -DTP_VERSION_MAX_ALLOWED=TP_VERSION_0_20 \ + * ${TP_CFLAGS} ${TP_LIBS} + * ]| + * + * This functionality was added in telepathy-glib 0.UNRELEASED, but it + * is safe to define the TP_VERSION_MIN_REQUIRED and TP_VERSION_MAX_ALLOWED + * macros even for older versions of telepathy-glib, as long as you do + * not try to expand them. + */ + +/** + * TP_MAJOR_VERSION: + * + * The major version of telepathy-glib (e.g. the 0 in 0.18.1) at the time your + * code was compiled. + */ + +/** + * TP_MINOR_VERSION: + * + * The minor version of telepathy-glib (e.g. the 18 in 0.18.1) at the time your + * code was compiled. + * + * Odd minor versions indicate a development branch; even minor versions + * indicate a stable branch. + */ + +/** + * TP_MICRO_VERSION: + * + * The micro version of telepathy-glib (e.g. the 1 in 0.18.1) at the time your + * code was compiled. + * + * Within a stable branch (even minor version), micro versions fix bugs + * but do not add features. + * + * Within a development branch (odd minor version), micro versions can + * fix bugs and/or add features. + */ + +/** + * TP_VERSION_0_16: (skip) + * + * A constant representing the telepathy-glib 0.16 stable branch, + * and the 0.15 development branch that led to it. + */ + +/** + * TP_VERSION_0_18: (skip) + * + * A constant representing the telepathy-glib 0.18 stable branch, + * and the 0.17 development branch that led to it. + */ + +/** + * TP_VERSION_0_20: (skip) + * + * A constant representing the telepathy-glib 0.20 stable branch, + * and the 0.19 development branch that led to it. + */ + +/** + * TP_VERSION_1_0: (skip) + * + * A constant representing the telepathy-glib 1.0 stable branch, + * and the 0.99 development branch that led to it. + */ + +/** + * TP_VERSION_MIN_REQUIRED: (skip) + * + * A version-number constant like %TP_VERSION_0_18. + * + * This may be defined to a value like %TP_VERSION_0_18 by users of + * telepathy-glib, to set the minimum version they wish to + * require. Warnings will be issued for functions deprecated in or + * before that version. + * + * If not defined, the default value is the previous stable branch. + */ + +/** + * TP_VERSION_MAX_ALLOWED: (skip) + * + * A version-number constant like %TP_VERSION_0_18. + * + * This may be defined to a value like %TP_VERSION_0_18 by users of + * telepathy-glib, to set the maximum version they wish to + * depend on. Warnings will be issued for functions deprecated in or + * before that version. + * + * If not defined, the default value in stable branches is that stable + * branch, and the default value in development branches is the next + * stable branch. + */ + +/** * SECTION:enums * @title: Telepathy protocol enumerations * @short_description: Enumerated types and bitfields from the Telepathy spec diff --git a/telepathy-glib/version.h.in b/telepathy-glib/version.h.in new file mode 100644 index 0000000..0c227ec --- /dev/null +++ b/telepathy-glib/version.h.in @@ -0,0 +1,5 @@ +/* @configure_input@ */ + +#define TP_MAJOR_VERSION @TP_MAJOR_VERSION@ +#define TP_MINOR_VERSION @TP_MINOR_VERSION@ +#define TP_MICRO_VERSION @TP_MICRO_VERSION@ -- 1.7.10