gst/gstevent.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wim.taymans@chello.be>
   4  *                    2005 Wim Taymans <wim@fluendo.com>
   5  *
   6  * gstevent.c: GstEvent subsystem
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  21  * Boston, MA 02110-1301, USA.
  22  */
  23
  24 /**
  25  * SECTION:gstevent
  26  * @short_description: Structure describing events that are passed up and down
  27  *                     a pipeline
  28  * @see_also: #GstPad, #GstElement
  29  *
  30  * The event class provides factory methods to construct events for sending
  31  * and functions to query (parse) received events.
  32  *
  33  * Events are usually created with gst_event_new_*() which takes event-type
  34  * specific parameters as arguments.
  35  * To send an event application will usually use gst_element_send_event() and
  36  * elements will use gst_pad_send_event() or gst_pad_push_event().
  37  * The event should be unreffed with gst_event_unref() if it has not been sent.
  38  *
  39  * Events that have been received can be parsed with their respective
  40  * gst_event_parse_*() functions. It is valid to pass %NULL for unwanted details.
  41  *
  42  * Events are passed between elements in parallel to the data stream. Some events
  43  * are serialized with buffers, others are not. Some events only travel downstream,
  44  * others only upstream. Some events can travel both upstream and downstream.
  45  *
  46  * The events are used to signal special conditions in the datastream such as
  47  * EOS (end of stream) or the start of a new stream-segment.
  48  * Events are also used to flush the pipeline of any pending data.
  49  *
  50  * Most of the event API is used inside plugins. Applications usually only
  51  * construct and use seek events.
  52  * To do that gst_event_new_seek() is used to create a seek event. It takes
  53  * the needed parameters to specify seeking time and mode.
  54  * [[
  55  *   GstEvent *event;
  56  *   gboolean result;
  57  *   ...
  58  *   // construct a seek event to play the media from second 2 to 5, flush
  59  *   // the pipeline to decrease latency.
  60  *   event = gst_event_new_seek (1.0,
  61  *      GST_FORMAT_TIME,
  62  *      GST_SEEK_FLAG_FLUSH,
  63  *      GST_SEEK_TYPE_SET, 2 * GST_SECOND,
  64  *      GST_SEEK_TYPE_SET, 5 * GST_SECOND);
  65  *   ...
  66  *   result = gst_element_send_event (pipeline, event);
  67  *   if (!result)
  68  *     g_warning ("seek failed");
  69  *   ...
  70  * ]|
  71  *
  72  * Last reviewed on 2012-03-28 (0.11.3)
  73  */
  74
  75
  76 #include "gst_private.h"
  77 #include <string.h>             /* memcpy */
  78
  79 #include "gstinfo.h"
  80 #include "gstevent.h"
  81 #include "gstenumtypes.h"
  82 #include "gstutils.h"
  83 #include "gstquark.h"
  84 #include "gstvalue.h"
  85
  86 GType _gst_event_type = 0;
  87
  88 typedef struct
  89 {
  90   GstEvent event;
  91
  92   GstStructure *structure;
  93 } GstEventImpl;
  94
  95 #define GST_EVENT_STRUCTURE(e)  (((GstEventImpl *)(e))->structure)
  96
  97 typedef struct
  98 {
  99   const gint type;
 100   const gchar *name;
 101   GQuark quark;
 102 } GstEventQuarks;
 103
 104 static GstEventQuarks event_quarks[] = {
 105   {GST_EVENT_UNKNOWN, "unknown", 0},
 106   {GST_EVENT_FLUSH_START, "flush-start", 0},
 107   {GST_EVENT_FLUSH_STOP, "flush-stop", 0},
 108   {GST_EVENT_STREAM_START, "stream-start", 0},
 109   {GST_EVENT_CAPS, "caps", 0},
 110   {GST_EVENT_SEGMENT, "segment", 0},
 111   {GST_EVENT_TAG, "tag", 0},
 112   {GST_EVENT_TOC, "toc", 0},
 113   {GST_EVENT_BUFFERSIZE, "buffersize", 0},
 114   {GST_EVENT_SINK_MESSAGE, "sink-message", 0},
 115   {GST_EVENT_EOS, "eos", 0},
 116   {GST_EVENT_SEGMENT_DONE, "segment-done", 0},
 117   {GST_EVENT_GAP, "gap", 0},
 118   {GST_EVENT_QOS, "qos", 0},
 119   {GST_EVENT_SEEK, "seek", 0},
 120   {GST_EVENT_NAVIGATION, "navigation", 0},
 121   {GST_EVENT_LATENCY, "latency", 0},
 122   {GST_EVENT_STEP, "step", 0},
 123   {GST_EVENT_RECONFIGURE, "reconfigure", 0},
 124   {GST_EVENT_TOC_SELECT, "toc-select", 0},
 125   {GST_EVENT_CUSTOM_UPSTREAM, "custom-upstream", 0},
 126   {GST_EVENT_CUSTOM_DOWNSTREAM, "custom-downstream", 0},
 127   {GST_EVENT_CUSTOM_DOWNSTREAM_OOB, "custom-downstream-oob", 0},
 128   {GST_EVENT_CUSTOM_DOWNSTREAM_STICKY, "custom-downstream-sticky", 0},
 129   {GST_EVENT_CUSTOM_BOTH, "custom-both", 0},
 130   {GST_EVENT_CUSTOM_BOTH_OOB, "custom-both-oob", 0},
 131
 132   {0, NULL, 0}
 133 };
 134
 135 GST_DEFINE_MINI_OBJECT_TYPE (GstEvent, gst_event);
 136
 137 void
 138 _priv_gst_event_initialize (void)
 139 {
 140   gint i;
 141
 142   _gst_event_type = gst_event_get_type ();
 143
 144   g_type_class_ref (gst_seek_flags_get_type ());
 145   g_type_class_ref (gst_seek_type_get_type ());
 146
 147   for (i = 0; event_quarks[i].name; i++) {
 148     event_quarks[i].quark = g_quark_from_static_string (event_quarks[i].name);
 149   }
 150 }
 151
 152 /**
 153  * gst_event_type_get_name:
 154  * @type: the event type
 155  *
 156  * Get a printable name for the given event type. Do not modify or free.
 157  *
 158  * Returns: a reference to the static name of the event.
 159  */
 160 const gchar *
 161 gst_event_type_get_name (GstEventType type)
 162 {
 163   gint i;
 164
 165   for (i = 0; event_quarks[i].name; i++) {
 166     if (type == event_quarks[i].type)
 167       return event_quarks[i].name;
 168   }
 169   return "unknown";
 170 }
 171
 172 /**
 173  * gst_event_type_to_quark:
 174  * @type: the event type
 175  *
 176  * Get the unique quark for the given event type.
 177  *
 178  * Returns: the quark associated with the event type
 179  */
 180 GQuark
 181 gst_event_type_to_quark (GstEventType type)
 182 {
 183   gint i;
 184
 185   for (i = 0; event_quarks[i].name; i++) {
 186     if (type == event_quarks[i].type)
 187       return event_quarks[i].quark;
 188   }
 189   return 0;
 190 }
 191
 192 /**
 193  * gst_event_type_get_flags:
 194  * @type: a #GstEventType
 195  *
 196  * Gets the #GstEventTypeFlags associated with @type.
 197  *
 198  * Returns: a #GstEventTypeFlags.
 199  */
 200 GstEventTypeFlags
 201 gst_event_type_get_flags (GstEventType type)
 202 {
 203   GstEventTypeFlags ret;
 204
 205   ret = type & ((1 << GST_EVENT_NUM_SHIFT) - 1);
 206
 207   return ret;
 208 }
 209
 210 static void
 211 _gst_event_free (GstEvent * event)
 212 {
 213   GstStructure *s;
 214
 215   g_return_if_fail (event != NULL);
 216   g_return_if_fail (GST_IS_EVENT (event));
 217
 218   GST_CAT_LOG (GST_CAT_EVENT, "freeing event %p type %s", event,
 219       GST_EVENT_TYPE_NAME (event));
 220
 221   s = GST_EVENT_STRUCTURE (event);
 222
 223   if (s) {
 224     gst_structure_set_parent_refcount (s, NULL);
 225     gst_structure_free (s);
 226   }
 227
 228   g_slice_free1 (sizeof (GstEventImpl), event);
 229 }
 230
 231 static void gst_event_init (GstEventImpl * event, GstEventType type);
 232
 233 static GstEvent *
 234 _gst_event_copy (GstEvent * event)
 235 {
 236   GstEventImpl *copy;
 237   GstStructure *s;
 238
 239   copy = g_slice_new0 (GstEventImpl);
 240
 241   gst_event_init (copy, GST_EVENT_TYPE (event));
 242
 243   GST_EVENT_TIMESTAMP (copy) = GST_EVENT_TIMESTAMP (event);
 244   GST_EVENT_SEQNUM (copy) = GST_EVENT_SEQNUM (event);
 245
 246   s = GST_EVENT_STRUCTURE (event);
 247   if (s) {
 248     GST_EVENT_STRUCTURE (copy) = gst_structure_copy (s);
 249     gst_structure_set_parent_refcount (GST_EVENT_STRUCTURE (copy),
 250         &copy->event.mini_object.refcount);
 251   } else {
 252     GST_EVENT_STRUCTURE (copy) = NULL;
 253   }
 254   return GST_EVENT_CAST (copy);
 255 }
 256
 257 static void
 258 gst_event_init (GstEventImpl * event, GstEventType type)
 259 {
 260   gst_mini_object_init (GST_MINI_OBJECT_CAST (event), 0, _gst_event_type,
 261       (GstMiniObjectCopyFunction) _gst_event_copy, NULL,
 262       (GstMiniObjectFreeFunction) _gst_event_free);
 263
 264   GST_EVENT_TYPE (event) = type;
 265   GST_EVENT_TIMESTAMP (event) = GST_CLOCK_TIME_NONE;
 266   GST_EVENT_SEQNUM (event) = gst_util_seqnum_next ();
 267 }
 268
 269
 270 /**
 271  * gst_event_new_custom:
 272  * @type: The type of the new event
 273  * @structure: (transfer full): the structure for the event. The event will
 274  *     take ownership of the structure.
 275  *
 276  * Create a new custom-typed event. This can be used for anything not
 277  * handled by other event-specific functions to pass an event to another
 278  * element.
 279  *
 280  * Make sure to allocate an event type with the #GST_EVENT_MAKE_TYPE macro,
 281  * assigning a free number and filling in the correct direction and
 282  * serialization flags.
 283  *
 284  * New custom events can also be created by subclassing the event type if
 285  * needed.
 286  *
 287  * Returns: (transfer full): the new custom event.
 288  */
 289 GstEvent *
 290 gst_event_new_custom (GstEventType type, GstStructure * structure)
 291 {
 292   GstEventImpl *event;
 293
 294   event = g_slice_new0 (GstEventImpl);
 295
 296   GST_CAT_DEBUG (GST_CAT_EVENT, "creating new event %p %s %d", event,
 297       gst_event_type_get_name (type), type);
 298
 299   if (structure) {
 300     /* structure must not have a parent */
 301     if (!gst_structure_set_parent_refcount (structure,
 302             &event->event.mini_object.refcount))
 303       goto had_parent;
 304
 305   }
 306   gst_event_init (event, type);
 307
 308   GST_EVENT_STRUCTURE (event) = structure;
 309
 310   return GST_EVENT_CAST (event);
 311
 312   /* ERRORS */
 313 had_parent:
 314   {
 315     g_slice_free1 (sizeof (GstEventImpl), event);
 316     g_warning ("structure is already owned by another object");
 317     return NULL;
 318   }
 319 }
 320
 321 /**
 322  * gst_event_get_structure:
 323  * @event: The #GstEvent.
 324  *
 325  * Access the structure of the event.
 326  *
 327  * Returns: The structure of the event. The structure is still
 328  * owned by the event, which means that you should not free it and
 329  * that the pointer becomes invalid when you free the event.
 330  *
 331  * MT safe.
 332  */
 333 const GstStructure *
 334 gst_event_get_structure (GstEvent * event)
 335 {
 336   g_return_val_if_fail (GST_IS_EVENT (event), NULL);
 337
 338   return GST_EVENT_STRUCTURE (event);
 339 }
 340
 341 /**
 342  * gst_event_writable_structure:
 343  * @event: The #GstEvent.
 344  *
 345  * Get a writable version of the structure.
 346  *
 347  * Returns: The structure of the event. The structure is still
 348  * owned by the event, which means that you should not free it and
 349  * that the pointer becomes invalid when you free the event.
 350  * This function checks if @event is writable and will never return NULL.
 351  *
 352  * MT safe.
 353  */
 354 GstStructure *
 355 gst_event_writable_structure (GstEvent * event)
 356 {
 357   GstStructure *structure;
 358
 359   g_return_val_if_fail (GST_IS_EVENT (event), NULL);
 360   g_return_val_if_fail (gst_event_is_writable (event), NULL);
 361
 362   structure = GST_EVENT_STRUCTURE (event);
 363
 364   if (structure == NULL) {
 365     structure =
 366         gst_structure_new_id_empty (gst_event_type_to_quark (GST_EVENT_TYPE
 367             (event)));
 368     gst_structure_set_parent_refcount (structure, &event->mini_object.refcount);
 369     GST_EVENT_STRUCTURE (event) = structure;
 370   }
 371   return structure;
 372 }
 373
 374 /**
 375  * gst_event_has_name:
 376  * @event: The #GstEvent.
 377  * @name: name to check
 378  *
 379  * Checks if @event has the given @name. This function is usually used to
 380  * check the name of a custom event.
 381  *
 382  * Returns: %TRUE if @name matches the name of the event structure.
 383  */
 384 gboolean
 385 gst_event_has_name (GstEvent * event, const gchar * name)
 386 {
 387   g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
 388
 389   if (GST_EVENT_STRUCTURE (event) == NULL)
 390     return FALSE;
 391
 392   return gst_structure_has_name (GST_EVENT_STRUCTURE (event), name);
 393 }
 394
 395 /**
 396  * gst_event_get_seqnum:
 397  * @event: A #GstEvent.
 398  *
 399  * Retrieve the sequence number of a event.
 400  *
 401  * Events have ever-incrementing sequence numbers, which may also be set
 402  * explicitly via gst_event_set_seqnum(). Sequence numbers are typically used to
 403  * indicate that a event corresponds to some other set of events or messages,
 404  * for example an EOS event corresponding to a SEEK event. It is considered good
 405  * practice to make this correspondence when possible, though it is not
 406  * required.
 407  *
 408  * Note that events and messages share the same sequence number incrementor;
 409  * two events or messages will never have the same sequence number unless
 410  * that correspondence was made explicitly.
 411  *
 412  * Returns: The event's sequence number.
 413  *
 414  * MT safe.
 415  */
 416 guint32
 417 gst_event_get_seqnum (GstEvent * event)
 418 {
 419   g_return_val_if_fail (GST_IS_EVENT (event), -1);
 420
 421   return GST_EVENT_SEQNUM (event);
 422 }
 423
 424 /**
 425  * gst_event_set_seqnum:
 426  * @event: A #GstEvent.
 427  * @seqnum: A sequence number.
 428  *
 429  * Set the sequence number of a event.
 430  *
 431  * This function might be called by the creator of a event to indicate that the
 432  * event relates to other events or messages. See gst_event_get_seqnum() for
 433  * more information.
 434  *
 435  * MT safe.
 436  */
 437 void
 438 gst_event_set_seqnum (GstEvent * event, guint32 seqnum)
 439 {
 440   g_return_if_fail (GST_IS_EVENT (event));
 441
 442   GST_EVENT_SEQNUM (event) = seqnum;
 443 }
 444
 445 /**
 446  * gst_event_new_flush_start:
 447  *
 448  * Allocate a new flush start event. The flush start event can be sent
 449  * upstream and downstream and travels out-of-bounds with the dataflow.
 450  *
 451  * It marks pads as being flushing and will make them return
 452  * #GST_FLOW_FLUSHING when used for data flow with gst_pad_push(),
 453  * gst_pad_chain(), gst_pad_get_range() and gst_pad_pull_range().
 454  * Any event (except a #GST_EVENT_FLUSH_STOP) received
 455  * on a flushing pad will return %FALSE immediately.
 456  *
 457  * Elements should unlock any blocking functions and exit their streaming
 458  * functions as fast as possible when this event is received.
 459  *
 460  * This event is typically generated after a seek to flush out all queued data
 461  * in the pipeline so that the new media is played as soon as possible.
 462  *
 463  * Returns: (transfer full): a new flush start event.
 464  */
 465 GstEvent *
 466 gst_event_new_flush_start (void)
 467 {
 468   return gst_event_new_custom (GST_EVENT_FLUSH_START, NULL);
 469 }
 470
 471 /**
 472  * gst_event_new_flush_stop:
 473  * @reset_time: if time should be reset
 474  *
 475  * Allocate a new flush stop event. The flush stop event can be sent
 476  * upstream and downstream and travels serialized with the dataflow.
 477  * It is typically sent after sending a FLUSH_START event to make the
 478  * pads accept data again.
 479  *
 480  * Elements can process this event synchronized with the dataflow since
 481  * the preceding FLUSH_START event stopped the dataflow.
 482  *
 483  * This event is typically generated to complete a seek and to resume
 484  * dataflow.
 485  *
 486  * Returns: (transfer full): a new flush stop event.
 487  */
 488 GstEvent *
 489 gst_event_new_flush_stop (gboolean reset_time)
 490 {
 491   GstEvent *event;
 492
 493   GST_CAT_INFO (GST_CAT_EVENT, "creating flush stop %d", reset_time);
 494
 495   event = gst_event_new_custom (GST_EVENT_FLUSH_STOP,
 496       gst_structure_new_id (GST_QUARK (EVENT_FLUSH_STOP),
 497           GST_QUARK (RESET_TIME), G_TYPE_BOOLEAN, reset_time, NULL));
 498
 499   return event;
 500 }
 501
 502 /**
 503  * gst_event_parse_flush_stop:
 504  * @event: The event to parse
 505  * @reset_time: (out): if time should be reset
 506  *
 507  * Parse the FLUSH_STOP event and retrieve the @reset_time member.
 508  */
 509 void
 510 gst_event_parse_flush_stop (GstEvent * event, gboolean * reset_time)
 511 {
 512   GstStructure *structure;
 513
 514   g_return_if_fail (GST_IS_EVENT (event));
 515   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_FLUSH_STOP);
 516
 517   structure = GST_EVENT_STRUCTURE (event);
 518   if (G_LIKELY (reset_time))
 519     *reset_time =
 520         g_value_get_boolean (gst_structure_id_get_value (structure,
 521             GST_QUARK (RESET_TIME)));
 522 }
 523
 524 /**
 525  * gst_event_new_eos:
 526  *
 527  * Create a new EOS event. The eos event can only travel downstream
 528  * synchronized with the buffer flow. Elements that receive the EOS
 529  * event on a pad can return #GST_FLOW_EOS as a #GstFlowReturn
 530  * when data after the EOS event arrives.
 531  *
 532  * The EOS event will travel down to the sink elements in the pipeline
 533  * which will then post the #GST_MESSAGE_EOS on the bus after they have
 534  * finished playing any buffered data.
 535  *
 536  * When all sinks have posted an EOS message, an EOS message is
 537  * forwarded to the application.
 538  *
 539  * The EOS event itself will not cause any state transitions of the pipeline.
 540  *
 541  * Returns: (transfer full): the new EOS event.
 542  */
 543 GstEvent *
 544 gst_event_new_eos (void)
 545 {
 546   return gst_event_new_custom (GST_EVENT_EOS, NULL);
 547 }
 548
 549 /**
 550  * gst_event_new_gap:
 551  * @timestamp: the start time (pts) of the gap
 552  * @duration: the duration of the gap
 553  *
 554  * Create a new GAP event. A gap event can be thought of as conceptually
 555  * equivalent to a buffer to signal that there is no data for a certain
 556  * amount of time. This is useful to signal a gap to downstream elements
 557  * which may wait for data, such as muxers or mixers or overlays, especially
 558  * for sparse streams such as subtitle streams.
 559  *
 560  * Returns: (transfer full): the new GAP event.
 561  */
 562 GstEvent *
 563 gst_event_new_gap (GstClockTime timestamp, GstClockTime duration)
 564 {
 565   GstEvent *event;
 566
 567   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), NULL);
 568
 569   GST_CAT_TRACE (GST_CAT_EVENT, "creating gap %" GST_TIME_FORMAT " - "
 570       "%" GST_TIME_FORMAT " (duration: %" GST_TIME_FORMAT ")",
 571       GST_TIME_ARGS (timestamp), GST_TIME_ARGS (timestamp + duration),
 572       GST_TIME_ARGS (duration));
 573
 574   event = gst_event_new_custom (GST_EVENT_GAP,
 575       gst_structure_new_id (GST_QUARK (EVENT_GAP),
 576           GST_QUARK (TIMESTAMP), GST_TYPE_CLOCK_TIME, timestamp,
 577           GST_QUARK (DURATION), GST_TYPE_CLOCK_TIME, duration, NULL));
 578
 579   return event;
 580 }
 581
 582 /**
 583  * gst_event_parse_gap:
 584  * @event: a #GstEvent of type #GST_EVENT_GAP
 585  * @timestamp: (out) (allow-none): location where to store the
 586  *     start time (pts) of the gap, or %NULL
 587  * @duration: (out) (allow-none): location where to store the duration of
 588  *     the gap, or %NULL
 589  *
 590  * Extract timestamp and duration from a new GAP event.
 591  */
 592 void
 593 gst_event_parse_gap (GstEvent * event, GstClockTime * timestamp,
 594     GstClockTime * duration)
 595 {
 596   GstStructure *structure;
 597
 598   g_return_if_fail (GST_IS_EVENT (event));
 599   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_GAP);
 600
 601   structure = GST_EVENT_STRUCTURE (event);
 602   gst_structure_id_get (structure,
 603       GST_QUARK (TIMESTAMP), GST_TYPE_CLOCK_TIME, timestamp,
 604       GST_QUARK (DURATION), GST_TYPE_CLOCK_TIME, duration, NULL);
 605 }
 606
 607 /**
 608  * gst_event_new_caps:
 609  * @caps: (transfer none): a #GstCaps
 610  *
 611  * Create a new CAPS event for @caps. The caps event can only travel downstream
 612  * synchronized with the buffer flow and contains the format of the buffers
 613  * that will follow after the event.
 614  *
 615  * Returns: (transfer full): the new CAPS event.
 616  */
 617 GstEvent *
 618 gst_event_new_caps (GstCaps * caps)
 619 {
 620   GstEvent *event;
 621
 622   g_return_val_if_fail (caps != NULL, NULL);
 623   g_return_val_if_fail (gst_caps_is_fixed (caps), NULL);
 624
 625   GST_CAT_INFO (GST_CAT_EVENT, "creating caps event %" GST_PTR_FORMAT, caps);
 626
 627   event = gst_event_new_custom (GST_EVENT_CAPS,
 628       gst_structure_new_id (GST_QUARK (EVENT_CAPS),
 629           GST_QUARK (CAPS), GST_TYPE_CAPS, caps, NULL));
 630
 631   return event;
 632 }
 633
 634 /**
 635  * gst_event_parse_caps:
 636  * @event: The event to parse
 637  * @caps: (out) (transfer none): A pointer to the caps
 638  *
 639  * Get the caps from @event. The caps remains valid as long as @event remains
 640  * valid.
 641  */
 642 void
 643 gst_event_parse_caps (GstEvent * event, GstCaps ** caps)
 644 {
 645   GstStructure *structure;
 646
 647   g_return_if_fail (GST_IS_EVENT (event));
 648   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_CAPS);
 649
 650   structure = GST_EVENT_STRUCTURE (event);
 651   if (G_LIKELY (caps))
 652     *caps =
 653         g_value_get_boxed (gst_structure_id_get_value (structure,
 654             GST_QUARK (CAPS)));
 655 }
 656
 657 /**
 658  * gst_event_new_segment:
 659  * @segment: (transfer none): a #GstSegment
 660  *
 661  * Create a new SEGMENT event for @segment. The segment event can only travel
 662  * downstream synchronized with the buffer flow and contains timing information
 663  * and playback properties for the buffers that will follow.
 664  *
 665  * The newsegment event marks the range of buffers to be processed. All
 666  * data not within the segment range is not to be processed. This can be
 667  * used intelligently by plugins to apply more efficient methods of skipping
 668  * unneeded data. The valid range is expressed with the @start and @stop
 669  * values.
 670  *
 671  * The time value of the segment is used in conjunction with the start
 672  * value to convert the buffer timestamps into the stream time. This is
 673  * usually done in sinks to report the current stream_time.
 674  * @time represents the stream_time of a buffer carrying a timestamp of
 675  * @start. @time cannot be -1.
 676  *
 677  * @start cannot be -1, @stop can be -1. If there
 678  * is a valid @stop given, it must be greater or equal the @start, including
 679  * when the indicated playback @rate is < 0.
 680  *
 681  * The @applied_rate value provides information about any rate adjustment that
 682  * has already been made to the timestamps and content on the buffers of the
 683  * stream. (@rate * @applied_rate) should always equal the rate that has been
 684  * requested for playback. For example, if an element has an input segment
 685  * with intended playback @rate of 2.0 and applied_rate of 1.0, it can adjust
 686  * incoming timestamps and buffer content by half and output a newsegment event
 687  * with @rate of 1.0 and @applied_rate of 2.0
 688  *
 689  * After a newsegment event, the buffer stream time is calculated with:
 690  *
 691  *   time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate)
 692  *
 693  * Returns: (transfer full): the new SEGMENT event.
 694  */
 695 GstEvent *
 696 gst_event_new_segment (const GstSegment * segment)
 697 {
 698   GstEvent *event;
 699
 700   g_return_val_if_fail (segment != NULL, NULL);
 701   g_return_val_if_fail (segment->rate != 0.0, NULL);
 702   g_return_val_if_fail (segment->applied_rate != 0.0, NULL);
 703   g_return_val_if_fail (segment->format != GST_FORMAT_UNDEFINED, NULL);
 704
 705   GST_CAT_INFO (GST_CAT_EVENT, "creating segment event %" GST_SEGMENT_FORMAT,
 706       segment);
 707
 708   event = gst_event_new_custom (GST_EVENT_SEGMENT,
 709       gst_structure_new_id (GST_QUARK (EVENT_SEGMENT),
 710           GST_QUARK (SEGMENT), GST_TYPE_SEGMENT, segment, NULL));
 711
 712   return event;
 713 }
 714
 715 /**
 716  * gst_event_parse_segment:
 717  * @event: The event to parse
 718  * @segment: (out) (transfer none): a pointer to a #GstSegment
 719  *
 720  * Parses a segment @event and stores the result in the given @segment location.
 721  * @segment remains valid only until the @event is freed. Don't modify the segment
 722  * and make a copy if you want to modify it or store it for later use.
 723  */
 724 void
 725 gst_event_parse_segment (GstEvent * event, const GstSegment ** segment)
 726 {
 727   GstStructure *structure;
 728
 729   g_return_if_fail (GST_IS_EVENT (event));
 730   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_SEGMENT);
 731
 732   if (segment) {
 733     structure = GST_EVENT_STRUCTURE (event);
 734     *segment = g_value_get_boxed (gst_structure_id_get_value (structure,
 735             GST_QUARK (SEGMENT)));
 736   }
 737 }
 738
 739 /**
 740  * gst_event_copy_segment:
 741  * @event: The event to parse
 742  * @segment: a pointer to a #GstSegment
 743  *
 744  * Parses a segment @event and copies the #GstSegment into the location
 745  * given by @segment.
 746  */
 747 void
 748 gst_event_copy_segment (GstEvent * event, GstSegment * segment)
 749 {
 750   const GstSegment *src;
 751
 752   g_return_if_fail (GST_IS_EVENT (event));
 753   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_SEGMENT);
 754
 755   if (segment) {
 756     gst_event_parse_segment (event, &src);
 757     gst_segment_copy_into (src, segment);
 758   }
 759 }
 760
 761 /**
 762  * gst_event_new_tag:
 763  * @taglist: (transfer full): metadata list. The event will take ownership
 764  *     of the taglist.
 765  *
 766  * Generates a metadata tag event from the given @taglist.
 767  *
 768  * The scope of the taglist specifies if the taglist applies to the
 769  * complete medium or only to this specific stream. As the tag event
 770  * is a sticky event, elements should merge tags received from
 771  * upstream with a given scope with their own tags with the same
 772  * scope and create a new tag event from it.
 773  *
 774  * Returns: (transfer full): a new #GstEvent
 775  */
 776 GstEvent *
 777 gst_event_new_tag (GstTagList * taglist)
 778 {
 779   GstStructure *s;
 780   GValue val = G_VALUE_INIT;
 781   const gchar *names[] = { "GstTagList-stream", "GstTagList-global" };
 782
 783   g_return_val_if_fail (taglist != NULL, NULL);
 784
 785   s = gst_structure_new_empty (names[gst_tag_list_get_scope (taglist)]);
 786   g_value_init (&val, GST_TYPE_TAG_LIST);
 787   g_value_take_boxed (&val, taglist);
 788   gst_structure_id_take_value (s, GST_QUARK (TAGLIST), &val);
 789   return gst_event_new_custom (GST_EVENT_TAG, s);
 790 }
 791
 792 /**
 793  * gst_event_parse_tag:
 794  * @event: a tag event
 795  * @taglist: (out) (transfer none): pointer to metadata list
 796  *
 797  * Parses a tag @event and stores the results in the given @taglist location.
 798  * No reference to the taglist will be returned, it remains valid only until
 799  * the @event is freed. Don't modify or free the taglist, make a copy if you
 800  * want to modify it or store it for later use.
 801  */
 802 void
 803 gst_event_parse_tag (GstEvent * event, GstTagList ** taglist)
 804 {
 805   const GValue *val;
 806
 807   g_return_if_fail (GST_IS_EVENT (event));
 808   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_TAG);
 809
 810   val = gst_structure_id_get_value (GST_EVENT_STRUCTURE (event),
 811       GST_QUARK (TAGLIST));
 812
 813   if (taglist)
 814     *taglist = (GstTagList *) g_value_get_boxed (val);
 815 }
 816
 817 /* buffersize event */
 818 /**
 819  * gst_event_new_buffer_size:
 820  * @format: buffer format
 821  * @minsize: minimum buffer size
 822  * @maxsize: maximum buffer size
 823  * @async: thread behavior
 824  *
 825  * Create a new buffersize event. The event is sent downstream and notifies
 826  * elements that they should provide a buffer of the specified dimensions.
 827  *
 828  * When the @async flag is set, a thread boundary is preferred.
 829  *
 830  * Returns: (transfer full): a new #GstEvent
 831  */
 832 GstEvent *
 833 gst_event_new_buffer_size (GstFormat format, gint64 minsize,
 834     gint64 maxsize, gboolean async)
 835 {
 836   GstEvent *event;
 837   GstStructure *structure;
 838
 839   GST_CAT_INFO (GST_CAT_EVENT,
 840       "creating buffersize format %s, minsize %" G_GINT64_FORMAT
 841       ", maxsize %" G_GINT64_FORMAT ", async %d", gst_format_get_name (format),
 842       minsize, maxsize, async);
 843
 844   structure = gst_structure_new_id (GST_QUARK (EVENT_BUFFER_SIZE),
 845       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 846       GST_QUARK (MINSIZE), G_TYPE_INT64, minsize,
 847       GST_QUARK (MAXSIZE), G_TYPE_INT64, maxsize,
 848       GST_QUARK (ASYNC), G_TYPE_BOOLEAN, async, NULL);
 849   event = gst_event_new_custom (GST_EVENT_BUFFERSIZE, structure);
 850
 851   return event;
 852 }
 853
 854 /**
 855  * gst_event_parse_buffer_size:
 856  * @event: The event to query
 857  * @format: (out): A pointer to store the format in
 858  * @minsize: (out): A pointer to store the minsize in
 859  * @maxsize: (out): A pointer to store the maxsize in
 860  * @async: (out): A pointer to store the async-flag in
 861  *
 862  * Get the format, minsize, maxsize and async-flag in the buffersize event.
 863  */
 864 void
 865 gst_event_parse_buffer_size (GstEvent * event, GstFormat * format,
 866     gint64 * minsize, gint64 * maxsize, gboolean * async)
 867 {
 868   const GstStructure *structure;
 869
 870   g_return_if_fail (GST_IS_EVENT (event));
 871   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_BUFFERSIZE);
 872
 873   structure = GST_EVENT_STRUCTURE (event);
 874   if (format)
 875     *format = (GstFormat)
 876         g_value_get_enum (gst_structure_id_get_value (structure,
 877             GST_QUARK (FORMAT)));
 878   if (minsize)
 879     *minsize =
 880         g_value_get_int64 (gst_structure_id_get_value (structure,
 881             GST_QUARK (MINSIZE)));
 882   if (maxsize)
 883     *maxsize =
 884         g_value_get_int64 (gst_structure_id_get_value (structure,
 885             GST_QUARK (MAXSIZE)));
 886   if (async)
 887     *async =
 888         g_value_get_boolean (gst_structure_id_get_value (structure,
 889             GST_QUARK (ASYNC)));
 890 }
 891
 892 /**
 893  * gst_event_new_qos:
 894  * @type: the QoS type
 895  * @proportion: the proportion of the qos message
 896  * @diff: The time difference of the last Clock sync
 897  * @timestamp: The timestamp of the buffer
 898  *
 899  * Allocate a new qos event with the given values.
 900  * The QOS event is generated in an element that wants an upstream
 901  * element to either reduce or increase its rate because of
 902  * high/low CPU load or other resource usage such as network performance or
 903  * throttling. Typically sinks generate these events for each buffer
 904  * they receive.
 905  *
 906  * @type indicates the reason for the QoS event. #GST_QOS_TYPE_OVERFLOW is
 907  * used when a buffer arrived in time or when the sink cannot keep up with
 908  * the upstream datarate. #GST_QOS_TYPE_UNDERFLOW is when the sink is not
 909  * receiving buffers fast enough and thus has to drop late buffers.
 910  * #GST_QOS_TYPE_THROTTLE is used when the datarate is artificially limited
 911  * by the application, for example to reduce power consumption.
 912  *
 913  * @proportion indicates the real-time performance of the streaming in the
 914  * element that generated the QoS event (usually the sink). The value is
 915  * generally computed based on more long term statistics about the streams
 916  * timestamps compared to the clock.
 917  * A value < 1.0 indicates that the upstream element is producing data faster
 918  * than real-time. A value > 1.0 indicates that the upstream element is not
 919  * producing data fast enough. 1.0 is the ideal @proportion value. The
 920  * proportion value can safely be used to lower or increase the quality of
 921  * the element.
 922  *
 923  * @diff is the difference against the clock in running time of the last
 924  * buffer that caused the element to generate the QOS event. A negative value
 925  * means that the buffer with @timestamp arrived in time. A positive value
 926  * indicates how late the buffer with @timestamp was. When throttling is
 927  * enabled, @diff will be set to the requested throttling interval.
 928  *
 929  * @timestamp is the timestamp of the last buffer that cause the element
 930  * to generate the QOS event. It is expressed in running time and thus an ever
 931  * increasing value.
 932  *
 933  * The upstream element can use the @diff and @timestamp values to decide
 934  * whether to process more buffers. For positive @diff, all buffers with
 935  * timestamp <= @timestamp + @diff will certainly arrive late in the sink
 936  * as well. A (negative) @diff value so that @timestamp + @diff would yield a
 937  * result smaller than 0 is not allowed.
 938  *
 939  * The application can use general event probes to intercept the QoS
 940  * event and implement custom application specific QoS handling.
 941  *
 942  * Returns: (transfer full): a new QOS event.
 943  */
 944 GstEvent *
 945 gst_event_new_qos (GstQOSType type, gdouble proportion,
 946     GstClockTimeDiff diff, GstClockTime timestamp)
 947 {
 948   GstEvent *event;
 949   GstStructure *structure;
 950
 951   /* diff must be positive or timestamp + diff must be positive */
 952   g_return_val_if_fail (diff >= 0 || -diff <= timestamp, NULL);
 953
 954   GST_CAT_LOG (GST_CAT_EVENT,
 955       "creating qos type %d, proportion %lf, diff %" G_GINT64_FORMAT
 956       ", timestamp %" GST_TIME_FORMAT, type, proportion,
 957       diff, GST_TIME_ARGS (timestamp));
 958
 959   structure = gst_structure_new_id (GST_QUARK (EVENT_QOS),
 960       GST_QUARK (TYPE), GST_TYPE_QOS_TYPE, type,
 961       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
 962       GST_QUARK (DIFF), G_TYPE_INT64, diff,
 963       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp, NULL);
 964   event = gst_event_new_custom (GST_EVENT_QOS, structure);
 965
 966   return event;
 967 }
 968
 969 /**
 970  * gst_event_parse_qos:
 971  * @event: The event to query
 972  * @type: (out): A pointer to store the QoS type in
 973  * @proportion: (out): A pointer to store the proportion in
 974  * @diff: (out): A pointer to store the diff in
 975  * @timestamp: (out): A pointer to store the timestamp in
 976  *
 977  * Get the type, proportion, diff and timestamp in the qos event. See
 978  * gst_event_new_qos() for more information about the different QoS values.
 979  */
 980 void
 981 gst_event_parse_qos (GstEvent * event, GstQOSType * type,
 982     gdouble * proportion, GstClockTimeDiff * diff, GstClockTime * timestamp)
 983 {
 984   const GstStructure *structure;
 985
 986   g_return_if_fail (GST_IS_EVENT (event));
 987   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_QOS);
 988
 989   structure = GST_EVENT_STRUCTURE (event);
 990   if (type)
 991     *type = (GstQOSType)
 992         g_value_get_enum (gst_structure_id_get_value (structure,
 993             GST_QUARK (TYPE)));
 994   if (proportion)
 995     *proportion =
 996         g_value_get_double (gst_structure_id_get_value (structure,
 997             GST_QUARK (PROPORTION)));
 998   if (diff)
 999     *diff =
1000         g_value_get_int64 (gst_structure_id_get_value (structure,
1001             GST_QUARK (DIFF)));
1002   if (timestamp)
1003     *timestamp =
1004         g_value_get_uint64 (gst_structure_id_get_value (structure,
1005             GST_QUARK (TIMESTAMP)));
1006 }
1007
1008 /**
1009  * gst_event_new_seek:
1010  * @rate: The new playback rate
1011  * @format: The format of the seek values
1012  * @flags: The optional seek flags
1013  * @start_type: The type and flags for the new start position
1014  * @start: The value of the new start position
1015  * @stop_type: The type and flags for the new stop position
1016  * @stop: The value of the new stop position
1017  *
1018  * Allocate a new seek event with the given parameters.
1019  *
1020  * The seek event configures playback of the pipeline between @start to @stop
1021  * at the speed given in @rate, also called a playback segment.
1022  * The @start and @stop values are expressed in @format.
1023  *
1024  * A @rate of 1.0 means normal playback rate, 2.0 means double speed.
1025  * Negatives values means backwards playback. A value of 0.0 for the
1026  * rate is not allowed and should be accomplished instead by PAUSING the
1027  * pipeline.
1028  *
1029  * A pipeline has a default playback segment configured with a start
1030  * position of 0, a stop position of -1 and a rate of 1.0. The currently
1031  * configured playback segment can be queried with #GST_QUERY_SEGMENT.
1032  *
1033  * @start_type and @stop_type specify how to adjust the currently configured
1034  * start and stop fields in playback segment. Adjustments can be made relative
1035  * or absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE
1036  * means that the position should not be updated.
1037  *
1038  * When the rate is positive and @start has been updated, playback will start
1039  * from the newly configured start position.
1040  *
1041  * For negative rates, playback will start from the newly configured stop
1042  * position (if any). If the stop position is updated, it must be different from
1043  * -1 (#GST_CLOCK_TIME_NONE) for negative rates.
1044  *
1045  * It is not possible to seek relative to the current playback position, to do
1046  * this, PAUSE the pipeline, query the current playback position with
1047  * #GST_QUERY_POSITION and update the playback segment current position with a
1048  * #GST_SEEK_TYPE_SET to the desired position.
1049  *
1050  * Returns: (transfer full): a new seek event.
1051  */
1052 GstEvent *
1053 gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags,
1054     GstSeekType start_type, gint64 start, GstSeekType stop_type, gint64 stop)
1055 {
1056   GstEvent *event;
1057   GstStructure *structure;
1058
1059   g_return_val_if_fail (rate != 0.0, NULL);
1060
1061   if (format == GST_FORMAT_TIME) {
1062     GST_CAT_INFO (GST_CAT_EVENT,
1063         "creating seek rate %lf, format TIME, flags %d, "
1064         "start_type %d, start %" GST_TIME_FORMAT ", "
1065         "stop_type %d, stop %" GST_TIME_FORMAT,
1066         rate, flags, start_type, GST_TIME_ARGS (start),
1067         stop_type, GST_TIME_ARGS (stop));
1068   } else {
1069     GST_CAT_INFO (GST_CAT_EVENT,
1070         "creating seek rate %lf, format %s, flags %d, "
1071         "start_type %d, start %" G_GINT64_FORMAT ", "
1072         "stop_type %d, stop %" G_GINT64_FORMAT,
1073         rate, gst_format_get_name (format), flags, start_type, start, stop_type,
1074         stop);
1075   }
1076
1077   structure = gst_structure_new_id (GST_QUARK (EVENT_SEEK),
1078       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1079       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1080       GST_QUARK (FLAGS), GST_TYPE_SEEK_FLAGS, flags,
1081       GST_QUARK (CUR_TYPE), GST_TYPE_SEEK_TYPE, start_type,
1082       GST_QUARK (CUR), G_TYPE_INT64, start,
1083       GST_QUARK (STOP_TYPE), GST_TYPE_SEEK_TYPE, stop_type,
1084       GST_QUARK (STOP), G_TYPE_INT64, stop, NULL);
1085   event = gst_event_new_custom (GST_EVENT_SEEK, structure);
1086
1087   return event;
1088 }
1089
1090 /**
1091  * gst_event_parse_seek:
1092  * @event: a seek event
1093  * @rate: (out): result location for the rate
1094  * @format: (out): result location for the stream format
1095  * @flags:  (out): result location for the #GstSeekFlags
1096  * @start_type: (out): result location for the #GstSeekType of the start position
1097  * @start: (out): result location for the start position expressed in @format
1098  * @stop_type:  (out): result location for the #GstSeekType of the stop position
1099  * @stop: (out): result location for the stop position expressed in @format
1100  *
1101  * Parses a seek @event and stores the results in the given result locations.
1102  */
1103 void
1104 gst_event_parse_seek (GstEvent * event, gdouble * rate,
1105     GstFormat * format, GstSeekFlags * flags, GstSeekType * start_type,
1106     gint64 * start, GstSeekType * stop_type, gint64 * stop)
1107 {
1108   const GstStructure *structure;
1109
1110   g_return_if_fail (GST_IS_EVENT (event));
1111   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_SEEK);
1112
1113   structure = GST_EVENT_STRUCTURE (event);
1114   if (rate)
1115     *rate =
1116         g_value_get_double (gst_structure_id_get_value (structure,
1117             GST_QUARK (RATE)));
1118   if (format)
1119     *format = (GstFormat)
1120         g_value_get_enum (gst_structure_id_get_value (structure,
1121             GST_QUARK (FORMAT)));
1122   if (flags)
1123     *flags = (GstSeekFlags)
1124         g_value_get_flags (gst_structure_id_get_value (structure,
1125             GST_QUARK (FLAGS)));
1126   if (start_type)
1127     *start_type = (GstSeekType)
1128         g_value_get_enum (gst_structure_id_get_value (structure,
1129             GST_QUARK (CUR_TYPE)));
1130   if (start)
1131     *start =
1132         g_value_get_int64 (gst_structure_id_get_value (structure,
1133             GST_QUARK (CUR)));
1134   if (stop_type)
1135     *stop_type = (GstSeekType)
1136         g_value_get_enum (gst_structure_id_get_value (structure,
1137             GST_QUARK (STOP_TYPE)));
1138   if (stop)
1139     *stop =
1140         g_value_get_int64 (gst_structure_id_get_value (structure,
1141             GST_QUARK (STOP)));
1142 }
1143
1144 /**
1145  * gst_event_new_navigation:
1146  * @structure: (transfer full): description of the event. The event will take
1147  *     ownership of the structure.
1148  *
1149  * Create a new navigation event from the given description.
1150  *
1151  * Returns: (transfer full): a new #GstEvent
1152  */
1153 GstEvent *
1154 gst_event_new_navigation (GstStructure * structure)
1155 {
1156   g_return_val_if_fail (structure != NULL, NULL);
1157
1158   return gst_event_new_custom (GST_EVENT_NAVIGATION, structure);
1159 }
1160
1161 /**
1162  * gst_event_new_latency:
1163  * @latency: the new latency value
1164  *
1165  * Create a new latency event. The event is sent upstream from the sinks and
1166  * notifies elements that they should add an additional @latency to the
1167  * running time before synchronising against the clock.
1168  *
1169  * The latency is mostly used in live sinks and is always expressed in
1170  * the time format.
1171  *
1172  * Returns: (transfer full): a new #GstEvent
1173  */
1174 GstEvent *
1175 gst_event_new_latency (GstClockTime latency)
1176 {
1177   GstEvent *event;
1178   GstStructure *structure;
1179
1180   GST_CAT_INFO (GST_CAT_EVENT,
1181       "creating latency event %" GST_TIME_FORMAT, GST_TIME_ARGS (latency));
1182
1183   structure = gst_structure_new_id (GST_QUARK (EVENT_LATENCY),
1184       GST_QUARK (LATENCY), G_TYPE_UINT64, latency, NULL);
1185   event = gst_event_new_custom (GST_EVENT_LATENCY, structure);
1186
1187   return event;
1188 }
1189
1190 /**
1191  * gst_event_parse_latency:
1192  * @event: The event to query
1193  * @latency: (out): A pointer to store the latency in.
1194  *
1195  * Get the latency in the latency event.
1196  */
1197 void
1198 gst_event_parse_latency (GstEvent * event, GstClockTime * latency)
1199 {
1200   g_return_if_fail (GST_IS_EVENT (event));
1201   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_LATENCY);
1202
1203   if (latency)
1204     *latency =
1205         g_value_get_uint64 (gst_structure_id_get_value (GST_EVENT_STRUCTURE
1206             (event), GST_QUARK (LATENCY)));
1207 }
1208
1209 /**
1210  * gst_event_new_step:
1211  * @format: the format of @amount
1212  * @amount: the amount of data to step
1213  * @rate: the step rate
1214  * @flush: flushing steps
1215  * @intermediate: intermediate steps
1216  *
1217  * Create a new step event. The purpose of the step event is to instruct a sink
1218  * to skip @amount (expressed in @format) of media. It can be used to implement
1219  * stepping through the video frame by frame or for doing fast trick modes.
1220  *
1221  * A rate of <= 0.0 is not allowed. Pause the pipeline, for the effect of rate
1222  * = 0.0 or first reverse the direction of playback using a seek event to get
1223  * the same effect as rate < 0.0.
1224  *
1225  * The @flush flag will clear any pending data in the pipeline before starting
1226  * the step operation.
1227  *
1228  * The @intermediate flag instructs the pipeline that this step operation is
1229  * part of a larger step operation.
1230  *
1231  * Returns: (transfer full): a new #GstEvent
1232  */
1233 GstEvent *
1234 gst_event_new_step (GstFormat format, guint64 amount, gdouble rate,
1235     gboolean flush, gboolean intermediate)
1236 {
1237   GstEvent *event;
1238   GstStructure *structure;
1239
1240   g_return_val_if_fail (rate > 0.0, NULL);
1241
1242   GST_CAT_INFO (GST_CAT_EVENT, "creating step event");
1243
1244   structure = gst_structure_new_id (GST_QUARK (EVENT_STEP),
1245       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1246       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1247       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1248       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1249       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1250   event = gst_event_new_custom (GST_EVENT_STEP, structure);
1251
1252   return event;
1253 }
1254
1255 /**
1256  * gst_event_parse_step:
1257  * @event: The event to query
1258  * @format: (out) (allow-none): a pointer to store the format in
1259  * @amount: (out) (allow-none): a pointer to store the amount in
1260  * @rate: (out) (allow-none): a pointer to store the rate in
1261  * @flush: (out) (allow-none): a pointer to store the flush boolean in
1262  * @intermediate: (out) (allow-none): a pointer to store the intermediate
1263  *     boolean in
1264  *
1265  * Parse the step event.
1266  */
1267 void
1268 gst_event_parse_step (GstEvent * event, GstFormat * format, guint64 * amount,
1269     gdouble * rate, gboolean * flush, gboolean * intermediate)
1270 {
1271   const GstStructure *structure;
1272
1273   g_return_if_fail (GST_IS_EVENT (event));
1274   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STEP);
1275
1276   structure = GST_EVENT_STRUCTURE (event);
1277   if (format)
1278     *format =
1279         (GstFormat) g_value_get_enum (gst_structure_id_get_value (structure,
1280             GST_QUARK (FORMAT)));
1281   if (amount)
1282     *amount = g_value_get_uint64 (gst_structure_id_get_value (structure,
1283             GST_QUARK (AMOUNT)));
1284   if (rate)
1285     *rate = g_value_get_double (gst_structure_id_get_value (structure,
1286             GST_QUARK (RATE)));
1287   if (flush)
1288     *flush = g_value_get_boolean (gst_structure_id_get_value (structure,
1289             GST_QUARK (FLUSH)));
1290   if (intermediate)
1291     *intermediate = g_value_get_boolean (gst_structure_id_get_value (structure,
1292             GST_QUARK (INTERMEDIATE)));
1293 }
1294
1295 /**
1296  * gst_event_new_reconfigure:
1297
1298  * Create a new reconfigure event. The purpose of the reconfigure event is
1299  * to travel upstream and make elements renegotiate their caps or reconfigure
1300  * their buffer pools. This is useful when changing properties on elements
1301  * or changing the topology of the pipeline.
1302  *
1303  * Returns: (transfer full): a new #GstEvent
1304  */
1305 GstEvent *
1306 gst_event_new_reconfigure (void)
1307 {
1308   GstEvent *event;
1309
1310   GST_CAT_INFO (GST_CAT_EVENT, "creating reconfigure event");
1311
1312   event = gst_event_new_custom (GST_EVENT_RECONFIGURE, NULL);
1313
1314   return event;
1315 }
1316
1317 /**
1318  * gst_event_new_sink_message:
1319  * @name: a name for the event
1320  * @msg: (transfer none): the #GstMessage to be posted
1321  *
1322  * Create a new sink-message event. The purpose of the sink-message event is
1323  * to instruct a sink to post the message contained in the event synchronized
1324  * with the stream.
1325  *
1326  * @name is used to store multiple sticky events on one pad.
1327  *
1328  * Returns: (transfer full): a new #GstEvent
1329  */
1330 /* FIXME 0.11: take ownership of msg for consistency? */
1331 GstEvent *
1332 gst_event_new_sink_message (const gchar * name, GstMessage * msg)
1333 {
1334   GstEvent *event;
1335   GstStructure *structure;
1336
1337   g_return_val_if_fail (msg != NULL, NULL);
1338
1339   GST_CAT_INFO (GST_CAT_EVENT, "creating sink-message event");
1340
1341   structure = gst_structure_new_id (g_quark_from_string (name),
1342       GST_QUARK (MESSAGE), GST_TYPE_MESSAGE, msg, NULL);
1343   event = gst_event_new_custom (GST_EVENT_SINK_MESSAGE, structure);
1344
1345   return event;
1346 }
1347
1348 /**
1349  * gst_event_parse_sink_message:
1350  * @event: The event to query
1351  * @msg: (out) (transfer full): a pointer to store the #GstMessage in.
1352  *
1353  * Parse the sink-message event. Unref @msg after usage.
1354  */
1355 void
1356 gst_event_parse_sink_message (GstEvent * event, GstMessage ** msg)
1357 {
1358   const GstStructure *structure;
1359
1360   g_return_if_fail (GST_IS_EVENT (event));
1361   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_SINK_MESSAGE);
1362
1363   structure = GST_EVENT_STRUCTURE (event);
1364   if (msg)
1365     *msg =
1366         GST_MESSAGE (g_value_dup_boxed (gst_structure_id_get_value
1367             (structure, GST_QUARK (MESSAGE))));
1368 }
1369
1370 /**
1371  * gst_event_new_stream_start:
1372  * @stream_id: Identifier for this stream
1373  *
1374  * Create a new STREAM_START event. The stream start event can only
1375  * travel downstream synchronized with the buffer flow. It is expected
1376  * to be the first event that is sent for a new stream.
1377  *
1378  * Source elements, demuxers and other elements that create new streams
1379  * are supposed to send this event as the first event of a new stream. It
1380  * should not be send after a flushing seek or in similar situations
1381  * and is used to mark the beginning of a new logical stream. Elements
1382  * combining multiple streams must ensure that this event is only forwarded
1383  * downstream once and not for every single input stream.
1384  *
1385  * The @stream_id should be a unique string that consists of the upstream
1386  * stream-id, / as separator and a unique stream-id for this specific
1387  * stream. A new stream-id should only be created for a stream if the upstream
1388  * stream is split into (potentially) multiple new streams, e.g. in a demuxer,
1389  * but not for every single element in the pipeline.
1390  * gst_pad_create_stream_id() or gst_pad_create_stream_id_printf() can be
1391  * used to create a stream-id.
1392  *
1393  * Returns: (transfer full): the new STREAM_START event.
1394  */
1395 GstEvent *
1396 gst_event_new_stream_start (const gchar * stream_id)
1397 {
1398   GstStructure *s;
1399
1400   g_return_val_if_fail (stream_id != NULL, NULL);
1401
1402   s = gst_structure_new_id (GST_QUARK (EVENT_STREAM_START),
1403       GST_QUARK (STREAM_ID), G_TYPE_STRING, stream_id,
1404       GST_QUARK (FLAGS), GST_TYPE_STREAM_FLAGS, GST_STREAM_FLAG_NONE, NULL);
1405
1406   return gst_event_new_custom (GST_EVENT_STREAM_START, s);
1407 }
1408
1409 /**
1410  * gst_event_parse_stream_start:
1411  * @event: a stream-start event.
1412  * @stream_id: (out) (transfer none): pointer to store the stream-id
1413  *
1414  * Parse a stream-id @event and store the result in the given @stream_id
1415  * location. The string stored in @stream_id must not be modified and will
1416  * remain valid only until @event gets freed. Make a copy if you want to
1417  * modify it or store it for later use.
1418  */
1419 void
1420 gst_event_parse_stream_start (GstEvent * event, const gchar ** stream_id)
1421 {
1422   const GstStructure *structure;
1423   const GValue *val;
1424
1425   g_return_if_fail (event != NULL);
1426   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START);
1427
1428   structure = gst_event_get_structure (event);
1429   val = gst_structure_id_get_value (structure, GST_QUARK (STREAM_ID));
1430
1431   if (stream_id)
1432     *stream_id = g_value_get_string (val);
1433 }
1434
1435 /**
1436  * gst_event_set_stream_flags:
1437  * @event: a stream-start event
1438  * @flags: the stream flags to set
1439  *
1440  * Since: 1.2
1441  */
1442 void
1443 gst_event_set_stream_flags (GstEvent * event, GstStreamFlags flags)
1444 {
1445   g_return_if_fail (event != NULL);
1446   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START);
1447   g_return_if_fail (gst_event_is_writable (event));
1448
1449   gst_structure_id_set (GST_EVENT_STRUCTURE (event),
1450       GST_QUARK (FLAGS), GST_TYPE_STREAM_FLAGS, flags, NULL);
1451 }
1452
1453 /**
1454  * gst_event_parse_stream_flags:
1455  * @event: a stream-start event
1456  * @flags: (out): address of variable where to store the stream flags
1457  *
1458  * Since: 1.2
1459  */
1460 void
1461 gst_event_parse_stream_flags (GstEvent * event, GstStreamFlags * flags)
1462 {
1463   g_return_if_fail (event != NULL);
1464   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START);
1465
1466   if (flags) {
1467     gst_structure_id_get (GST_EVENT_STRUCTURE (event),
1468         GST_QUARK (FLAGS), GST_TYPE_STREAM_FLAGS, flags, NULL);
1469   }
1470 }
1471
1472 /**
1473  * gst_event_set_group_id:
1474  * @event: a stream-start event
1475  * @group_id: the group id to set
1476  *
1477  * All streams that have the same group id are supposed to be played
1478  * together, i.e. all streams inside a container file should have the
1479  * same group id but different stream ids. The group id should change
1480  * each time the stream is started, resulting in different group ids
1481  * each time a file is played for example.
1482  *
1483  * Use gst_util_group_id_next() to get a new group id.
1484  *
1485  * Since: 1.2
1486  */
1487 void
1488 gst_event_set_group_id (GstEvent * event, guint group_id)
1489 {
1490   g_return_if_fail (event != NULL);
1491   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START);
1492   g_return_if_fail (gst_event_is_writable (event));
1493
1494   gst_structure_id_set (GST_EVENT_STRUCTURE (event),
1495       GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id, NULL);
1496 }
1497
1498 /**
1499  * gst_event_parse_group_id:
1500  * @event: a stream-start event
1501  * @group_id: (out): address of variable where to store the group id
1502  *
1503  * Returns: %TRUE if a group id was set on the event and could be parsed,
1504  *   %FALSE otherwise.
1505  *
1506  * Since: 1.2
1507  */
1508 gboolean
1509 gst_event_parse_group_id (GstEvent * event, guint * group_id)
1510 {
1511   g_return_val_if_fail (event != NULL, FALSE);
1512   g_return_val_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_START,
1513       FALSE);
1514
1515   if (group_id) {
1516     return gst_structure_id_get (GST_EVENT_STRUCTURE (event),
1517         GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id, NULL);
1518   }
1519
1520   return TRUE;
1521 }
1522
1523 /**
1524  * gst_event_new_toc:
1525  * @toc: (transfer none): #GstToc structure.
1526  * @updated: whether @toc was updated or not.
1527  *
1528  * Generate a TOC event from the given @toc. The purpose of the TOC event is to
1529  * inform elements that some kind of the TOC was found.
1530  *
1531  * Returns: (transfer full): a new #GstEvent.
1532  */
1533 GstEvent *
1534 gst_event_new_toc (GstToc * toc, gboolean updated)
1535 {
1536   GstStructure *toc_struct;
1537   GQuark id;
1538
1539   g_return_val_if_fail (toc != NULL, NULL);
1540
1541   GST_CAT_INFO (GST_CAT_EVENT, "creating toc event");
1542
1543   /* need different structure names so sticky_multi event stuff on pads
1544    * works, i.e. both TOC events are kept around */
1545   if (gst_toc_get_scope (toc) == GST_TOC_SCOPE_GLOBAL)
1546     id = GST_QUARK (EVENT_TOC_GLOBAL);
1547   else
1548     id = GST_QUARK (EVENT_TOC_CURRENT);
1549
1550   toc_struct = gst_structure_new_id (id,
1551       GST_QUARK (TOC), GST_TYPE_TOC, toc,
1552       GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
1553
1554   return gst_event_new_custom (GST_EVENT_TOC, toc_struct);
1555 }
1556
1557 /**
1558  * gst_event_parse_toc:
1559  * @event: a TOC event.
1560  * @toc: (out) (transfer full): pointer to #GstToc structure.
1561  * @updated: (out): pointer to store TOC updated flag.
1562  *
1563  * Parse a TOC @event and store the results in the given @toc and @updated locations.
1564  */
1565 void
1566 gst_event_parse_toc (GstEvent * event, GstToc ** toc, gboolean * updated)
1567 {
1568   const GstStructure *structure;
1569
1570   g_return_if_fail (event != NULL);
1571   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_TOC);
1572   g_return_if_fail (toc != NULL);
1573
1574   structure = gst_event_get_structure (event);
1575
1576   gst_structure_id_get (structure,
1577       GST_QUARK (TOC), GST_TYPE_TOC, toc,
1578       GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
1579 }
1580
1581 /**
1582  * gst_event_new_toc_select:
1583  * @uid: UID in the TOC to start playback from.
1584  *
1585  * Generate a TOC select event with the given @uid. The purpose of the
1586  * TOC select event is to start playback based on the TOC's entry with the
1587  * given @uid.
1588  *
1589  * Returns: a new #GstEvent.
1590  */
1591 GstEvent *
1592 gst_event_new_toc_select (const gchar * uid)
1593 {
1594   GstStructure *structure;
1595
1596   g_return_val_if_fail (uid != NULL, NULL);
1597
1598   GST_CAT_INFO (GST_CAT_EVENT, "creating toc select event for UID: %s", uid);
1599
1600   structure = gst_structure_new_id (GST_QUARK (EVENT_TOC_SELECT),
1601       GST_QUARK (UID), G_TYPE_STRING, uid, NULL);
1602
1603   return gst_event_new_custom (GST_EVENT_TOC_SELECT, structure);
1604 }
1605
1606 /**
1607  * gst_event_parse_toc_select:
1608  * @event: a TOC select event.
1609  * @uid: (out): storage for the selection UID.
1610  *
1611  * Parse a TOC select @event and store the results in the given @uid location.
1612  */
1613 void
1614 gst_event_parse_toc_select (GstEvent * event, gchar ** uid)
1615 {
1616   const GstStructure *structure;
1617   const GValue *val;
1618
1619   g_return_if_fail (event != NULL);
1620   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_TOC_SELECT);
1621
1622   structure = gst_event_get_structure (event);
1623   val = gst_structure_id_get_value (structure, GST_QUARK (UID));
1624
1625   if (uid != NULL)
1626     *uid = g_strdup (g_value_get_string (val));
1627
1628 }
1629
1630 /**
1631  * gst_event_new_segment_done:
1632  * @format: The format of the position being done
1633  * @position: The position of the segment being done
1634  *
1635  * Create a new segment-done event. This event is sent by elements that
1636  * finish playback of a segment as a result of a segment seek.
1637  *
1638  * Returns: (transfer full): a new #GstEvent
1639  */
1640 GstEvent *
1641 gst_event_new_segment_done (GstFormat format, gint64 position)
1642 {
1643   GstEvent *event;
1644   GstStructure *structure;
1645
1646   GST_CAT_INFO (GST_CAT_EVENT, "creating segment-done event");
1647
1648   structure = gst_structure_new_id (GST_QUARK (EVENT_SEGMENT_DONE),
1649       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1650       GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
1651
1652   event = gst_event_new_custom (GST_EVENT_SEGMENT_DONE, structure);
1653
1654   return event;
1655 }
1656
1657 /**
1658  * gst_event_parse_segment_done:
1659  * @event: A valid #GstEvent of type GST_EVENT_SEGMENT_DONE.
1660  * @format: (out) (allow-none): Result location for the format, or NULL
1661  * @position: (out) (allow-none): Result location for the position, or NULL
1662  *
1663  * Extracts the position and format from the segment done message.
1664  *
1665  */
1666 void
1667 gst_event_parse_segment_done (GstEvent * event, GstFormat * format,
1668     gint64 * position)
1669 {
1670   const GstStructure *structure;
1671   const GValue *val;
1672
1673   g_return_if_fail (event != NULL);
1674   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_SEGMENT_DONE);
1675
1676   structure = gst_event_get_structure (event);
1677
1678   val = gst_structure_id_get_value (structure, GST_QUARK (FORMAT));
1679   if (format != NULL)
1680     *format = g_value_get_enum (val);
1681
1682   val = gst_structure_id_get_value (structure, GST_QUARK (POSITION));
1683   if (position != NULL)
1684     *position = g_value_get_int64 (val);
1685 }