pad: Deprecate GST_FLOW_IS_FATAL() and GST_FLOW_IS_SUCCESS()

The problem with both macros is, that they suggest something that isn't true.
If GST_FLOW_IS_FATAL is true, there could still be a problem for many elements
and they should stop what they're currently doing and return that value
upstream (e.g. not-linked in a parser). If GST_FLOW_IS_SUCCESS is false, it
could still be that this is "ok" for the element (e.g. not-linked for a demuxer
on a few of its pads but not all).

It's better to not have these "convenience" macros but instead let people
*think* about the handling of different flow returns, that makes sense for
their element. And we should document the expected handling of flow returns for
different classes of elements in the plugin writer's guide.

Fixes bug #628014.

diff --git a/gst/gstpad.h b/gst/gstpad.h
index 99d4e05..10cb206 100644 (file)
--- a/gst/gstpad.h
+++ b/gst/gstpad.h
@@ -158,8 +158,13 @@ typedef enum {
  * whether an error message should be posted on the bus. Note that such
  * elements may also need to post an error message in the #GST_FLOW_NOT_LINKED
  * case which is not caught by this macro.
+ *
+ * Deprecated: This macro is badly named and can't be used in any real
+ * scenarios without additional checks.
  */
+#ifndef GST_DISABLE_DEPRECATED
 #define GST_FLOW_IS_FATAL(ret) ((ret) <= GST_FLOW_UNEXPECTED)
+#endif
 
 /**
  * GST_FLOW_IS_SUCCESS:
@@ -171,8 +176,13 @@ typedef enum {
  * of a buffer was successfull.
  *
  * Since: 0.10.7
+ *
+ * Deprecated: This macro is badly named and can't be used in any real
+ * scenarios without additional checks.
  */
+#ifndef GST_DISABLE_DEPRECATED
 #define GST_FLOW_IS_SUCCESS(ret) ((ret) >= GST_FLOW_OK)
+#endif
 
 G_CONST_RETURN gchar*  gst_flow_get_name       (GstFlowReturn ret);
 GQuark                 gst_flow_to_quark       (GstFlowReturn ret);