element: Add API to more easily post messages about flowing issues

In many parts of the code we raise streaming error when the flow
goes wrong, and each time we create more or less similare error
message. Also that message does not let the application know what
has actually gone wrong. In the new API we add a "flow-return" detail
field inside the GstMessage so that the application has all the information
if it needs it.

API:
    GST_ELEMENT_FLOW_ERROR

https://bugzilla.gnome.org/show_bug.cgi?id=770158

docs/gst/gstreamer-sections.txt

@@ -815,6 +815,7 @@ GST_ELEMENT_PADS
 GST_ELEMENT_START_TIME
 GST_ELEMENT_ERROR
 GST_ELEMENT_ERROR_WITH_DETAILS
+GST_ELEMENT_FLOW_ERROR
 GST_ELEMENT_WARNING
 GST_ELEMENT_WARNING_WITH_DETAILS
 GST_ELEMENT_INFO

gst/gstelement.h

@@ -402,6 +402,24 @@ typedef enum
 GstStructure *gst_make_element_message_details (const char *name, ...);
 #define GST_ELEMENT_MESSAGE_MAKE_DETAILS(args) gst_make_element_message_details args
 
+/**
+ * GST_ELEMENT_FLOW_ERROR:
+ * @el:           the element that generates the error
+ * @flow_return:  the GstFlowReturn leading to that ERROR message
+ *
+ * Utility function that elements can use in case they encountered a fatal
+ * data processing error due to wrong flow processing.
+ *
+ * Since: 1.10
+ */
+#define GST_ELEMENT_FLOW_ERROR(el,flow_return)  \
+G_STMT_START {                                                          \
+  GST_ELEMENT_ERROR_WITH_DETAILS (el, STREAM, FAILED, \
+      ("Internal data stream error."), \
+      ("streaming stopped, reason %s (%d)", gst_flow_get_name (flow_return), flow_return), \
+      ("flow-return", G_TYPE_INT, flow_return, NULL));\
+} G_STMT_END
+
 /**
  * GST_ELEMENT_ERROR_WITH_DETAILS:
  * @el:     the element that generates the error