Differences between revisions 1 and 2
Revision 1 as of 2008-01-31 15:14:11
Size: 1865
Editor: 88-97-242-46
Comment:
Revision 2 as of 2009-01-13 11:33:28
Size: 1865
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

Deprecating API

There are two relevant preprocessor defines:

  • GST_DISABLE_DEPRECATED
  • GST_REMOVE_DEPRECATED

GST_DISABLE_DEPRECATED

Declarations of deprecated API in header files should be guarded with this.

The idea is that people who want to make sure that they are not using deprecated GStreamer API in their applications or plugins can add -DGST_DISABLE_DEPRECATED to their CFLAGS and will then receive a compiler warning about the missing declaration if they are trying to use such a deprecated function in their code.

GST_DISABLE_DEPRECATED should only affect the visibility of function declarations, it should under no circumstances change ABI. This means, among other things, that you must never use it within a structure definition in a public header file.

Example (in gstbuffer.h):

#ifndef GST_DISABLE_DEPRECATED
void gst_buffer_stamp (GstBuffer * dest, const GstBuffer * src);
#endif

Applications and plugin modules should try not to use -DGST_DISABLE_DEPRECATED and -Wall -Werror combined as CFLAGS for releases, since this would make releases harder to compile against newer versions of GStreamer or gst-plugins-base (-DGST_DISABLE_DEPRECATED and just -Wall is obviously ok though).

GST_REMOVE_DEPRECATED

This macro can be used to remove deprecated API (ie. whole function bodies) from the build. This breaks ABI (meaning: if you use this, you're basically on your own, don't come to us for support). You should probably re-build the entire GStreamer/gst-plugins-*/GStreamer applications stack if you make changes anywhere in the stack.

Example (in gstbuffer.c):

#ifndef GST_REMOVE_DEPRECATED
void
gst_buffer_stamp (GstBuffer * dest, const GstBuffer * src)
{
  gst_buffer_copy_metadata (dest, src, GST_BUFFER_COPY_TIMESTAMPS);
}
#endif /* GST_REMOVE_DEPRECATED */

DeprecatingAPI (last edited 2009-01-13 11:33:28 by localhost)