X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gst%2Fgstevent.c;h=386a1eb8d3a6f393d27faa31f1fe6564dd9db079;hb=e10266e3f3cf9b05b69198b1ac6faa9a62840e30;hp=3bb548039b73e214378d98d5f6eec9281f5b91c6;hpb=5acdc22001033be1310fa9085b44ab79157e6f82;p=platform%2Fupstream%2Fgstreamer.git diff --git a/gst/gstevent.c b/gst/gstevent.c index 3bb5480..386a1eb 100644 --- a/gst/gstevent.c +++ b/gst/gstevent.c @@ -17,8 +17,8 @@ * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, + * Boston, MA 02110-1301, USA. */ /** @@ -36,24 +36,22 @@ * elements will use gst_pad_send_event() or gst_pad_push_event(). * The event should be unreffed with gst_event_unref() if it has not been sent. * - * Events that have been received can be parsed with their respective + * Events that have been received can be parsed with their respective * gst_event_parse_*() functions. It is valid to pass %NULL for unwanted details. * * Events are passed between elements in parallel to the data stream. Some events * are serialized with buffers, others are not. Some events only travel downstream, - * others only upstream. Some events can travel both upstream and downstream. - * + * others only upstream. Some events can travel both upstream and downstream. + * * The events are used to signal special conditions in the datastream such as * EOS (end of stream) or the start of a new stream-segment. * Events are also used to flush the pipeline of any pending data. * - * Most of the event API is used inside plugins. Applications usually only - * construct and use seek events. + * Most of the event API is used inside plugins. Applications usually only + * construct and use seek events. * To do that gst_event_new_seek() is used to create a seek event. It takes * the needed parameters to specify seeking time and mode. - * - * performing a seek on a pipeline - * + * |[ * GstEvent *event; * gboolean result; * ... @@ -69,10 +67,7 @@ * if (!result) * g_warning ("seek failed"); * ... - * - * - * - * Last reviewed on 2006-09-6 (0.10.10) + * ]| */ @@ -84,6 +79,7 @@ #include "gstenumtypes.h" #include "gstutils.h" #include "gstquark.h" +#include "gstvalue.h" GType _gst_event_type = 0; @@ -92,6 +88,7 @@ typedef struct GstEvent event; GstStructure *structure; + gint64 running_time_offset; } GstEventImpl; #define GST_EVENT_STRUCTURE(e) (((GstEventImpl *)(e))->structure) @@ -107,21 +104,27 @@ static GstEventQuarks event_quarks[] = { {GST_EVENT_UNKNOWN, "unknown", 0}, {GST_EVENT_FLUSH_START, "flush-start", 0}, {GST_EVENT_FLUSH_STOP, "flush-stop", 0}, - {GST_EVENT_EOS, "eos", 0}, + {GST_EVENT_STREAM_START, "stream-start", 0}, {GST_EVENT_CAPS, "caps", 0}, {GST_EVENT_SEGMENT, "segment", 0}, {GST_EVENT_TAG, "tag", 0}, + {GST_EVENT_TOC, "toc", 0}, {GST_EVENT_BUFFERSIZE, "buffersize", 0}, {GST_EVENT_SINK_MESSAGE, "sink-message", 0}, + {GST_EVENT_EOS, "eos", 0}, + {GST_EVENT_SEGMENT_DONE, "segment-done", 0}, + {GST_EVENT_GAP, "gap", 0}, {GST_EVENT_QOS, "qos", 0}, {GST_EVENT_SEEK, "seek", 0}, {GST_EVENT_NAVIGATION, "navigation", 0}, {GST_EVENT_LATENCY, "latency", 0}, {GST_EVENT_STEP, "step", 0}, {GST_EVENT_RECONFIGURE, "reconfigure", 0}, + {GST_EVENT_TOC_SELECT, "toc-select", 0}, {GST_EVENT_CUSTOM_UPSTREAM, "custom-upstream", 0}, {GST_EVENT_CUSTOM_DOWNSTREAM, "custom-downstream", 0}, {GST_EVENT_CUSTOM_DOWNSTREAM_OOB, "custom-downstream-oob", 0}, + {GST_EVENT_CUSTOM_DOWNSTREAM_STICKY, "custom-downstream-sticky", 0}, {GST_EVENT_CUSTOM_BOTH, "custom-both", 0}, {GST_EVENT_CUSTOM_BOTH_OOB, "custom-both-oob", 0}, @@ -198,7 +201,7 @@ gst_event_type_get_flags (GstEventType type) { GstEventTypeFlags ret; - ret = type & ((1 << GST_EVENT_STICKY_SHIFT) - 1); + ret = type & ((1 << GST_EVENT_NUM_SHIFT) - 1); return ret; } @@ -221,11 +224,10 @@ _gst_event_free (GstEvent * event) gst_structure_free (s); } - g_slice_free1 (GST_MINI_OBJECT_SIZE (event), event); + g_slice_free1 (sizeof (GstEventImpl), event); } -static void gst_event_init (GstEventImpl * event, gsize size, - GstEventType type); +static void gst_event_init (GstEventImpl * event, GstEventType type); static GstEvent * _gst_event_copy (GstEvent * event) @@ -235,7 +237,7 @@ _gst_event_copy (GstEvent * event) copy = g_slice_new0 (GstEventImpl); - gst_event_init (copy, sizeof (GstEventImpl), GST_EVENT_TYPE (event)); + gst_event_init (copy, GST_EVENT_TYPE (event)); GST_EVENT_TIMESTAMP (copy) = GST_EVENT_TIMESTAMP (event); GST_EVENT_SEQNUM (copy) = GST_EVENT_SEQNUM (event); @@ -245,37 +247,29 @@ _gst_event_copy (GstEvent * event) GST_EVENT_STRUCTURE (copy) = gst_structure_copy (s); gst_structure_set_parent_refcount (GST_EVENT_STRUCTURE (copy), ©->event.mini_object.refcount); + } else { + GST_EVENT_STRUCTURE (copy) = NULL; } + + ((GstEventImpl *) copy)->running_time_offset = + ((GstEventImpl *) event)->running_time_offset; + return GST_EVENT_CAST (copy); } static void -gst_event_init (GstEventImpl * event, gsize size, GstEventType type) +gst_event_init (GstEventImpl * event, GstEventType type) { - gst_mini_object_init (GST_MINI_OBJECT_CAST (event), _gst_event_type, size); - - event->event.mini_object.copy = (GstMiniObjectCopyFunction) _gst_event_copy; - event->event.mini_object.free = (GstMiniObjectFreeFunction) _gst_event_free; + gst_mini_object_init (GST_MINI_OBJECT_CAST (event), 0, _gst_event_type, + (GstMiniObjectCopyFunction) _gst_event_copy, NULL, + (GstMiniObjectFreeFunction) _gst_event_free); GST_EVENT_TYPE (event) = type; GST_EVENT_TIMESTAMP (event) = GST_CLOCK_TIME_NONE; GST_EVENT_SEQNUM (event) = gst_util_seqnum_next (); + event->running_time_offset = 0; } -static GstEvent * -gst_event_new (GstEventType type) -{ - GstEventImpl *event; - - event = g_slice_new0 (GstEventImpl); - - GST_CAT_DEBUG (GST_CAT_EVENT, "creating new event %p %s %d", event, - gst_event_type_get_name (type), type); - - gst_event_init (event, sizeof (GstEventImpl), type); - - return GST_EVENT_CAST (event); -} /** * gst_event_new_custom: @@ -299,23 +293,30 @@ gst_event_new (GstEventType type) GstEvent * gst_event_new_custom (GstEventType type, GstStructure * structure) { - GstEvent *event; + GstEventImpl *event; + + event = g_slice_new0 (GstEventImpl); + + GST_CAT_DEBUG (GST_CAT_EVENT, "creating new event %p %s %d", event, + gst_event_type_get_name (type), type); - /* structure must not have a parent */ - event = gst_event_new (type); if (structure) { + /* structure must not have a parent */ if (!gst_structure_set_parent_refcount (structure, - &event->mini_object.refcount)) + &event->event.mini_object.refcount)) goto had_parent; - GST_EVENT_STRUCTURE (event) = structure; } - return event; + gst_event_init (event, type); + + GST_EVENT_STRUCTURE (event) = structure; + + return GST_EVENT_CAST (event); /* ERRORS */ had_parent: { - gst_event_unref (event); + g_slice_free1 (sizeof (GstEventImpl), event); g_warning ("structure is already owned by another object"); return NULL; } @@ -350,7 +351,7 @@ gst_event_get_structure (GstEvent * event) * Returns: The structure of the event. The structure is still * owned by the event, which means that you should not free it and * that the pointer becomes invalid when you free the event. - * This function checks if @event is writable and will never return NULL. + * This function checks if @event is writable and will never return %NULL. * * MT safe. */ @@ -383,8 +384,6 @@ gst_event_writable_structure (GstEvent * event) * check the name of a custom event. * * Returns: %TRUE if @name matches the name of the event structure. - * - * Since: 0.10.20 */ gboolean gst_event_has_name (GstEvent * event, const gchar * name) @@ -417,8 +416,6 @@ gst_event_has_name (GstEvent * event, const gchar * name) * Returns: The event's sequence number. * * MT safe. - * - * Since: 0.10.22 */ guint32 gst_event_get_seqnum (GstEvent * event) @@ -440,8 +437,6 @@ gst_event_get_seqnum (GstEvent * event) * more information. * * MT safe. - * - * Since: 0.10.22 */ void gst_event_set_seqnum (GstEvent * event, guint32 seqnum) @@ -451,9 +446,53 @@ gst_event_set_seqnum (GstEvent * event, guint32 seqnum) GST_EVENT_SEQNUM (event) = seqnum; } -/* FIXME 0.11: It would be nice to have flush events - * that don't reset the running time in the sinks +/** + * gst_event_get_running_time_offset: + * @event: A #GstEvent. + * + * Retrieve the accumulated running time offset of the event. + * + * Events passing through #GstPads that have a running time + * offset set via gst_pad_set_offset() will get their offset + * adjusted according to the pad's offset. + * + * If the event contains any information that related to the + * running time, this information will need to be updated + * before usage with this offset. + * + * Returns: The event's running time offset + * + * MT safe. + * + * Since: 1.4 */ +gint64 +gst_event_get_running_time_offset (GstEvent * event) +{ + g_return_val_if_fail (GST_IS_EVENT (event), 0); + + return ((GstEventImpl *) event)->running_time_offset; +} + +/** + * gst_event_set_running_time_offset: + * @event: A #GstEvent. + * @offset: A the new running time offset + * + * Set the running time offset of a event. See + * gst_event_get_running_time_offset() for more information. + * + * MT safe. + * + * Since: 1.4 + */ +void +gst_event_set_running_time_offset (GstEvent * event, gint64 offset) +{ + g_return_if_fail (GST_IS_EVENT (event)); + + ((GstEventImpl *) event)->running_time_offset = offset; +} /** * gst_event_new_flush_start: @@ -462,9 +501,9 @@ gst_event_set_seqnum (GstEvent * event, guint32 seqnum) * upstream and downstream and travels out-of-bounds with the dataflow. * * It marks pads as being flushing and will make them return - * #GST_FLOW_WRONG_STATE when used for data flow with gst_pad_push(), - * gst_pad_chain(), gst_pad_alloc_buffer(), gst_pad_get_range() and - * gst_pad_pull_range(). Any event (except a #GST_EVENT_FLUSH_STOP) received + * #GST_FLOW_FLUSHING when used for data flow with gst_pad_push(), + * gst_pad_chain(), gst_pad_get_range() and gst_pad_pull_range(). + * Any event (except a #GST_EVENT_FLUSH_STOP) received * on a flushing pad will return %FALSE immediately. * * Elements should unlock any blocking functions and exit their streaming @@ -478,7 +517,7 @@ gst_event_set_seqnum (GstEvent * event, guint32 seqnum) GstEvent * gst_event_new_flush_start (void) { - return gst_event_new (GST_EVENT_FLUSH_START); + return gst_event_new_custom (GST_EVENT_FLUSH_START, NULL); } /** @@ -491,7 +530,7 @@ gst_event_new_flush_start (void) * pads accept data again. * * Elements can process this event synchronized with the dataflow since - * the preceeding FLUSH_START event stopped the dataflow. + * the preceding FLUSH_START event stopped the dataflow. * * This event is typically generated to complete a seek and to resume * dataflow. @@ -539,7 +578,7 @@ gst_event_parse_flush_stop (GstEvent * event, gboolean * reset_time) * * Create a new EOS event. The eos event can only travel downstream * synchronized with the buffer flow. Elements that receive the EOS - * event on a pad can return #GST_FLOW_UNEXPECTED as a #GstFlowReturn + * event on a pad can return #GST_FLOW_EOS as a #GstFlowReturn * when data after the EOS event arrives. * * The EOS event will travel down to the sink elements in the pipeline @@ -556,7 +595,65 @@ gst_event_parse_flush_stop (GstEvent * event, gboolean * reset_time) GstEvent * gst_event_new_eos (void) { - return gst_event_new (GST_EVENT_EOS); + return gst_event_new_custom (GST_EVENT_EOS, NULL); +} + +/** + * gst_event_new_gap: + * @timestamp: the start time (pts) of the gap + * @duration: the duration of the gap + * + * Create a new GAP event. A gap event can be thought of as conceptually + * equivalent to a buffer to signal that there is no data for a certain + * amount of time. This is useful to signal a gap to downstream elements + * which may wait for data, such as muxers or mixers or overlays, especially + * for sparse streams such as subtitle streams. + * + * Returns: (transfer full): the new GAP event. + */ +GstEvent * +gst_event_new_gap (GstClockTime timestamp, GstClockTime duration) +{ + GstEvent *event; + + g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), NULL); + + GST_CAT_TRACE (GST_CAT_EVENT, "creating gap %" GST_TIME_FORMAT " - " + "%" GST_TIME_FORMAT " (duration: %" GST_TIME_FORMAT ")", + GST_TIME_ARGS (timestamp), GST_TIME_ARGS (timestamp + duration), + GST_TIME_ARGS (duration)); + + event = gst_event_new_custom (GST_EVENT_GAP, + gst_structure_new_id (GST_QUARK (EVENT_GAP), + GST_QUARK (TIMESTAMP), GST_TYPE_CLOCK_TIME, timestamp, + GST_QUARK (DURATION), GST_TYPE_CLOCK_TIME, duration, NULL)); + + return event; +} + +/** + * gst_event_parse_gap: + * @event: a #GstEvent of type #GST_EVENT_GAP + * @timestamp: (out) (allow-none): location where to store the + * start time (pts) of the gap, or %NULL + * @duration: (out) (allow-none): location where to store the duration of + * the gap, or %NULL + * + * Extract timestamp and duration from a new GAP event. + */ +void +gst_event_parse_gap (GstEvent * event, GstClockTime * timestamp, + GstClockTime * duration) +{ + GstStructure *structure; + + g_return_if_fail (GST_IS_EVENT (event)); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_GAP); + + structure = GST_EVENT_STRUCTURE (event); + gst_structure_id_get (structure, + GST_QUARK (TIMESTAMP), GST_TYPE_CLOCK_TIME, timestamp, + GST_QUARK (DURATION), GST_TYPE_CLOCK_TIME, duration, NULL); } /** @@ -589,7 +686,7 @@ gst_event_new_caps (GstCaps * caps) /** * gst_event_parse_caps: * @event: The event to parse - * @caps: (out): A pointer to the caps + * @caps: (out) (transfer none): A pointer to the caps * * Get the caps from @event. The caps remains valid as long as @event remains * valid. @@ -653,6 +750,9 @@ gst_event_new_segment (const GstSegment * segment) GstEvent *event; g_return_val_if_fail (segment != NULL, NULL); + g_return_val_if_fail (segment->rate != 0.0, NULL); + g_return_val_if_fail (segment->applied_rate != 0.0, NULL); + g_return_val_if_fail (segment->format != GST_FORMAT_UNDEFINED, NULL); GST_CAT_INFO (GST_CAT_EVENT, "creating segment event %" GST_SEGMENT_FORMAT, segment); @@ -717,14 +817,28 @@ gst_event_copy_segment (GstEvent * event, GstSegment * segment) * * Generates a metadata tag event from the given @taglist. * + * The scope of the taglist specifies if the taglist applies to the + * complete medium or only to this specific stream. As the tag event + * is a sticky event, elements should merge tags received from + * upstream with a given scope with their own tags with the same + * scope and create a new tag event from it. + * * Returns: (transfer full): a new #GstEvent */ GstEvent * gst_event_new_tag (GstTagList * taglist) { + GstStructure *s; + GValue val = G_VALUE_INIT; + const gchar *names[] = { "GstTagList-stream", "GstTagList-global" }; + g_return_val_if_fail (taglist != NULL, NULL); - return gst_event_new_custom (GST_EVENT_TAG, (GstStructure *) taglist); + s = gst_structure_new_empty (names[gst_tag_list_get_scope (taglist)]); + g_value_init (&val, GST_TYPE_TAG_LIST); + g_value_take_boxed (&val, taglist); + gst_structure_id_take_value (s, GST_QUARK (TAGLIST), &val); + return gst_event_new_custom (GST_EVENT_TAG, s); } /** @@ -740,11 +854,16 @@ gst_event_new_tag (GstTagList * taglist) void gst_event_parse_tag (GstEvent * event, GstTagList ** taglist) { + const GValue *val; + g_return_if_fail (GST_IS_EVENT (event)); g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_TAG); + val = gst_structure_id_get_value (GST_EVENT_STRUCTURE (event), + GST_QUARK (TAGLIST)); + if (taglist) - *taglist = (GstTagList *) GST_EVENT_STRUCTURE (event); + *taglist = (GstTagList *) g_value_get_boxed (val); } /* buffersize event */ @@ -864,7 +983,7 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format, * increasing value. * * The upstream element can use the @diff and @timestamp values to decide - * whether to process more buffers. For possitive @diff, all buffers with + * whether to process more buffers. For positive @diff, all buffers with * timestamp <= @timestamp + @diff will certainly arrive late in the sink * as well. A (negative) @diff value so that @timestamp + @diff would yield a * result smaller than 0 is not allowed. @@ -909,6 +1028,8 @@ gst_event_new_qos (GstQOSType type, gdouble proportion, * * Get the type, proportion, diff and timestamp in the qos event. See * gst_event_new_qos() for more information about the different QoS values. + * + * @timestamp will be adjusted for any pad offsets of pads it was passing through. */ void gst_event_parse_qos (GstEvent * event, GstQOSType * type, @@ -932,10 +1053,18 @@ gst_event_parse_qos (GstEvent * event, GstQOSType * type, *diff = g_value_get_int64 (gst_structure_id_get_value (structure, GST_QUARK (DIFF))); - if (timestamp) + if (timestamp) { + gint64 offset = gst_event_get_running_time_offset (event); + *timestamp = g_value_get_uint64 (gst_structure_id_get_value (structure, GST_QUARK (TIMESTAMP))); + /* Catch underflows */ + if (*timestamp > -offset) + *timestamp += offset; + else + *timestamp = 0; + } } /** @@ -972,13 +1101,13 @@ gst_event_parse_qos (GstEvent * event, GstQOSType * type, * from the newly configured start position. * * For negative rates, playback will start from the newly configured stop - * position (if any). If the stop position if updated, it must be different from - * -1 for negative rates. + * position (if any). If the stop position is updated, it must be different from + * -1 (#GST_CLOCK_TIME_NONE) for negative rates. * * It is not possible to seek relative to the current playback position, to do * this, PAUSE the pipeline, query the current playback position with * #GST_QUERY_POSITION and update the playback segment current position with a - * #GST_SEEK_TYPE_SET to the desired position. + * #GST_SEEK_TYPE_SET to the desired position. * * Returns: (transfer full): a new seek event. */ @@ -1027,9 +1156,9 @@ gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags, * @format: (out): result location for the stream format * @flags: (out): result location for the #GstSeekFlags * @start_type: (out): result location for the #GstSeekType of the start position - * @start: (out): result location for the start postion expressed in @format + * @start: (out): result location for the start position expressed in @format * @stop_type: (out): result location for the #GstSeekType of the stop position - * @stop: (out): result location for the stop postion expressed in @format + * @stop: (out): result location for the stop position expressed in @format * * Parses a seek @event and stores the results in the given result locations. */ @@ -1103,8 +1232,6 @@ gst_event_new_navigation (GstStructure * structure) * the time format. * * Returns: (transfer full): a new #GstEvent - * - * Since: 0.10.12 */ GstEvent * gst_event_new_latency (GstClockTime latency) @@ -1128,8 +1255,6 @@ gst_event_new_latency (GstClockTime latency) * @latency: (out): A pointer to store the latency in. * * Get the latency in the latency event. - * - * Since: 0.10.12 */ void gst_event_parse_latency (GstEvent * event, GstClockTime * latency) @@ -1166,8 +1291,6 @@ gst_event_parse_latency (GstEvent * event, GstClockTime * latency) * part of a larger step operation. * * Returns: (transfer full): a new #GstEvent - * - * Since: 0.10.24 */ GstEvent * gst_event_new_step (GstFormat format, guint64 amount, gdouble rate, @@ -1202,8 +1325,6 @@ gst_event_new_step (GstFormat format, guint64 amount, gdouble rate, * boolean in * * Parse the step event. - * - * Since: 0.10.24 */ void gst_event_parse_step (GstEvent * event, GstFormat * format, guint64 * amount, @@ -1236,14 +1357,12 @@ gst_event_parse_step (GstEvent * event, GstFormat * format, guint64 * amount, /** * gst_event_new_reconfigure: - * Create a new reconfigure event. The purpose of the reconfingure event is + * Create a new reconfigure event. The purpose of the reconfigure event is * to travel upstream and make elements renegotiate their caps or reconfigure * their buffer pools. This is useful when changing properties on elements * or changing the topology of the pipeline. * * Returns: (transfer full): a new #GstEvent - * - * Since: 0.11.0 */ GstEvent * gst_event_new_reconfigure (void) @@ -1259,19 +1378,20 @@ gst_event_new_reconfigure (void) /** * gst_event_new_sink_message: + * @name: a name for the event * @msg: (transfer none): 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: (transfer full): a new #GstEvent + * @name is used to store multiple sticky events on one pad. * - * Since: 0.10.26 + * Returns: (transfer full): a new #GstEvent */ /* FIXME 0.11: take ownership of msg for consistency? */ GstEvent * -gst_event_new_sink_message (GstMessage * msg) +gst_event_new_sink_message (const gchar * name, GstMessage * msg) { GstEvent *event; GstStructure *structure; @@ -1280,7 +1400,7 @@ gst_event_new_sink_message (GstMessage * msg) GST_CAT_INFO (GST_CAT_EVENT, "creating sink-message event"); - structure = gst_structure_new_id (GST_QUARK (EVENT_SINK_MESSAGE), + structure = gst_structure_new_id (g_quark_from_string (name), GST_QUARK (MESSAGE), GST_TYPE_MESSAGE, msg, NULL); event = gst_event_new_custom (GST_EVENT_SINK_MESSAGE, structure); @@ -1293,8 +1413,6 @@ gst_event_new_sink_message (GstMessage * msg) * @msg: (out) (transfer full): 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) @@ -1310,3 +1428,320 @@ gst_event_parse_sink_message (GstEvent * event, GstMessage ** msg) GST_MESSAGE (g_value_dup_boxed (gst_structure_id_get_value (structure, GST_QUARK (MESSAGE)))); } + +/** + * gst_event_new_stream_start: + * @stream_id: Identifier for this stream + * + * Create a new STREAM_START event. The stream start event can only + * travel downstream synchronized with the buffer flow. It is expected + * to be the first event that is sent for a new stream. + * + * Source elements, demuxers and other elements that create new streams + * are supposed to send this event as the first event of a new stream. It + * should not be send after a flushing seek or in similar situations + * and is used to mark the beginning of a new logical stream. Elements + * combining multiple streams must ensure that this event is only forwarded + * downstream once and not for every single input stream. + * + * The @stream_id should be a unique string that consists of the upstream + * stream-id, / as separator and a unique stream-id for this specific + * stream. A new stream-id should only be created for a stream if the upstream + * stream is split into (potentially) multiple new streams, e.g. in a demuxer, + * but not for every single element in the pipeline. + * gst_pad_create_stream_id() or gst_pad_create_stream_id_printf() can be + * used to create a stream-id. + * + * Returns: (transfer full): the new STREAM_START event. + */ +GstEvent * +gst_event_new_stream_start (const gchar * stream_id) +{ + GstStructure *s; + + g_return_val_if_fail (stream_id != NULL, NULL); + + s = gst_structure_new_id (GST_QUARK (EVENT_STREAM_START), + GST_QUARK (STREAM_ID), G_TYPE_STRING, stream_id, + GST_QUARK (FLAGS), GST_TYPE_STREAM_FLAGS, GST_STREAM_FLAG_NONE, NULL); + + return gst_event_new_custom (GST_EVENT_STREAM_START, s); +} + +/** + * gst_event_parse_stream_start: + * @event: a stream-start event. + * @stream_id: (out) (transfer none): pointer to store the stream-id + * + * Parse a stream-id @event and store the result in the given @stream_id + * location. The string stored in @stream_id must not be modified and will + * remain valid only until @event gets freed. Make a copy if you want to + * modify it or store it for later use. + */ +void +gst_event_parse_stream_start (GstEvent * event, const gchar ** stream_id) +{ + const GstStructure *structure; + const GValue *val; + + g_return_if_fail (event != NULL); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START); + + structure = gst_event_get_structure (event); + val = gst_structure_id_get_value (structure, GST_QUARK (STREAM_ID)); + + if (stream_id) + *stream_id = g_value_get_string (val); +} + +/** + * gst_event_set_stream_flags: + * @event: a stream-start event + * @flags: the stream flags to set + * + * Since: 1.2 + */ +void +gst_event_set_stream_flags (GstEvent * event, GstStreamFlags flags) +{ + g_return_if_fail (event != NULL); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START); + g_return_if_fail (gst_event_is_writable (event)); + + gst_structure_id_set (GST_EVENT_STRUCTURE (event), + GST_QUARK (FLAGS), GST_TYPE_STREAM_FLAGS, flags, NULL); +} + +/** + * gst_event_parse_stream_flags: + * @event: a stream-start event + * @flags: (out): address of variable where to store the stream flags + * + * Since: 1.2 + */ +void +gst_event_parse_stream_flags (GstEvent * event, GstStreamFlags * flags) +{ + g_return_if_fail (event != NULL); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START); + + if (flags) { + gst_structure_id_get (GST_EVENT_STRUCTURE (event), + GST_QUARK (FLAGS), GST_TYPE_STREAM_FLAGS, flags, NULL); + } +} + +/** + * gst_event_set_group_id: + * @event: a stream-start event + * @group_id: the group id to set + * + * All streams that have the same group id are supposed to be played + * together, i.e. all streams inside a container file should have the + * same group id but different stream ids. The group id should change + * each time the stream is started, resulting in different group ids + * each time a file is played for example. + * + * Use gst_util_group_id_next() to get a new group id. + * + * Since: 1.2 + */ +void +gst_event_set_group_id (GstEvent * event, guint group_id) +{ + g_return_if_fail (event != NULL); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START); + g_return_if_fail (gst_event_is_writable (event)); + + gst_structure_id_set (GST_EVENT_STRUCTURE (event), + GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id, NULL); +} + +/** + * gst_event_parse_group_id: + * @event: a stream-start event + * @group_id: (out): address of variable where to store the group id + * + * Returns: %TRUE if a group id was set on the event and could be parsed, + * %FALSE otherwise. + * + * Since: 1.2 + */ +gboolean +gst_event_parse_group_id (GstEvent * event, guint * group_id) +{ + g_return_val_if_fail (event != NULL, FALSE); + g_return_val_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START, + FALSE); + + if (group_id) { + return gst_structure_id_get (GST_EVENT_STRUCTURE (event), + GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id, NULL); + } + + return TRUE; +} + +/** + * gst_event_new_toc: + * @toc: (transfer none): #GstToc structure. + * @updated: whether @toc was updated or not. + * + * Generate a TOC event from the given @toc. The purpose of the TOC event is to + * inform elements that some kind of the TOC was found. + * + * Returns: (transfer full): a new #GstEvent. + */ +GstEvent * +gst_event_new_toc (GstToc * toc, gboolean updated) +{ + GstStructure *toc_struct; + GQuark id; + + g_return_val_if_fail (toc != NULL, NULL); + + GST_CAT_INFO (GST_CAT_EVENT, "creating toc event"); + + /* need different structure names so sticky_multi event stuff on pads + * works, i.e. both TOC events are kept around */ + if (gst_toc_get_scope (toc) == GST_TOC_SCOPE_GLOBAL) + id = GST_QUARK (EVENT_TOC_GLOBAL); + else + id = GST_QUARK (EVENT_TOC_CURRENT); + + toc_struct = gst_structure_new_id (id, + GST_QUARK (TOC), GST_TYPE_TOC, toc, + GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL); + + return gst_event_new_custom (GST_EVENT_TOC, toc_struct); +} + +/** + * gst_event_parse_toc: + * @event: a TOC event. + * @toc: (out) (transfer full): pointer to #GstToc structure. + * @updated: (out): pointer to store TOC updated flag. + * + * Parse a TOC @event and store the results in the given @toc and @updated locations. + */ +void +gst_event_parse_toc (GstEvent * event, GstToc ** toc, gboolean * updated) +{ + const GstStructure *structure; + + g_return_if_fail (event != NULL); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_TOC); + g_return_if_fail (toc != NULL); + + structure = gst_event_get_structure (event); + + gst_structure_id_get (structure, + GST_QUARK (TOC), GST_TYPE_TOC, toc, + GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL); +} + +/** + * gst_event_new_toc_select: + * @uid: UID in the TOC to start playback from. + * + * Generate a TOC select event with the given @uid. The purpose of the + * TOC select event is to start playback based on the TOC's entry with the + * given @uid. + * + * Returns: a new #GstEvent. + */ +GstEvent * +gst_event_new_toc_select (const gchar * uid) +{ + GstStructure *structure; + + g_return_val_if_fail (uid != NULL, NULL); + + GST_CAT_INFO (GST_CAT_EVENT, "creating toc select event for UID: %s", uid); + + structure = gst_structure_new_id (GST_QUARK (EVENT_TOC_SELECT), + GST_QUARK (UID), G_TYPE_STRING, uid, NULL); + + return gst_event_new_custom (GST_EVENT_TOC_SELECT, structure); +} + +/** + * gst_event_parse_toc_select: + * @event: a TOC select event. + * @uid: (out): storage for the selection UID. + * + * Parse a TOC select @event and store the results in the given @uid location. + */ +void +gst_event_parse_toc_select (GstEvent * event, gchar ** uid) +{ + const GstStructure *structure; + const GValue *val; + + g_return_if_fail (event != NULL); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_TOC_SELECT); + + structure = gst_event_get_structure (event); + val = gst_structure_id_get_value (structure, GST_QUARK (UID)); + + if (uid != NULL) + *uid = g_strdup (g_value_get_string (val)); + +} + +/** + * gst_event_new_segment_done: + * @format: The format of the position being done + * @position: The position of the segment being done + * + * Create a new segment-done event. This event is sent by elements that + * finish playback of a segment as a result of a segment seek. + * + * Returns: (transfer full): a new #GstEvent + */ +GstEvent * +gst_event_new_segment_done (GstFormat format, gint64 position) +{ + GstEvent *event; + GstStructure *structure; + + GST_CAT_INFO (GST_CAT_EVENT, "creating segment-done event"); + + structure = gst_structure_new_id (GST_QUARK (EVENT_SEGMENT_DONE), + GST_QUARK (FORMAT), GST_TYPE_FORMAT, format, + GST_QUARK (POSITION), G_TYPE_INT64, position, NULL); + + event = gst_event_new_custom (GST_EVENT_SEGMENT_DONE, structure); + + return event; +} + +/** + * gst_event_parse_segment_done: + * @event: A valid #GstEvent of type GST_EVENT_SEGMENT_DONE. + * @format: (out) (allow-none): Result location for the format, or %NULL + * @position: (out) (allow-none): Result location for the position, or %NULL + * + * Extracts the position and format from the segment done message. + * + */ +void +gst_event_parse_segment_done (GstEvent * event, GstFormat * format, + gint64 * position) +{ + const GstStructure *structure; + const GValue *val; + + g_return_if_fail (event != NULL); + g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_SEGMENT_DONE); + + structure = gst_event_get_structure (event); + + val = gst_structure_id_get_value (structure, GST_QUARK (FORMAT)); + if (format != NULL) + *format = g_value_get_enum (val); + + val = gst_structure_id_get_value (structure, GST_QUARK (POSITION)); + if (position != NULL) + *position = g_value_get_int64 (val); +}