gst/gstpad.*: Added _CUSTOM error and success GstFlowReturn that can be used be eleme...

Original commit message from CVS:
* gst/gstpad.c: (gst_flow_get_name), (gst_flow_to_quark):
* gst/gstpad.h:
Added _CUSTOM error and success GstFlowReturn that can be
used be elements internally.
Added macro to check for SUCCESS flowreturns.
API: GST_FLOW_CUSTOM_SUCCESS
API: GST_FLOW_CUSTOM_ERROR
API: GST_FLOW_IS_SUCCESS
* tests/check/gst/gstpad.c: (GST_START_TEST), (gst_pad_suite):
Added check for GstFlowReturn sanity.

diff --git a/ChangeLog b/ChangeLog
index 851c890..f8d1308 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,19 @@
 2006-05-23  Wim Taymans  <wim@fluendo.com>
 
+       * gst/gstpad.c: (gst_flow_get_name), (gst_flow_to_quark):
+       * gst/gstpad.h:
+       Added _CUSTOM error and success GstFlowReturn that can be
+       used be elements internally. 
+       Added macro to check for SUCCESS flowreturns.
+       API: GST_FLOW_CUSTOM_SUCCESS
+       API: GST_FLOW_CUSTOM_ERROR
+       API: GST_FLOW_IS_SUCCESS
+
+       * tests/check/gst/gstpad.c: (GST_START_TEST), (gst_pad_suite):
+       Added check for GstFlowReturn sanity.
+
+2006-05-23  Wim Taymans  <wim@fluendo.com>
+
        Patch by: Mark Nauwelaerts <manauw at skynet dot be>
 
        * libs/gst/base/gstcollectpads.c: (gst_collect_pads_remove_pad),

diff --git a/gst/gstpad.c b/gst/gstpad.c
index 15c87b3..3b6dcd1 100644 (file)
--- a/gst/gstpad.c
+++ b/gst/gstpad.c
@@ -130,6 +130,7 @@ typedef struct
 } GstFlowQuarks;
 
 static GstFlowQuarks flow_quarks[] = {
+  {GST_FLOW_CUSTOM_SUCCESS, "custom-success", 0},
   {GST_FLOW_RESEND, "resend", 0},
   {GST_FLOW_OK, "ok", 0},
   {GST_FLOW_NOT_LINKED, "not-linked", 0},
@@ -138,6 +139,7 @@ static GstFlowQuarks flow_quarks[] = {
   {GST_FLOW_NOT_NEGOTIATED, "not-negotiated", 0},
   {GST_FLOW_ERROR, "error", 0},
   {GST_FLOW_NOT_SUPPORTED, "not-supported", 0},
+  {GST_FLOW_CUSTOM_ERROR, "custom-error", 0},
 
   {0, NULL, 0}
 };
@@ -148,13 +150,15 @@ static GstFlowQuarks flow_quarks[] = {
  *
  * Gets a string representing the given flow return.
  *
- * Returns: a string with the name of the flow return.
+ * Returns: a static string with the name of the flow return.
  */
 G_CONST_RETURN gchar *
 gst_flow_get_name (GstFlowReturn ret)
 {
   gint i;
 
+  ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
+
   for (i = 0; flow_quarks[i].name; i++) {
     if (ret == flow_quarks[i].ret)
       return flow_quarks[i].name;
@@ -176,6 +180,8 @@ gst_flow_to_quark (GstFlowReturn ret)
 {
   gint i;
 
+  ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
+
   for (i = 0; flow_quarks[i].name; i++) {
     if (ret == flow_quarks[i].ret)
       return flow_quarks[i].quark;

diff --git a/gst/gstpad.h b/gst/gstpad.h
index 26b7c5e..bf2041e 100644 (file)
--- a/gst/gstpad.h
+++ b/gst/gstpad.h
@@ -91,18 +91,32 @@ typedef enum {
 
 /**
  * GstFlowReturn:
+ * @GST_FLOW_CUSTOM_SUCCESS:    Elements can use values starting from
+ *                               this to define custom success codes. 
+ *                               Since 0.10.7.
  * @GST_FLOW_RESEND:            Resend buffer, possibly with new caps.
  * @GST_FLOW_OK:                Data passing was ok.
  * @GST_FLOW_NOT_LINKED:        Pad is not linked.
  * @GST_FLOW_WRONG_STATE:       Pad is in wrong state.
  * @GST_FLOW_UNEXPECTED:        Did not expect anything, like after EOS.
  * @GST_FLOW_NOT_NEGOTIATED:    Pad is not negotiated.
- * @GST_FLOW_ERROR:             Some (fatal) error occured.
+ * @GST_FLOW_ERROR:             Some (fatal) error occured. Element generating
+ *                               this error should post an error message with more
+ *                               details.
  * @GST_FLOW_NOT_SUPPORTED:     This operation is not supported.
+ * @GST_FLOW_CUSTOM_ERROR:      Elements can use values starting from
+ *                               this to define custom error codes. Since 0.10.7.
  *
- * The result of passing data to a linked pad.
+ * The result of passing data to a pad. 
+ *
+ * Note that the custom return values should not be exposed outside of the 
+ * element scope and are available since 0.10.7.
  */
 typedef enum {
+  /* custom success starts here */ 
+  GST_FLOW_CUSTOM_SUCCESS = 100,
+
+  /* core predefined */ 
   GST_FLOW_RESEND        =  1,
   GST_FLOW_OK            =  0,
   /* expected failures */
@@ -112,7 +126,10 @@ typedef enum {
   GST_FLOW_UNEXPECTED     = -3,
   GST_FLOW_NOT_NEGOTIATED = -4,
   GST_FLOW_ERROR         = -5,
-  GST_FLOW_NOT_SUPPORTED  = -6
+  GST_FLOW_NOT_SUPPORTED  = -6,
+
+  /* custom error starts here */ 
+  GST_FLOW_CUSTOM_ERROR   = -100
 } GstFlowReturn;
 
 /**
@@ -125,6 +142,19 @@ typedef enum {
  */
 #define GST_FLOW_IS_FATAL(ret) ((ret) <= GST_FLOW_UNEXPECTED)
 
+/**
+ * GST_FLOW_IS_SUCCESS:
+ * @ret: a #GstFlowReturn value
+ *
+ * Macro to test if the given #GstFlowReturn value indicates a 
+ * successfull result
+ * This macro is mainly used in elements to decide if the processing
+ * of a buffer was successfull.
+ *
+ * Since: 0.10.7
+ */
+#define GST_FLOW_IS_SUCCESS(ret) ((ret) >= GST_FLOW_OK)
+
 G_CONST_RETURN gchar*  gst_flow_get_name       (GstFlowReturn ret);
 GQuark                 gst_flow_to_quark       (GstFlowReturn ret);
 

diff --git a/tests/check/gst/gstpad.c b/tests/check/gst/gstpad.c
index 1221c83..258c7cc 100644 (file)
--- a/tests/check/gst/gstpad.c
+++ b/tests/check/gst/gstpad.c
@@ -380,6 +380,67 @@ GST_START_TEST (test_push_linked)
 
 GST_END_TEST;
 
+GST_START_TEST (test_flowreturn)
+{
+  GstFlowReturn ret;
+  GQuark quark;
+
+  /* test some of the macros */
+  ret = GST_FLOW_UNEXPECTED;
+  fail_unless (GST_FLOW_IS_FATAL (ret));
+  fail_if (GST_FLOW_IS_SUCCESS (ret));
+  fail_if (strcmp (gst_flow_get_name (ret), "unexpected"));
+  quark = gst_flow_to_quark (ret);
+  fail_if (strcmp (g_quark_to_string (quark), "unexpected"));
+
+  ret = GST_FLOW_RESEND;
+  fail_if (GST_FLOW_IS_FATAL (ret));
+  fail_unless (GST_FLOW_IS_SUCCESS (ret));
+  fail_if (strcmp (gst_flow_get_name (ret), "resend"));
+  quark = gst_flow_to_quark (ret);
+  fail_if (strcmp (g_quark_to_string (quark), "resend"));
+
+  /* custom returns */
+  ret = GST_FLOW_CUSTOM_SUCCESS;
+  fail_if (GST_FLOW_IS_FATAL (ret));
+  fail_unless (GST_FLOW_IS_SUCCESS (ret));
+  fail_if (strcmp (gst_flow_get_name (ret), "custom-success"));
+  quark = gst_flow_to_quark (ret);
+  fail_if (strcmp (g_quark_to_string (quark), "custom-success"));
+
+  ret = GST_FLOW_CUSTOM_ERROR;
+  fail_unless (GST_FLOW_IS_FATAL (ret));
+  fail_if (GST_FLOW_IS_SUCCESS (ret));
+  fail_if (strcmp (gst_flow_get_name (ret), "custom-error"));
+  quark = gst_flow_to_quark (ret);
+  fail_if (strcmp (g_quark_to_string (quark), "custom-error"));
+
+  /* custom returns clamping */
+  ret = GST_FLOW_CUSTOM_SUCCESS + 2;
+  fail_if (GST_FLOW_IS_FATAL (ret));
+  fail_unless (GST_FLOW_IS_SUCCESS (ret));
+  fail_if (strcmp (gst_flow_get_name (ret), "custom-success"));
+  quark = gst_flow_to_quark (ret);
+  fail_if (strcmp (g_quark_to_string (quark), "custom-success"));
+
+  ret = GST_FLOW_CUSTOM_ERROR - 2;
+  fail_unless (GST_FLOW_IS_FATAL (ret));
+  fail_if (GST_FLOW_IS_SUCCESS (ret));
+  fail_if (strcmp (gst_flow_get_name (ret), "custom-error"));
+  quark = gst_flow_to_quark (ret);
+  fail_if (strcmp (g_quark_to_string (quark), "custom-error"));
+
+  /* unknown values */
+  ret = GST_FLOW_CUSTOM_ERROR + 2;
+  fail_unless (GST_FLOW_IS_FATAL (ret));
+  fail_if (GST_FLOW_IS_SUCCESS (ret));
+  fail_if (strcmp (gst_flow_get_name (ret), "unknown"));
+  quark = gst_flow_to_quark (ret);
+  fail_unless (quark == 0);
+
+}
+
+GST_END_TEST;
 
 Suite *
 gst_pad_suite (void)
@@ -398,6 +459,8 @@ gst_pad_suite (void)
   tcase_add_test (tc_chain, test_name_is_valid);
   tcase_add_test (tc_chain, test_push_unlinked);
   tcase_add_test (tc_chain, test_push_linked);
+  tcase_add_test (tc_chain, test_flowreturn);
+
   return s;
 }