event: API: Add sink-message event

gst_event_new_sink_message()
gst_event_parse_sink_message()

This event is used for sending a GstMessage downstream and synchronized
with the stream, to be posted by the sink once it reaches the sink.

Fixes bug #602275.

docs/gst/gstreamer-sections.txt

@@ -758,6 +758,9 @@ gst_event_parse_latency
 
 gst_event_new_step
 gst_event_parse_step
+
+gst_event_new_sink_message
+gst_event_parse_sink_message
 <SUBSECTION Standard>
 GstEventClass
 GST_EVENT

gst/gstevent.c

@@ -115,6 +115,7 @@ static GstEventQuarks event_quarks[] = {
   {GST_EVENT_NEWSEGMENT, "newsegment", 0},
   {GST_EVENT_TAG, "tag", 0},
   {GST_EVENT_BUFFERSIZE, "buffersize", 0},
+  {GST_EVENT_SINK_MESSAGE, "sink-message", 0},
   {GST_EVENT_QOS, "qos", 0},
   {GST_EVENT_SEEK, "seek", 0},
   {GST_EVENT_NAVIGATION, "navigation", 0},
@@ -1180,3 +1181,56 @@ gst_event_parse_step (GstEvent * event, GstFormat * format, guint64 * amount,
     *intermediate = g_value_get_boolean (gst_structure_id_get_value (structure,
             GST_QUARK (INTERMEDIATE)));
 }
+
+/**
+ * gst_event_new_sink_message:
+ * @msg: The #GstMessage to be posted
+ *
+ * Create a new sink-message event. The purpose of the sink-message event is
+ * to instruct a sink to post the message contained in the event synchronized
+ * with the stream.
+ *
+ * Returns: a new #GstEvent
+ *
+ * Since: 0.10.26
+ */
+GstEvent *
+gst_event_new_sink_message (GstMessage * msg)
+{
+  GstEvent *event;
+  GstStructure *structure;
+
+  g_return_val_if_fail (msg != NULL, NULL);
+
+  GST_CAT_INFO (GST_CAT_EVENT, "creating sink-message event");
+
+  structure = gst_structure_id_new (GST_QUARK (EVENT_SINK_MESSAGE),
+      GST_QUARK (MESSAGE), GST_TYPE_MESSAGE, msg, NULL);
+  event = gst_event_new_custom (GST_EVENT_SINK_MESSAGE, structure);
+
+  return event;
+}
+
+/**
+ * gst_event_parse_sink_message:
+ * @event: The event to query
+ * @msg: A pointer to store the #GstMessage in.
+ *
+ * Parse the sink-message event. Unref @msg after usage.
+ *
+ * Since: 0.10.26
+ */
+void
+gst_event_parse_sink_message (GstEvent * event, GstMessage ** msg)
+{
+  const GstStructure *structure;
+
+  g_return_if_fail (GST_IS_EVENT (event));
+  g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_SINK_MESSAGE);
+
+  structure = gst_event_get_structure (event);
+  if (msg)
+    *msg =
+        GST_MESSAGE (gst_value_dup_mini_object (gst_structure_id_get_value
+            (structure, GST_QUARK (MESSAGE))));
+}

gst/gstevent.h

@@ -120,6 +120,7 @@ typedef enum {
   GST_EVENT_NEWSEGMENT            = GST_EVENT_MAKE_TYPE (6, FLAG(DOWNSTREAM) | FLAG(SERIALIZED)),
   GST_EVENT_TAG                   = GST_EVENT_MAKE_TYPE (7, FLAG(DOWNSTREAM) | FLAG(SERIALIZED)),
   GST_EVENT_BUFFERSIZE            = GST_EVENT_MAKE_TYPE (8, FLAG(DOWNSTREAM) | FLAG(SERIALIZED)),
+  GST_EVENT_SINK_MESSAGE          = GST_EVENT_MAKE_TYPE (9, FLAG(DOWNSTREAM) | FLAG(SERIALIZED)),
   /* upstream events */
   GST_EVENT_QOS                   = GST_EVENT_MAKE_TYPE (15, FLAG(UPSTREAM)),
   GST_EVENT_SEEK                  = GST_EVENT_MAKE_TYPE (16, FLAG(UPSTREAM)),

gst/gstquark.c

@@ -47,7 +47,8 @@ static const gchar *_quark_strings[] = {
   "GstQueryPosition", "GstQueryDuration", "GstQueryLatency", "GstQueryConvert",
   "GstQuerySegment", "GstQuerySeeking", "GstQueryFormats", "GstQueryBuffering",
   "GstQueryURI", "GstEventStep", "GstMessageStepDone", "amount", "flush",
-  "intermediate", "GstMessageStepStart", "active", "eos"
+  "intermediate", "GstMessageStepStart", "active", "eos", "sink-message",
+  "message"
 };
 
 GQuark _priv_gst_quark_table[GST_QUARK_MAX];

gst/gstquark.h

@@ -117,8 +117,10 @@ typedef enum _GstQuarkId
   GST_QUARK_MESSAGE_STEP_START = 88,
   GST_QUARK_ACTIVE = 89,
   GST_QUARK_EOS = 90,
+  GST_QUARK_EVENT_SINK_MESSAGE = 91,
+  GST_QUARK_MESSAGE = 92,
 
-  GST_QUARK_MAX = 91
+  GST_QUARK_MAX = 93
 } GstQuarkId;
 
 extern GQuark _priv_gst_quark_table[GST_QUARK_MAX];

gst/gstutils.h

@@ -1172,6 +1172,19 @@ void gst_util_double_to_fraction (gdouble src, gint *dest_n, gint *dest_d);
 gboolean gst_util_fraction_multiply (gint a_n, gint a_d, gint b_n, gint b_d, gint *res_n, gint *res_d);
 gboolean gst_util_fraction_add (gint a_n, gint a_d, gint b_n, gint b_d, gint *res_n, gint *res_d);
 
+
+/* sink message event
+ *
+ * FIXME: This should be in gstevent.h but can't because
+ * it needs GstMessage and this would introduce circular
+ * header includes. And forward declarations of typedefs
+ * are unfortunately not possible. The implementation of
+ * these functions is in gstevent.c.
+ */
+GstEvent*       gst_event_new_sink_message      (struct _GstMessage *msg);
+void            gst_event_parse_sink_message    (GstEvent *event, struct _GstMessage **msg);
+
+
 G_END_DECLS
 
 #endif /* __GST_UTILS_H__ */

win32/common/libgstreamer.def

@@ -365,6 +365,7 @@ EXPORTS
 	gst_event_new_new_segment_full
 	gst_event_new_qos
 	gst_event_new_seek
+	gst_event_new_sink_message
 	gst_event_new_step
 	gst_event_new_tag
 	gst_event_parse_buffer_size
@@ -373,6 +374,7 @@ EXPORTS
 	gst_event_parse_new_segment_full
 	gst_event_parse_qos
 	gst_event_parse_seek
+	gst_event_parse_sink_message
 	gst_event_parse_step
 	gst_event_parse_tag
 	gst_event_set_seqnum