gst/gstmessage.c

   1 /* GStreamer
   2  * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
   3  *
   4  * gstmessage.c: GstMessage subsystem
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22 /**
  23  * SECTION:gstmessage
  24  * @short_description: Lightweight objects to signal the application of
  25  *                     pipeline events
  26  * @see_also: #GstBus, #GstMiniObject, #GstElement
  27  *
  28  * Messages are implemented as a subclass of #GstMiniObject with a generic
  29  * #GstStructure as the content. This allows for writing custom messages without
  30  * requiring an API change while allowing a wide range of different types
  31  * of messages.
  32  *
  33  * Messages are posted by objects in the pipeline and are passed to the
  34  * application using the #GstBus.
  35  *
  36  * The basic use pattern of posting a message on a #GstBus is as follows:
  37  * |[
  38  *   gst_bus_post (bus, gst_message_new_eos());
  39  * ]|
  40  *
  41  * A #GstElement usually posts messages on the bus provided by the parent
  42  * container using gst_element_post_message().
  43  */
  44
  45
  46 #include "gst_private.h"
  47 #include <string.h>             /* memcpy */
  48 #include "gsterror.h"
  49 #include "gstenumtypes.h"
  50 #include "gstinfo.h"
  51 #include "gstmessage.h"
  52 #include "gsttaglist.h"
  53 #include "gstutils.h"
  54 #include "gstquark.h"
  55
  56
  57 typedef struct
  58 {
  59   GstMessage message;
  60
  61   GstStructure *structure;
  62 } GstMessageImpl;
  63
  64 #define GST_MESSAGE_STRUCTURE(m)  (((GstMessageImpl *)(m))->structure)
  65
  66 typedef struct
  67 {
  68   const gint type;
  69   const gchar *name;
  70   GQuark quark;
  71 } GstMessageQuarks;
  72
  73 static GstMessageQuarks message_quarks[] = {
  74   {GST_MESSAGE_UNKNOWN, "unknown", 0},
  75   {GST_MESSAGE_EOS, "eos", 0},
  76   {GST_MESSAGE_ERROR, "error", 0},
  77   {GST_MESSAGE_WARNING, "warning", 0},
  78   {GST_MESSAGE_INFO, "info", 0},
  79   {GST_MESSAGE_TAG, "tag", 0},
  80   {GST_MESSAGE_BUFFERING, "buffering", 0},
  81   {GST_MESSAGE_STATE_CHANGED, "state-changed", 0},
  82   {GST_MESSAGE_STATE_DIRTY, "state-dirty", 0},
  83   {GST_MESSAGE_STEP_DONE, "step-done", 0},
  84   {GST_MESSAGE_CLOCK_PROVIDE, "clock-provide", 0},
  85   {GST_MESSAGE_CLOCK_LOST, "clock-lost", 0},
  86   {GST_MESSAGE_NEW_CLOCK, "new-clock", 0},
  87   {GST_MESSAGE_STRUCTURE_CHANGE, "structure-change", 0},
  88   {GST_MESSAGE_STREAM_STATUS, "stream-status", 0},
  89   {GST_MESSAGE_APPLICATION, "application", 0},
  90   {GST_MESSAGE_ELEMENT, "element", 0},
  91   {GST_MESSAGE_SEGMENT_START, "segment-start", 0},
  92   {GST_MESSAGE_SEGMENT_DONE, "segment-done", 0},
  93   {GST_MESSAGE_DURATION_CHANGED, "duration-changed", 0},
  94   {GST_MESSAGE_LATENCY, "latency", 0},
  95   {GST_MESSAGE_ASYNC_START, "async-start", 0},
  96   {GST_MESSAGE_ASYNC_DONE, "async-done", 0},
  97   {GST_MESSAGE_REQUEST_STATE, "request-state", 0},
  98   {GST_MESSAGE_STEP_START, "step-start", 0},
  99   {GST_MESSAGE_QOS, "qos", 0},
 100   {GST_MESSAGE_PROGRESS, "progress", 0},
 101   {GST_MESSAGE_TOC, "toc", 0},
 102   {GST_MESSAGE_RESET_TIME, "reset-time", 0},
 103   {GST_MESSAGE_STREAM_START, "stream-start", 0},
 104   {GST_MESSAGE_NEED_CONTEXT, "need-context", 0},
 105   {GST_MESSAGE_HAVE_CONTEXT, "have-context", 0},
 106   {GST_MESSAGE_DEVICE_ADDED, "device-added", 0},
 107   {GST_MESSAGE_DEVICE_REMOVED, "device-removed", 0},
 108   {0, NULL, 0}
 109 };
 110
 111 GType _gst_message_type = 0;
 112 GST_DEFINE_MINI_OBJECT_TYPE (GstMessage, gst_message);
 113
 114 void
 115 _priv_gst_message_initialize (void)
 116 {
 117   gint i;
 118
 119   GST_CAT_INFO (GST_CAT_GST_INIT, "init messages");
 120
 121   for (i = 0; message_quarks[i].name; i++) {
 122     message_quarks[i].quark =
 123         g_quark_from_static_string (message_quarks[i].name);
 124   }
 125
 126   _gst_message_type = gst_message_get_type ();
 127 }
 128
 129 /**
 130  * gst_message_type_get_name:
 131  * @type: the message type
 132  *
 133  * Get a printable name for the given message type. Do not modify or free.
 134  *
 135  * Returns: a reference to the static name of the message.
 136  */
 137 const gchar *
 138 gst_message_type_get_name (GstMessageType type)
 139 {
 140   gint i;
 141
 142   for (i = 0; message_quarks[i].name; i++) {
 143     if (type == message_quarks[i].type)
 144       return message_quarks[i].name;
 145   }
 146   return "unknown";
 147 }
 148
 149 /**
 150  * gst_message_type_to_quark:
 151  * @type: the message type
 152  *
 153  * Get the unique quark for the given message type.
 154  *
 155  * Returns: the quark associated with the message type
 156  */
 157 GQuark
 158 gst_message_type_to_quark (GstMessageType type)
 159 {
 160   gint i;
 161
 162   for (i = 0; message_quarks[i].name; i++) {
 163     if (type == message_quarks[i].type)
 164       return message_quarks[i].quark;
 165   }
 166   return 0;
 167 }
 168
 169 static gboolean
 170 _gst_message_dispose (GstMessage * message)
 171 {
 172   gboolean do_free = TRUE;
 173
 174   if (GST_MINI_OBJECT_FLAG_IS_SET (message, GST_MESSAGE_FLAG_ASYNC_DELIVERY)) {
 175     GST_INFO ("[msg %p] signalling async free", message);
 176
 177     GST_MESSAGE_LOCK (message);
 178     GST_MESSAGE_SIGNAL (message);
 179     GST_MESSAGE_UNLOCK (message);
 180
 181     /* don't free it yet, let bus finish with it first */
 182     gst_message_ref (message);
 183     do_free = FALSE;
 184   }
 185
 186   return do_free;
 187 }
 188
 189 static void
 190 _gst_message_free (GstMessage * message)
 191 {
 192   GstStructure *structure;
 193
 194   g_return_if_fail (message != NULL);
 195
 196   GST_CAT_LOG (GST_CAT_MESSAGE, "finalize message %p, %s from %s", message,
 197       GST_MESSAGE_TYPE_NAME (message), GST_MESSAGE_SRC_NAME (message));
 198
 199   if (GST_MESSAGE_SRC (message)) {
 200     gst_object_unref (GST_MESSAGE_SRC (message));
 201     GST_MESSAGE_SRC (message) = NULL;
 202   }
 203
 204   structure = GST_MESSAGE_STRUCTURE (message);
 205   if (structure) {
 206     gst_structure_set_parent_refcount (structure, NULL);
 207     gst_structure_free (structure);
 208   }
 209
 210   g_slice_free1 (sizeof (GstMessageImpl), message);
 211 }
 212
 213 static void
 214 gst_message_init (GstMessageImpl * message, GstMessageType type,
 215     GstObject * src);
 216
 217 static GstMessage *
 218 _gst_message_copy (GstMessage * message)
 219 {
 220   GstMessageImpl *copy;
 221   GstStructure *structure;
 222
 223   GST_CAT_LOG (GST_CAT_MESSAGE, "copy message %p, %s from %s", message,
 224       GST_MESSAGE_TYPE_NAME (message),
 225       GST_OBJECT_NAME (GST_MESSAGE_SRC (message)));
 226
 227   copy = g_slice_new0 (GstMessageImpl);
 228
 229   gst_message_init (copy, GST_MESSAGE_TYPE (message),
 230       GST_MESSAGE_SRC (message));
 231
 232   GST_MESSAGE_TIMESTAMP (copy) = GST_MESSAGE_TIMESTAMP (message);
 233   GST_MESSAGE_SEQNUM (copy) = GST_MESSAGE_SEQNUM (message);
 234
 235   structure = GST_MESSAGE_STRUCTURE (message);
 236   if (structure) {
 237     GST_MESSAGE_STRUCTURE (copy) = gst_structure_copy (structure);
 238     gst_structure_set_parent_refcount (GST_MESSAGE_STRUCTURE (copy),
 239         &copy->message.mini_object.refcount);
 240   } else {
 241     GST_MESSAGE_STRUCTURE (copy) = NULL;
 242   }
 243
 244   return GST_MESSAGE_CAST (copy);
 245 }
 246
 247 static void
 248 gst_message_init (GstMessageImpl * message, GstMessageType type,
 249     GstObject * src)
 250 {
 251   gst_mini_object_init (GST_MINI_OBJECT_CAST (message), 0, _gst_message_type,
 252       (GstMiniObjectCopyFunction) _gst_message_copy,
 253       (GstMiniObjectDisposeFunction) _gst_message_dispose,
 254       (GstMiniObjectFreeFunction) _gst_message_free);
 255
 256   GST_MESSAGE_TYPE (message) = type;
 257   if (src)
 258     gst_object_ref (src);
 259   GST_MESSAGE_SRC (message) = src;
 260   GST_MESSAGE_TIMESTAMP (message) = GST_CLOCK_TIME_NONE;
 261   GST_MESSAGE_SEQNUM (message) = gst_util_seqnum_next ();
 262 }
 263
 264
 265 /**
 266  * gst_message_new_custom:
 267  * @type: The #GstMessageType to distinguish messages
 268  * @src: The object originating the message.
 269  * @structure: (transfer full) (allow-none): the structure for the
 270  *     message. The message will take ownership of the structure.
 271  *
 272  * Create a new custom-typed message. This can be used for anything not
 273  * handled by other message-specific functions to pass a message to the
 274  * app. The structure field can be %NULL.
 275  *
 276  * Returns: (transfer full): The new message.
 277  *
 278  * MT safe.
 279  */
 280 GstMessage *
 281 gst_message_new_custom (GstMessageType type, GstObject * src,
 282     GstStructure * structure)
 283 {
 284   GstMessageImpl *message;
 285
 286   message = g_slice_new0 (GstMessageImpl);
 287
 288   GST_CAT_LOG (GST_CAT_MESSAGE, "source %s: creating new message %p %s",
 289       (src ? GST_OBJECT_NAME (src) : "NULL"), message,
 290       gst_message_type_get_name (type));
 291
 292   if (structure) {
 293     /* structure must not have a parent */
 294     if (!gst_structure_set_parent_refcount (structure,
 295             &message->message.mini_object.refcount))
 296       goto had_parent;
 297   }
 298   gst_message_init (message, type, src);
 299
 300   GST_MESSAGE_STRUCTURE (message) = structure;
 301
 302   return GST_MESSAGE_CAST (message);
 303
 304   /* ERRORS */
 305 had_parent:
 306   {
 307     g_slice_free1 (sizeof (GstMessageImpl), message);
 308     g_warning ("structure is already owned by another object");
 309     return NULL;
 310   }
 311 }
 312
 313 /**
 314  * gst_message_get_seqnum:
 315  * @message: A #GstMessage.
 316  *
 317  * Retrieve the sequence number of a message.
 318  *
 319  * Messages have ever-incrementing sequence numbers, which may also be set
 320  * explicitly via gst_message_set_seqnum(). Sequence numbers are typically used
 321  * to indicate that a message corresponds to some other set of messages or
 322  * events, for example a SEGMENT_DONE message corresponding to a SEEK event. It
 323  * is considered good practice to make this correspondence when possible, though
 324  * it is not required.
 325  *
 326  * Note that events and messages share the same sequence number incrementor;
 327  * two events or messages will never have the same sequence number unless
 328  * that correspondence was made explicitly.
 329  *
 330  * Returns: The message's sequence number.
 331  *
 332  * MT safe.
 333  */
 334 guint32
 335 gst_message_get_seqnum (GstMessage * message)
 336 {
 337   g_return_val_if_fail (GST_IS_MESSAGE (message), -1);
 338
 339   return GST_MESSAGE_SEQNUM (message);
 340 }
 341
 342 /**
 343  * gst_message_set_seqnum:
 344  * @message: A #GstMessage.
 345  * @seqnum: A sequence number.
 346  *
 347  * Set the sequence number of a message.
 348  *
 349  * This function might be called by the creator of a message to indicate that
 350  * the message relates to other messages or events. See gst_message_get_seqnum()
 351  * for more information.
 352  *
 353  * MT safe.
 354  */
 355 void
 356 gst_message_set_seqnum (GstMessage * message, guint32 seqnum)
 357 {
 358   g_return_if_fail (GST_IS_MESSAGE (message));
 359
 360   GST_MESSAGE_SEQNUM (message) = seqnum;
 361 }
 362
 363 /**
 364  * gst_message_new_eos:
 365  * @src: (transfer none): The object originating the message.
 366  *
 367  * Create a new eos message. This message is generated and posted in
 368  * the sink elements of a GstBin. The bin will only forward the EOS
 369  * message to the application if all sinks have posted an EOS message.
 370  *
 371  * Returns: (transfer full): The new eos message.
 372  *
 373  * MT safe.
 374  */
 375 GstMessage *
 376 gst_message_new_eos (GstObject * src)
 377 {
 378   GstMessage *message;
 379
 380   message = gst_message_new_custom (GST_MESSAGE_EOS, src, NULL);
 381
 382   return message;
 383 }
 384
 385 /**
 386  * gst_message_new_error:
 387  * @src: (transfer none): The object originating the message.
 388  * @error: (transfer none): The GError for this message.
 389  * @debug: A debugging string.
 390  *
 391  * Create a new error message. The message will copy @error and
 392  * @debug. This message is posted by element when a fatal event
 393  * occurred. The pipeline will probably (partially) stop. The application
 394  * receiving this message should stop the pipeline.
 395  *
 396  * Returns: (transfer full): the new error message.
 397  *
 398  * MT safe.
 399  */
 400 GstMessage *
 401 gst_message_new_error (GstObject * src, GError * error, const gchar * debug)
 402 {
 403   GstMessage *message;
 404   GstStructure *structure;
 405
 406   structure = gst_structure_new_id (GST_QUARK (MESSAGE_ERROR),
 407       GST_QUARK (GERROR), G_TYPE_ERROR, error,
 408       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
 409   message = gst_message_new_custom (GST_MESSAGE_ERROR, src, structure);
 410
 411   return message;
 412 }
 413
 414 /**
 415  * gst_message_new_warning:
 416  * @src: (transfer none): The object originating the message.
 417  * @error: (transfer none): The GError for this message.
 418  * @debug: A debugging string.
 419  *
 420  * Create a new warning message. The message will make copies of @error and
 421  * @debug.
 422  *
 423  * Returns: (transfer full): The new warning message.
 424  *
 425  * MT safe.
 426  */
 427 GstMessage *
 428 gst_message_new_warning (GstObject * src, GError * error, const gchar * debug)
 429 {
 430   GstMessage *message;
 431   GstStructure *structure;
 432
 433   structure = gst_structure_new_id (GST_QUARK (MESSAGE_WARNING),
 434       GST_QUARK (GERROR), G_TYPE_ERROR, error,
 435       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
 436   message = gst_message_new_custom (GST_MESSAGE_WARNING, src, structure);
 437
 438   return message;
 439 }
 440
 441 /**
 442  * gst_message_new_info:
 443  * @src: (transfer none): The object originating the message.
 444  * @error: (transfer none): The GError for this message.
 445  * @debug: A debugging string.
 446  *
 447  * Create a new info message. The message will make copies of @error and
 448  * @debug.
 449  *
 450  * MT safe.
 451  *
 452  * Returns: (transfer full): the new info message.
 453  */
 454 GstMessage *
 455 gst_message_new_info (GstObject * src, GError * error, const gchar * debug)
 456 {
 457   GstMessage *message;
 458   GstStructure *structure;
 459
 460   structure = gst_structure_new_id (GST_QUARK (MESSAGE_INFO),
 461       GST_QUARK (GERROR), G_TYPE_ERROR, error,
 462       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
 463   message = gst_message_new_custom (GST_MESSAGE_INFO, src, structure);
 464
 465   return message;
 466 }
 467
 468 /**
 469  * gst_message_new_tag:
 470  * @src: (transfer none): The object originating the message.
 471  * @tag_list: (transfer full): the tag list for the message.
 472  *
 473  * Create a new tag message. The message will take ownership of the tag list.
 474  * The message is posted by elements that discovered a new taglist.
 475  *
 476  * Returns: (transfer full): the new tag message.
 477  *
 478  * MT safe.
 479  */
 480 GstMessage *
 481 gst_message_new_tag (GstObject * src, GstTagList * tag_list)
 482 {
 483   GstStructure *s;
 484   GstMessage *message;
 485   GValue val = G_VALUE_INIT;
 486
 487   g_return_val_if_fail (GST_IS_TAG_LIST (tag_list), NULL);
 488
 489   s = gst_structure_new_id_empty (GST_QUARK (MESSAGE_TAG));
 490   g_value_init (&val, GST_TYPE_TAG_LIST);
 491   g_value_take_boxed (&val, tag_list);
 492   gst_structure_id_take_value (s, GST_QUARK (TAGLIST), &val);
 493   message = gst_message_new_custom (GST_MESSAGE_TAG, src, s);
 494   return message;
 495 }
 496
 497 /**
 498  * gst_message_new_buffering:
 499  * @src: (transfer none): The object originating the message.
 500  * @percent: The buffering percent
 501  *
 502  * Create a new buffering message. This message can be posted by an element that
 503  * needs to buffer data before it can continue processing. @percent should be a
 504  * value between 0 and 100. A value of 100 means that the buffering completed.
 505  *
 506  * When @percent is < 100 the application should PAUSE a PLAYING pipeline. When
 507  * @percent is 100, the application can set the pipeline (back) to PLAYING.
 508  * The application must be prepared to receive BUFFERING messages in the
 509  * PREROLLING state and may only set the pipeline to PLAYING after receiving a
 510  * message with @percent set to 100, which can happen after the pipeline
 511  * completed prerolling.
 512  *
 513  * MT safe.
 514  *
 515  * Returns: (transfer full): The new buffering message.
 516  */
 517 GstMessage *
 518 gst_message_new_buffering (GstObject * src, gint percent)
 519 {
 520   GstMessage *message;
 521   GstStructure *structure;
 522   gint64 buffering_left;
 523
 524   g_return_val_if_fail (percent >= 0 && percent <= 100, NULL);
 525
 526   buffering_left = (percent == 100 ? 0 : -1);
 527
 528   structure = gst_structure_new_id (GST_QUARK (MESSAGE_BUFFERING),
 529       GST_QUARK (BUFFER_PERCENT), G_TYPE_INT, percent,
 530       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, GST_BUFFERING_STREAM,
 531       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, -1,
 532       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, -1,
 533       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
 534   message = gst_message_new_custom (GST_MESSAGE_BUFFERING, src, structure);
 535
 536   return message;
 537 }
 538
 539 /**
 540  * gst_message_new_state_changed:
 541  * @src: (transfer none): the object originating the message
 542  * @oldstate: the previous state
 543  * @newstate: the new (current) state
 544  * @pending: the pending (target) state
 545  *
 546  * Create a state change message. This message is posted whenever an element
 547  * changed its state.
 548  *
 549  * Returns: (transfer full): the new state change message.
 550  *
 551  * MT safe.
 552  */
 553 GstMessage *
 554 gst_message_new_state_changed (GstObject * src,
 555     GstState oldstate, GstState newstate, GstState pending)
 556 {
 557   GstMessage *message;
 558   GstStructure *structure;
 559
 560   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STATE_CHANGED),
 561       GST_QUARK (OLD_STATE), GST_TYPE_STATE, (gint) oldstate,
 562       GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) newstate,
 563       GST_QUARK (PENDING_STATE), GST_TYPE_STATE, (gint) pending, NULL);
 564   message = gst_message_new_custom (GST_MESSAGE_STATE_CHANGED, src, structure);
 565
 566   return message;
 567 }
 568
 569 /**
 570  * gst_message_new_state_dirty:
 571  * @src: (transfer none): the object originating the message
 572  *
 573  * Create a state dirty message. This message is posted whenever an element
 574  * changed its state asynchronously and is used internally to update the
 575  * states of container objects.
 576  *
 577  * Returns: (transfer full): the new state dirty message.
 578  *
 579  * MT safe.
 580  */
 581 GstMessage *
 582 gst_message_new_state_dirty (GstObject * src)
 583 {
 584   GstMessage *message;
 585
 586   message = gst_message_new_custom (GST_MESSAGE_STATE_DIRTY, src, NULL);
 587
 588   return message;
 589 }
 590
 591 /**
 592  * gst_message_new_clock_provide:
 593  * @src: (transfer none): the object originating the message.
 594  * @clock: (transfer none): the clock it provides
 595  * @ready: %TRUE if the sender can provide a clock
 596  *
 597  * Create a clock provide message. This message is posted whenever an
 598  * element is ready to provide a clock or lost its ability to provide
 599  * a clock (maybe because it paused or became EOS).
 600  *
 601  * This message is mainly used internally to manage the clock
 602  * selection.
 603  *
 604  * Returns: (transfer full): the new provide clock message.
 605  *
 606  * MT safe.
 607  */
 608 GstMessage *
 609 gst_message_new_clock_provide (GstObject * src, GstClock * clock,
 610     gboolean ready)
 611 {
 612   GstMessage *message;
 613   GstStructure *structure;
 614
 615   structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_PROVIDE),
 616       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock,
 617       GST_QUARK (READY), G_TYPE_BOOLEAN, ready, NULL);
 618   message = gst_message_new_custom (GST_MESSAGE_CLOCK_PROVIDE, src, structure);
 619
 620   return message;
 621 }
 622
 623 /**
 624  * gst_message_new_clock_lost:
 625  * @src: (transfer none): the object originating the message.
 626  * @clock: (transfer none): the clock that was lost
 627  *
 628  * Create a clock lost message. This message is posted whenever the
 629  * clock is not valid anymore.
 630  *
 631  * If this message is posted by the pipeline, the pipeline will
 632  * select a new clock again when it goes to PLAYING. It might therefore
 633  * be needed to set the pipeline to PAUSED and PLAYING again.
 634  *
 635  * Returns: (transfer full): The new clock lost message.
 636  *
 637  * MT safe.
 638  */
 639 GstMessage *
 640 gst_message_new_clock_lost (GstObject * src, GstClock * clock)
 641 {
 642   GstMessage *message;
 643   GstStructure *structure;
 644
 645   structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_LOST),
 646       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
 647   message = gst_message_new_custom (GST_MESSAGE_CLOCK_LOST, src, structure);
 648
 649   return message;
 650 }
 651
 652 /**
 653  * gst_message_new_new_clock:
 654  * @src: (transfer none): The object originating the message.
 655  * @clock: (transfer none): the new selected clock
 656  *
 657  * Create a new clock message. This message is posted whenever the
 658  * pipeline selects a new clock for the pipeline.
 659  *
 660  * Returns: (transfer full): The new new clock message.
 661  *
 662  * MT safe.
 663  */
 664 GstMessage *
 665 gst_message_new_new_clock (GstObject * src, GstClock * clock)
 666 {
 667   GstMessage *message;
 668   GstStructure *structure;
 669
 670   structure = gst_structure_new_id (GST_QUARK (MESSAGE_NEW_CLOCK),
 671       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
 672   message = gst_message_new_custom (GST_MESSAGE_NEW_CLOCK, src, structure);
 673
 674   return message;
 675 }
 676
 677 /**
 678  * gst_message_new_structure_change:
 679  * @src: (transfer none): The object originating the message.
 680  * @type: The change type.
 681  * @owner: (transfer none): The owner element of @src.
 682  * @busy: Whether the structure change is busy.
 683  *
 684  * Create a new structure change message. This message is posted when the
 685  * structure of a pipeline is in the process of being changed, for example
 686  * when pads are linked or unlinked.
 687  *
 688  * @src should be the sinkpad that unlinked or linked.
 689  *
 690  * Returns: (transfer full): the new structure change message.
 691  *
 692  * MT safe.
 693  */
 694 GstMessage *
 695 gst_message_new_structure_change (GstObject * src, GstStructureChangeType type,
 696     GstElement * owner, gboolean busy)
 697 {
 698   GstMessage *message;
 699   GstStructure *structure;
 700
 701   g_return_val_if_fail (GST_IS_PAD (src), NULL);
 702   /* g_return_val_if_fail (GST_PAD_DIRECTION (src) == GST_PAD_SINK, NULL); */
 703   g_return_val_if_fail (GST_IS_ELEMENT (owner), NULL);
 704
 705   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STRUCTURE_CHANGE),
 706       GST_QUARK (TYPE), GST_TYPE_STRUCTURE_CHANGE_TYPE, type,
 707       GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner,
 708       GST_QUARK (BUSY), G_TYPE_BOOLEAN, busy, NULL);
 709
 710   message = gst_message_new_custom (GST_MESSAGE_STRUCTURE_CHANGE, src,
 711       structure);
 712
 713   return message;
 714 }
 715
 716 /**
 717  * gst_message_new_segment_start:
 718  * @src: (transfer none): The object originating the message.
 719  * @format: The format of the position being played
 720  * @position: The position of the segment being played
 721  *
 722  * Create a new segment message. This message is posted by elements that
 723  * start playback of a segment as a result of a segment seek. This message
 724  * is not received by the application but is used for maintenance reasons in
 725  * container elements.
 726  *
 727  * Returns: (transfer full): the new segment start message.
 728  *
 729  * MT safe.
 730  */
 731 GstMessage *
 732 gst_message_new_segment_start (GstObject * src, GstFormat format,
 733     gint64 position)
 734 {
 735   GstMessage *message;
 736   GstStructure *structure;
 737
 738   structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_START),
 739       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 740       GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
 741   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_START, src, structure);
 742
 743   return message;
 744 }
 745
 746 /**
 747  * gst_message_new_segment_done:
 748  * @src: (transfer none): the object originating the message.
 749  * @format: The format of the position being done
 750  * @position: The position of the segment being done
 751  *
 752  * Create a new segment done message. This message is posted by elements that
 753  * finish playback of a segment as a result of a segment seek. This message
 754  * is received by the application after all elements that posted a segment_start
 755  * have posted the segment_done.
 756  *
 757  * Returns: (transfer full): the new segment done message.
 758  *
 759  * MT safe.
 760  */
 761 GstMessage *
 762 gst_message_new_segment_done (GstObject * src, GstFormat format,
 763     gint64 position)
 764 {
 765   GstMessage *message;
 766   GstStructure *structure;
 767
 768   structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_DONE),
 769       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 770       GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
 771   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_DONE, src, structure);
 772
 773   return message;
 774 }
 775
 776 /**
 777  * gst_message_new_application:
 778  * @src: (transfer none): the object originating the message.
 779  * @structure: (transfer full): the structure for the message. The message
 780  *     will take ownership of the structure.
 781  *
 782  * Create a new application-typed message. GStreamer will never create these
 783  * messages; they are a gift from us to you. Enjoy.
 784  *
 785  * Returns: (transfer full): The new application message.
 786  *
 787  * MT safe.
 788  */
 789 GstMessage *
 790 gst_message_new_application (GstObject * src, GstStructure * structure)
 791 {
 792   g_return_val_if_fail (structure != NULL, NULL);
 793
 794   return gst_message_new_custom (GST_MESSAGE_APPLICATION, src, structure);
 795 }
 796
 797 /**
 798  * gst_message_new_element:
 799  * @src: (transfer none): The object originating the message.
 800  * @structure: (transfer full): The structure for the
 801  *     message. The message will take ownership of the structure.
 802  *
 803  * Create a new element-specific message. This is meant as a generic way of
 804  * allowing one-way communication from an element to an application, for example
 805  * "the firewire cable was unplugged". The format of the message should be
 806  * documented in the element's documentation. The structure field can be %NULL.
 807  *
 808  * Returns: (transfer full): The new element message.
 809  *
 810  * MT safe.
 811  */
 812 GstMessage *
 813 gst_message_new_element (GstObject * src, GstStructure * structure)
 814 {
 815   g_return_val_if_fail (structure != NULL, NULL);
 816
 817   return gst_message_new_custom (GST_MESSAGE_ELEMENT, src, structure);
 818 }
 819
 820 /**
 821  * gst_message_new_duration_changed:
 822  * @src: (transfer none): The object originating the message.
 823  *
 824  * Create a new duration changed message. This message is posted by elements
 825  * that know the duration of a stream when the duration changes. This message
 826  * is received by bins and is used to calculate the total duration of a
 827  * pipeline. Elements may post a duration message with a duration of
 828  * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the
 829  * cached duration should be discarded. The new duration can then be
 830  * retrieved via a query.
 831  *
 832  * Returns: (transfer full): The new duration-changed message.
 833  *
 834  * MT safe.
 835  */
 836 GstMessage *
 837 gst_message_new_duration_changed (GstObject * src)
 838 {
 839   GstMessage *message;
 840
 841   message = gst_message_new_custom (GST_MESSAGE_DURATION_CHANGED, src,
 842       gst_structure_new_id_empty (GST_QUARK (MESSAGE_DURATION_CHANGED)));
 843
 844   return message;
 845 }
 846
 847 /**
 848  * gst_message_new_async_start:
 849  * @src: (transfer none): The object originating the message.
 850  *
 851  * This message is posted by elements when they start an ASYNC state change.
 852  *
 853  * Returns: (transfer full): The new async_start message.
 854  *
 855  * MT safe.
 856  */
 857 GstMessage *
 858 gst_message_new_async_start (GstObject * src)
 859 {
 860   GstMessage *message;
 861
 862   message = gst_message_new_custom (GST_MESSAGE_ASYNC_START, src, NULL);
 863
 864   return message;
 865 }
 866
 867 /**
 868  * gst_message_new_async_done:
 869  * @src: (transfer none): The object originating the message.
 870  * @running_time: the desired running_time
 871  *
 872  * The message is posted when elements completed an ASYNC state change.
 873  * @running_time contains the time of the desired running_time when this
 874  * elements goes to PLAYING. A value of #GST_CLOCK_TIME_NONE for @running_time
 875  * means that the element has no clock interaction and thus doesn't care about
 876  * the running_time of the pipeline.
 877  *
 878  * Returns: (transfer full): The new async_done message.
 879  *
 880  * MT safe.
 881  */
 882 GstMessage *
 883 gst_message_new_async_done (GstObject * src, GstClockTime running_time)
 884 {
 885   GstMessage *message;
 886   GstStructure *structure;
 887
 888   structure = gst_structure_new_id (GST_QUARK (MESSAGE_ASYNC_DONE),
 889       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
 890   message = gst_message_new_custom (GST_MESSAGE_ASYNC_DONE, src, structure);
 891
 892   return message;
 893 }
 894
 895 /**
 896  * gst_message_new_latency:
 897  * @src: (transfer none): The object originating the message.
 898  *
 899  * This message can be posted by elements when their latency requirements have
 900  * changed.
 901  *
 902  * Returns: (transfer full): The new latency message.
 903  *
 904  * MT safe.
 905  */
 906 GstMessage *
 907 gst_message_new_latency (GstObject * src)
 908 {
 909   GstMessage *message;
 910
 911   message = gst_message_new_custom (GST_MESSAGE_LATENCY, src, NULL);
 912
 913   return message;
 914 }
 915
 916 /**
 917  * gst_message_new_request_state:
 918  * @src: (transfer none): the object originating the message.
 919  * @state: The new requested state
 920  *
 921  * This message can be posted by elements when they want to have their state
 922  * changed. A typical use case would be an audio server that wants to pause the
 923  * pipeline because a higher priority stream is being played.
 924  *
 925  * Returns: (transfer full): the new request state message.
 926  *
 927  * MT safe.
 928  */
 929 GstMessage *
 930 gst_message_new_request_state (GstObject * src, GstState state)
 931 {
 932   GstMessage *message;
 933   GstStructure *structure;
 934
 935   structure = gst_structure_new_id (GST_QUARK (MESSAGE_REQUEST_STATE),
 936       GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) state, NULL);
 937   message = gst_message_new_custom (GST_MESSAGE_REQUEST_STATE, src, structure);
 938
 939   return message;
 940 }
 941
 942 /**
 943  * gst_message_get_structure:
 944  * @message: The #GstMessage.
 945  *
 946  * Access the structure of the message.
 947  *
 948  * Returns: (transfer none): The structure of the message. The structure is
 949  * still owned by the message, which means that you should not free it and
 950  * that the pointer becomes invalid when you free the message.
 951  *
 952  * MT safe.
 953  */
 954 const GstStructure *
 955 gst_message_get_structure (GstMessage * message)
 956 {
 957   g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
 958
 959   return GST_MESSAGE_STRUCTURE (message);
 960 }
 961
 962 /**
 963  * gst_message_has_name:
 964  * @message: The #GstMessage.
 965  * @name: name to check
 966  *
 967  * Checks if @message has the given @name. This function is usually used to
 968  * check the name of a custom message.
 969  *
 970  * Returns: %TRUE if @name matches the name of the message structure.
 971  */
 972 gboolean
 973 gst_message_has_name (GstMessage * message, const gchar * name)
 974 {
 975   GstStructure *structure;
 976
 977   g_return_val_if_fail (GST_IS_MESSAGE (message), FALSE);
 978
 979   structure = GST_MESSAGE_STRUCTURE (message);
 980   if (structure == NULL)
 981     return FALSE;
 982
 983   return gst_structure_has_name (structure, name);
 984 }
 985
 986 /**
 987  * gst_message_parse_tag:
 988  * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
 989  * @tag_list: (out callee-allocates): return location for the tag-list.
 990  *
 991  * Extracts the tag list from the GstMessage. The tag list returned in the
 992  * output argument is a copy; the caller must free it when done.
 993  *
 994  * Typical usage of this function might be:
 995  * |[
 996  *   ...
 997  *   switch (GST_MESSAGE_TYPE (msg)) {
 998  *     case GST_MESSAGE_TAG: {
 999  *       GstTagList *tags = NULL;
1000  *
1001  *       gst_message_parse_tag (msg, &amp;tags);
1002  *       g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
1003  *       handle_tags (tags);
1004  *       gst_tag_list_unref (tags);
1005  *       break;
1006  *     }
1007  *     ...
1008  *   }
1009  *   ...
1010  * ]|
1011  *
1012  * MT safe.
1013  */
1014 void
1015 gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
1016 {
1017   g_return_if_fail (GST_IS_MESSAGE (message));
1018   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TAG);
1019   g_return_if_fail (tag_list != NULL);
1020
1021   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1022       GST_QUARK (TAGLIST), GST_TYPE_TAG_LIST, tag_list, NULL);
1023 }
1024
1025 /**
1026  * gst_message_parse_buffering:
1027  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1028  * @percent: (out) (allow-none): Return location for the percent.
1029  *
1030  * Extracts the buffering percent from the GstMessage. see also
1031  * gst_message_new_buffering().
1032  *
1033  * MT safe.
1034  */
1035 void
1036 gst_message_parse_buffering (GstMessage * message, gint * percent)
1037 {
1038   g_return_if_fail (GST_IS_MESSAGE (message));
1039   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1040
1041   if (percent)
1042     *percent =
1043         g_value_get_int (gst_structure_id_get_value (GST_MESSAGE_STRUCTURE
1044             (message), GST_QUARK (BUFFER_PERCENT)));
1045 }
1046
1047 /**
1048  * gst_message_set_buffering_stats:
1049  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1050  * @mode: a buffering mode
1051  * @avg_in: the average input rate
1052  * @avg_out: the average output rate
1053  * @buffering_left: amount of buffering time left in milliseconds
1054  *
1055  * Configures the buffering stats values in @message.
1056  */
1057 void
1058 gst_message_set_buffering_stats (GstMessage * message, GstBufferingMode mode,
1059     gint avg_in, gint avg_out, gint64 buffering_left)
1060 {
1061   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1062
1063   gst_structure_id_set (GST_MESSAGE_STRUCTURE (message),
1064       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, mode,
1065       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, avg_in,
1066       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, avg_out,
1067       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
1068 }
1069
1070 /**
1071  * gst_message_parse_buffering_stats:
1072  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1073  * @mode: (out) (allow-none): a buffering mode, or %NULL
1074  * @avg_in: (out) (allow-none): the average input rate, or %NULL
1075  * @avg_out: (out) (allow-none): the average output rate, or %NULL
1076  * @buffering_left: (out) (allow-none): amount of buffering time left in
1077  *     milliseconds, or %NULL
1078  *
1079  * Extracts the buffering stats values from @message.
1080  */
1081 void
1082 gst_message_parse_buffering_stats (GstMessage * message,
1083     GstBufferingMode * mode, gint * avg_in, gint * avg_out,
1084     gint64 * buffering_left)
1085 {
1086   GstStructure *structure;
1087
1088   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1089
1090   structure = GST_MESSAGE_STRUCTURE (message);
1091   if (mode)
1092     *mode = (GstBufferingMode)
1093         g_value_get_enum (gst_structure_id_get_value (structure,
1094             GST_QUARK (BUFFERING_MODE)));
1095   if (avg_in)
1096     *avg_in = g_value_get_int (gst_structure_id_get_value (structure,
1097             GST_QUARK (AVG_IN_RATE)));
1098   if (avg_out)
1099     *avg_out = g_value_get_int (gst_structure_id_get_value (structure,
1100             GST_QUARK (AVG_OUT_RATE)));
1101   if (buffering_left)
1102     *buffering_left =
1103         g_value_get_int64 (gst_structure_id_get_value (structure,
1104             GST_QUARK (BUFFERING_LEFT)));
1105 }
1106
1107 /**
1108  * gst_message_parse_state_changed:
1109  * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED
1110  * @oldstate: (out) (allow-none): the previous state, or %NULL
1111  * @newstate: (out) (allow-none): the new (current) state, or %NULL
1112  * @pending: (out) (allow-none): the pending (target) state, or %NULL
1113  *
1114  * Extracts the old and new states from the GstMessage.
1115  *
1116  * Typical usage of this function might be:
1117  * |[
1118  *   ...
1119  *   switch (GST_MESSAGE_TYPE (msg)) {
1120  *     case GST_MESSAGE_STATE_CHANGED: {
1121  *       GstState old_state, new_state;
1122  *
1123  *       gst_message_parse_state_changed (msg, &amp;old_state, &amp;new_state, NULL);
1124  *       g_print ("Element %s changed state from %s to %s.\n",
1125  *           GST_OBJECT_NAME (msg->src),
1126  *           gst_element_state_get_name (old_state),
1127  *           gst_element_state_get_name (new_state));
1128  *       break;
1129  *     }
1130  *     ...
1131  *   }
1132  *   ...
1133  * ]|
1134  *
1135  * MT safe.
1136  */
1137 void
1138 gst_message_parse_state_changed (GstMessage * message,
1139     GstState * oldstate, GstState * newstate, GstState * pending)
1140 {
1141   GstStructure *structure;
1142
1143   g_return_if_fail (GST_IS_MESSAGE (message));
1144   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STATE_CHANGED);
1145
1146   structure = GST_MESSAGE_STRUCTURE (message);
1147   if (oldstate)
1148     *oldstate = (GstState)
1149         g_value_get_enum (gst_structure_id_get_value (structure,
1150             GST_QUARK (OLD_STATE)));
1151   if (newstate)
1152     *newstate = (GstState)
1153         g_value_get_enum (gst_structure_id_get_value (structure,
1154             GST_QUARK (NEW_STATE)));
1155   if (pending)
1156     *pending = (GstState)
1157         g_value_get_enum (gst_structure_id_get_value (structure,
1158             GST_QUARK (PENDING_STATE)));
1159 }
1160
1161 /**
1162  * gst_message_parse_clock_provide:
1163  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.
1164  * @clock: (out) (allow-none) (transfer none): a pointer to  hold a clock
1165  *     object, or %NULL
1166  * @ready: (out) (allow-none): a pointer to hold the ready flag, or %NULL
1167  *
1168  * Extracts the clock and ready flag from the GstMessage.
1169  * The clock object returned remains valid until the message is freed.
1170  *
1171  * MT safe.
1172  */
1173 void
1174 gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock,
1175     gboolean * ready)
1176 {
1177   const GValue *clock_gvalue;
1178   GstStructure *structure;
1179
1180   g_return_if_fail (GST_IS_MESSAGE (message));
1181   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_PROVIDE);
1182
1183   structure = GST_MESSAGE_STRUCTURE (message);
1184   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1185   g_return_if_fail (clock_gvalue != NULL);
1186   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1187
1188   if (ready)
1189     *ready =
1190         g_value_get_boolean (gst_structure_id_get_value (structure,
1191             GST_QUARK (READY)));
1192   if (clock)
1193     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1194 }
1195
1196 /**
1197  * gst_message_parse_clock_lost:
1198  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST.
1199  * @clock: (out) (allow-none) (transfer none): a pointer to hold the lost clock
1200  *
1201  * Extracts the lost clock from the GstMessage.
1202  * The clock object returned remains valid until the message is freed.
1203  *
1204  * MT safe.
1205  */
1206 void
1207 gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock)
1208 {
1209   const GValue *clock_gvalue;
1210   GstStructure *structure;
1211
1212   g_return_if_fail (GST_IS_MESSAGE (message));
1213   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_LOST);
1214
1215   structure = GST_MESSAGE_STRUCTURE (message);
1216   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1217   g_return_if_fail (clock_gvalue != NULL);
1218   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1219
1220   if (clock)
1221     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1222 }
1223
1224 /**
1225  * gst_message_parse_new_clock:
1226  * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK.
1227  * @clock: (out) (allow-none) (transfer none): a pointer to hold the selected
1228  *     new clock
1229  *
1230  * Extracts the new clock from the GstMessage.
1231  * The clock object returned remains valid until the message is freed.
1232  *
1233  * MT safe.
1234  */
1235 void
1236 gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)
1237 {
1238   const GValue *clock_gvalue;
1239   GstStructure *structure;
1240
1241   g_return_if_fail (GST_IS_MESSAGE (message));
1242   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_NEW_CLOCK);
1243
1244   structure = GST_MESSAGE_STRUCTURE (message);
1245   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1246   g_return_if_fail (clock_gvalue != NULL);
1247   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1248
1249   if (clock)
1250     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1251 }
1252
1253 /**
1254  * gst_message_parse_structure_change:
1255  * @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.
1256  * @type: (out): A pointer to hold the change type
1257  * @owner: (out) (allow-none) (transfer none): The owner element of the
1258  *     message source
1259  * @busy: (out) (allow-none): a pointer to hold whether the change is in
1260  *     progress or has been completed
1261  *
1262  * Extracts the change type and completion status from the GstMessage.
1263  *
1264  * MT safe.
1265  */
1266 void
1267 gst_message_parse_structure_change (GstMessage * message,
1268     GstStructureChangeType * type, GstElement ** owner, gboolean * busy)
1269 {
1270   const GValue *owner_gvalue;
1271   GstStructure *structure;
1272
1273   g_return_if_fail (GST_IS_MESSAGE (message));
1274   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STRUCTURE_CHANGE);
1275
1276   structure = GST_MESSAGE_STRUCTURE (message);
1277   owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1278   g_return_if_fail (owner_gvalue != NULL);
1279   g_return_if_fail (G_VALUE_TYPE (owner_gvalue) == GST_TYPE_ELEMENT);
1280
1281   if (type)
1282     *type = (GstStructureChangeType)
1283         g_value_get_enum (gst_structure_id_get_value (structure,
1284             GST_QUARK (TYPE)));
1285   if (owner)
1286     *owner = (GstElement *) g_value_get_object (owner_gvalue);
1287   if (busy)
1288     *busy =
1289         g_value_get_boolean (gst_structure_id_get_value (structure,
1290             GST_QUARK (BUSY)));
1291 }
1292
1293 /**
1294  * gst_message_parse_error:
1295  * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
1296  * @gerror: (out) (allow-none) (transfer full): location for the GError
1297  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1298  *     or %NULL
1299  *
1300  * Extracts the GError and debug string from the GstMessage. The values returned
1301  * in the output arguments are copies; the caller must free them when done.
1302  *
1303  * Typical usage of this function might be:
1304  * |[
1305  *   ...
1306  *   switch (GST_MESSAGE_TYPE (msg)) {
1307  *     case GST_MESSAGE_ERROR: {
1308  *       GError *err = NULL;
1309  *       gchar *dbg_info = NULL;
1310  *
1311  *       gst_message_parse_error (msg, &amp;err, &amp;dbg_info);
1312  *       g_printerr ("ERROR from element %s: %s\n",
1313  *           GST_OBJECT_NAME (msg->src), err->message);
1314  *       g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none");
1315  *       g_error_free (err);
1316  *       g_free (dbg_info);
1317  *       break;
1318  *     }
1319  *     ...
1320  *   }
1321  *   ...
1322  * ]|
1323  *
1324  * MT safe.
1325  */
1326 void
1327 gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
1328 {
1329   g_return_if_fail (GST_IS_MESSAGE (message));
1330   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ERROR);
1331
1332   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1333       GST_QUARK (GERROR), G_TYPE_ERROR, gerror,
1334       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
1335 }
1336
1337 /**
1338  * gst_message_parse_warning:
1339  * @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
1340  * @gerror: (out) (allow-none) (transfer full): location for the GError
1341  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1342  *     or %NULL
1343  *
1344  * Extracts the GError and debug string from the GstMessage. The values returned
1345  * in the output arguments are copies; the caller must free them when done.
1346  *
1347  * MT safe.
1348  */
1349 void
1350 gst_message_parse_warning (GstMessage * message, GError ** gerror,
1351     gchar ** debug)
1352 {
1353   g_return_if_fail (GST_IS_MESSAGE (message));
1354   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_WARNING);
1355
1356   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1357       GST_QUARK (GERROR), G_TYPE_ERROR, gerror,
1358       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
1359 }
1360
1361 /**
1362  * gst_message_parse_info:
1363  * @message: A valid #GstMessage of type GST_MESSAGE_INFO.
1364  * @gerror: (out) (allow-none) (transfer full): location for the GError
1365  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1366  *     or %NULL
1367  *
1368  * Extracts the GError and debug string from the GstMessage. The values returned
1369  * in the output arguments are copies; the caller must free them when done.
1370  *
1371  * MT safe.
1372  */
1373 void
1374 gst_message_parse_info (GstMessage * message, GError ** gerror, gchar ** debug)
1375 {
1376   g_return_if_fail (GST_IS_MESSAGE (message));
1377   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_INFO);
1378
1379   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1380       GST_QUARK (GERROR), G_TYPE_ERROR, gerror,
1381       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
1382 }
1383
1384 /**
1385  * gst_message_parse_segment_start:
1386  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_START.
1387  * @format: (out) (allow-none): Result location for the format, or %NULL
1388  * @position: (out) (allow-none): Result location for the position, or %NULL
1389  *
1390  * Extracts the position and format from the segment start message.
1391  *
1392  * MT safe.
1393  */
1394 void
1395 gst_message_parse_segment_start (GstMessage * message, GstFormat * format,
1396     gint64 * position)
1397 {
1398   GstStructure *structure;
1399
1400   g_return_if_fail (GST_IS_MESSAGE (message));
1401   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_START);
1402
1403   structure = GST_MESSAGE_STRUCTURE (message);
1404   if (format)
1405     *format = (GstFormat)
1406         g_value_get_enum (gst_structure_id_get_value (structure,
1407             GST_QUARK (FORMAT)));
1408   if (position)
1409     *position =
1410         g_value_get_int64 (gst_structure_id_get_value (structure,
1411             GST_QUARK (POSITION)));
1412 }
1413
1414 /**
1415  * gst_message_parse_segment_done:
1416  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE.
1417  * @format: (out) (allow-none): Result location for the format, or %NULL
1418  * @position: (out) (allow-none): Result location for the position, or %NULL
1419  *
1420  * Extracts the position and format from the segment done message.
1421  *
1422  * MT safe.
1423  */
1424 void
1425 gst_message_parse_segment_done (GstMessage * message, GstFormat * format,
1426     gint64 * position)
1427 {
1428   GstStructure *structure;
1429
1430   g_return_if_fail (GST_IS_MESSAGE (message));
1431   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_DONE);
1432
1433   structure = GST_MESSAGE_STRUCTURE (message);
1434   if (format)
1435     *format = (GstFormat)
1436         g_value_get_enum (gst_structure_id_get_value (structure,
1437             GST_QUARK (FORMAT)));
1438   if (position)
1439     *position =
1440         g_value_get_int64 (gst_structure_id_get_value (structure,
1441             GST_QUARK (POSITION)));
1442 }
1443
1444 /**
1445  * gst_message_parse_async_done:
1446  * @message: A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE.
1447  * @running_time: (out) (allow-none): Result location for the running_time or %NULL
1448  *
1449  * Extract the running_time from the async_done message.
1450  *
1451  * MT safe.
1452  */
1453 void
1454 gst_message_parse_async_done (GstMessage * message, GstClockTime * running_time)
1455 {
1456   GstStructure *structure;
1457
1458   g_return_if_fail (GST_IS_MESSAGE (message));
1459   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ASYNC_DONE);
1460
1461   structure = GST_MESSAGE_STRUCTURE (message);
1462   if (running_time)
1463     *running_time =
1464         g_value_get_uint64 (gst_structure_id_get_value (structure,
1465             GST_QUARK (RUNNING_TIME)));
1466 }
1467
1468 /**
1469  * gst_message_parse_request_state:
1470  * @message: A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE.
1471  * @state: (out) (allow-none): Result location for the requested state or %NULL
1472  *
1473  * Extract the requested state from the request_state message.
1474  *
1475  * MT safe.
1476  */
1477 void
1478 gst_message_parse_request_state (GstMessage * message, GstState * state)
1479 {
1480   GstStructure *structure;
1481
1482   g_return_if_fail (GST_IS_MESSAGE (message));
1483   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_REQUEST_STATE);
1484
1485   structure = GST_MESSAGE_STRUCTURE (message);
1486   if (state)
1487     *state = (GstState)
1488         g_value_get_enum (gst_structure_id_get_value (structure,
1489             GST_QUARK (NEW_STATE)));
1490 }
1491
1492 /**
1493  * gst_message_new_stream_status:
1494  * @src: The object originating the message.
1495  * @type: The stream status type.
1496  * @owner: (transfer none): the owner element of @src.
1497  *
1498  * Create a new stream status message. This message is posted when a streaming
1499  * thread is created/destroyed or when the state changed.
1500  *
1501  * Returns: (transfer full): the new stream status message.
1502  *
1503  * MT safe.
1504  */
1505 GstMessage *
1506 gst_message_new_stream_status (GstObject * src, GstStreamStatusType type,
1507     GstElement * owner)
1508 {
1509   GstMessage *message;
1510   GstStructure *structure;
1511
1512   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STREAM_STATUS),
1513       GST_QUARK (TYPE), GST_TYPE_STREAM_STATUS_TYPE, (gint) type,
1514       GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner, NULL);
1515   message = gst_message_new_custom (GST_MESSAGE_STREAM_STATUS, src, structure);
1516
1517   return message;
1518 }
1519
1520 /**
1521  * gst_message_parse_stream_status:
1522  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1523  * @type: (out): A pointer to hold the status type
1524  * @owner: (out) (transfer none): The owner element of the message source
1525  *
1526  * Extracts the stream status type and owner the GstMessage. The returned
1527  * owner remains valid for as long as the reference to @message is valid and
1528  * should thus not be unreffed.
1529  *
1530  * MT safe.
1531  */
1532 void
1533 gst_message_parse_stream_status (GstMessage * message,
1534     GstStreamStatusType * type, GstElement ** owner)
1535 {
1536   const GValue *owner_gvalue;
1537   GstStructure *structure;
1538
1539   g_return_if_fail (GST_IS_MESSAGE (message));
1540   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1541
1542   structure = GST_MESSAGE_STRUCTURE (message);
1543   owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1544   g_return_if_fail (owner_gvalue != NULL);
1545
1546   if (type)
1547     *type = (GstStreamStatusType)
1548         g_value_get_enum (gst_structure_id_get_value (structure,
1549             GST_QUARK (TYPE)));
1550   if (owner)
1551     *owner = (GstElement *) g_value_get_object (owner_gvalue);
1552 }
1553
1554 /**
1555  * gst_message_set_stream_status_object:
1556  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1557  * @object: the object controlling the streaming
1558  *
1559  * Configures the object handling the streaming thread. This is usually a
1560  * GstTask object but other objects might be added in the future.
1561  */
1562 void
1563 gst_message_set_stream_status_object (GstMessage * message,
1564     const GValue * object)
1565 {
1566   GstStructure *structure;
1567
1568   g_return_if_fail (GST_IS_MESSAGE (message));
1569   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1570
1571   structure = GST_MESSAGE_STRUCTURE (message);
1572   gst_structure_id_set_value (structure, GST_QUARK (OBJECT), object);
1573 }
1574
1575 /**
1576  * gst_message_get_stream_status_object:
1577  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1578  *
1579  * Extracts the object managing the streaming thread from @message.
1580  *
1581  * Returns: a GValue containing the object that manages the streaming thread.
1582  * This object is usually of type GstTask but other types can be added in the
1583  * future. The object remains valid as long as @message is valid.
1584  */
1585 const GValue *
1586 gst_message_get_stream_status_object (GstMessage * message)
1587 {
1588   const GValue *result;
1589   GstStructure *structure;
1590
1591   g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
1592   g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS,
1593       NULL);
1594
1595   structure = GST_MESSAGE_STRUCTURE (message);
1596   result = gst_structure_id_get_value (structure, GST_QUARK (OBJECT));
1597
1598   return result;
1599 }
1600
1601 /**
1602  * gst_message_new_step_done:
1603  * @src: The object originating the message.
1604  * @format: the format of @amount
1605  * @amount: the amount of stepped data
1606  * @rate: the rate of the stepped amount
1607  * @flush: is this an flushing step
1608  * @intermediate: is this an intermediate step
1609  * @duration: the duration of the data
1610  * @eos: the step caused EOS
1611  *
1612  * This message is posted by elements when they complete a part, when @intermediate set
1613  * to %TRUE, or a complete step operation.
1614  *
1615  * @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped
1616  * @amount of media in format @format.
1617  *
1618  * Returns: (transfer full): the new step_done message.
1619  *
1620  * MT safe.
1621  */
1622 GstMessage *
1623 gst_message_new_step_done (GstObject * src, GstFormat format, guint64 amount,
1624     gdouble rate, gboolean flush, gboolean intermediate, guint64 duration,
1625     gboolean eos)
1626 {
1627   GstMessage *message;
1628   GstStructure *structure;
1629
1630   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_DONE),
1631       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1632       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1633       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1634       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1635       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1636       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1637       GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1638   message = gst_message_new_custom (GST_MESSAGE_STEP_DONE, src, structure);
1639
1640   return message;
1641 }
1642
1643 /**
1644  * gst_message_parse_step_done:
1645  * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1646  * @format: (out) (allow-none): result location for the format
1647  * @amount: (out) (allow-none): result location for the amount
1648  * @rate: (out) (allow-none): result location for the rate
1649  * @flush: (out) (allow-none): result location for the flush flag
1650  * @intermediate: (out) (allow-none): result location for the intermediate flag
1651  * @duration: (out) (allow-none): result location for the duration
1652  * @eos: (out) (allow-none): result location for the EOS flag
1653  *
1654  * Extract the values the step_done message.
1655  *
1656  * MT safe.
1657  */
1658 void
1659 gst_message_parse_step_done (GstMessage * message, GstFormat * format,
1660     guint64 * amount, gdouble * rate, gboolean * flush, gboolean * intermediate,
1661     guint64 * duration, gboolean * eos)
1662 {
1663   GstStructure *structure;
1664
1665   g_return_if_fail (GST_IS_MESSAGE (message));
1666   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_DONE);
1667
1668   structure = GST_MESSAGE_STRUCTURE (message);
1669   gst_structure_id_get (structure,
1670       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1671       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1672       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1673       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1674       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1675       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1676       GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1677 }
1678
1679 /**
1680  * gst_message_new_step_start:
1681  * @src: The object originating the message.
1682  * @active: if the step is active or queued
1683  * @format: the format of @amount
1684  * @amount: the amount of stepped data
1685  * @rate: the rate of the stepped amount
1686  * @flush: is this an flushing step
1687  * @intermediate: is this an intermediate step
1688  *
1689  * This message is posted by elements when they accept or activate a new step
1690  * event for @amount in @format.
1691  *
1692  * @active is set to %FALSE when the element accepted the new step event and has
1693  * queued it for execution in the streaming threads.
1694  *
1695  * @active is set to %TRUE when the element has activated the step operation and
1696  * is now ready to start executing the step in the streaming thread. After this
1697  * message is emitted, the application can queue a new step operation in the
1698  * element.
1699  *
1700  * Returns: (transfer full): The new step_start message.
1701  *
1702  * MT safe.
1703  */
1704 GstMessage *
1705 gst_message_new_step_start (GstObject * src, gboolean active, GstFormat format,
1706     guint64 amount, gdouble rate, gboolean flush, gboolean intermediate)
1707 {
1708   GstMessage *message;
1709   GstStructure *structure;
1710
1711   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_START),
1712       GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1713       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1714       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1715       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1716       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1717       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1718   message = gst_message_new_custom (GST_MESSAGE_STEP_START, src, structure);
1719
1720   return message;
1721 }
1722
1723 /**
1724  * gst_message_parse_step_start:
1725  * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1726  * @active: (out) (allow-none): result location for the active flag
1727  * @format: (out) (allow-none): result location for the format
1728  * @amount: (out) (allow-none): result location for the amount
1729  * @rate: (out) (allow-none): result location for the rate
1730  * @flush: (out) (allow-none): result location for the flush flag
1731  * @intermediate: (out) (allow-none): result location for the intermediate flag
1732  *
1733  * Extract the values from step_start message.
1734  *
1735  * MT safe.
1736  */
1737 void
1738 gst_message_parse_step_start (GstMessage * message, gboolean * active,
1739     GstFormat * format, guint64 * amount, gdouble * rate, gboolean * flush,
1740     gboolean * intermediate)
1741 {
1742   GstStructure *structure;
1743
1744   g_return_if_fail (GST_IS_MESSAGE (message));
1745   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_START);
1746
1747   structure = GST_MESSAGE_STRUCTURE (message);
1748   gst_structure_id_get (structure,
1749       GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1750       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1751       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1752       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1753       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1754       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1755 }
1756
1757 /**
1758  * gst_message_new_qos:
1759  * @src: The object originating the message.
1760  * @live: if the message was generated by a live element
1761  * @running_time: the running time of the buffer that generated the message
1762  * @stream_time: the stream time of the buffer that generated the message
1763  * @timestamp: the timestamps of the buffer that generated the message
1764  * @duration: the duration of the buffer that generated the message
1765  *
1766  * A QOS message is posted on the bus whenever an element decides to drop a
1767  * buffer because of QoS reasons or whenever it changes its processing strategy
1768  * because of QoS reasons (quality adjustments such as processing at lower
1769  * accuracy).
1770  *
1771  * This message can be posted by an element that performs synchronisation against the
1772  * clock (live) or it could be dropped by an element that performs QoS because of QOS
1773  * events received from a downstream element (!live).
1774  *
1775  * @running_time, @stream_time, @timestamp, @duration should be set to the
1776  * respective running-time, stream-time, timestamp and duration of the (dropped)
1777  * buffer that generated the QoS event. Values can be left to
1778  * GST_CLOCK_TIME_NONE when unknown.
1779  *
1780  * Returns: (transfer full): The new qos message.
1781  *
1782  * MT safe.
1783  */
1784 GstMessage *
1785 gst_message_new_qos (GstObject * src, gboolean live, guint64 running_time,
1786     guint64 stream_time, guint64 timestamp, guint64 duration)
1787 {
1788   GstMessage *message;
1789   GstStructure *structure;
1790
1791   structure = gst_structure_new_id (GST_QUARK (MESSAGE_QOS),
1792       GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
1793       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
1794       GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
1795       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
1796       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1797       GST_QUARK (JITTER), G_TYPE_INT64, (gint64) 0,
1798       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, (gdouble) 1.0,
1799       GST_QUARK (QUALITY), G_TYPE_INT, (gint) 1000000,
1800       GST_QUARK (FORMAT), GST_TYPE_FORMAT, GST_FORMAT_UNDEFINED,
1801       GST_QUARK (PROCESSED), G_TYPE_UINT64, (guint64) - 1,
1802       GST_QUARK (DROPPED), G_TYPE_UINT64, (guint64) - 1, NULL);
1803   message = gst_message_new_custom (GST_MESSAGE_QOS, src, structure);
1804
1805   return message;
1806 }
1807
1808 /**
1809  * gst_message_set_qos_values:
1810  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1811  * @jitter: The difference of the running-time against the deadline.
1812  * @proportion: Long term prediction of the ideal rate relative to normal rate
1813  * to get optimal quality.
1814  * @quality: An element dependent integer value that specifies the current
1815  * quality level of the element. The default maximum quality is 1000000.
1816  *
1817  * Set the QoS values that have been calculated/analysed from the QoS data
1818  *
1819  * MT safe.
1820  */
1821 void
1822 gst_message_set_qos_values (GstMessage * message, gint64 jitter,
1823     gdouble proportion, gint quality)
1824 {
1825   GstStructure *structure;
1826
1827   g_return_if_fail (GST_IS_MESSAGE (message));
1828   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1829
1830   structure = GST_MESSAGE_STRUCTURE (message);
1831   gst_structure_id_set (structure,
1832       GST_QUARK (JITTER), G_TYPE_INT64, jitter,
1833       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
1834       GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
1835 }
1836
1837 /**
1838  * gst_message_set_qos_stats:
1839  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1840  * @format: Units of the 'processed' and 'dropped' fields. Video sinks and video
1841  * filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters
1842  * will likely use GST_FORMAT_DEFAULT (samples).
1843  * @processed: Total number of units correctly processed since the last state
1844  * change to READY or a flushing operation.
1845  * @dropped: Total number of units dropped since the last state change to READY
1846  * or a flushing operation.
1847  *
1848  * Set the QoS stats representing the history of the current continuous pipeline
1849  * playback period.
1850  *
1851  * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
1852  * invalid. Values of -1 for either @processed or @dropped mean unknown values.
1853  *
1854  * MT safe.
1855  */
1856 void
1857 gst_message_set_qos_stats (GstMessage * message, GstFormat format,
1858     guint64 processed, guint64 dropped)
1859 {
1860   GstStructure *structure;
1861
1862   g_return_if_fail (GST_IS_MESSAGE (message));
1863   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1864
1865   structure = GST_MESSAGE_STRUCTURE (message);
1866   gst_structure_id_set (structure,
1867       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1868       GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
1869       GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
1870 }
1871
1872 /**
1873  * gst_message_parse_qos:
1874  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1875  * @live: (out) (allow-none): if the message was generated by a live element
1876  * @running_time: (out) (allow-none): the running time of the buffer that
1877  *     generated the message
1878  * @stream_time: (out) (allow-none): the stream time of the buffer that
1879  *     generated the message
1880  * @timestamp: (out) (allow-none): the timestamps of the buffer that
1881  *     generated the message
1882  * @duration: (out) (allow-none): the duration of the buffer that
1883  *     generated the message
1884  *
1885  * Extract the timestamps and live status from the QoS message.
1886  *
1887  * The returned values give the running_time, stream_time, timestamp and
1888  * duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown
1889  * values.
1890  *
1891  * MT safe.
1892  */
1893 void
1894 gst_message_parse_qos (GstMessage * message, gboolean * live,
1895     guint64 * running_time, guint64 * stream_time, guint64 * timestamp,
1896     guint64 * duration)
1897 {
1898   GstStructure *structure;
1899
1900   g_return_if_fail (GST_IS_MESSAGE (message));
1901   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1902
1903   structure = GST_MESSAGE_STRUCTURE (message);
1904   gst_structure_id_get (structure,
1905       GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
1906       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
1907       GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
1908       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
1909       GST_QUARK (DURATION), G_TYPE_UINT64, duration, NULL);
1910 }
1911
1912 /**
1913  * gst_message_parse_qos_values:
1914  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1915  * @jitter: (out) (allow-none): The difference of the running-time against
1916  *     the deadline.
1917  * @proportion: (out) (allow-none): Long term prediction of the ideal rate
1918  *     relative to normal rate to get optimal quality.
1919  * @quality: (out) (allow-none): An element dependent integer value that
1920  *     specifies the current quality level of the element. The default
1921  *     maximum quality is 1000000.
1922  *
1923  * Extract the QoS values that have been calculated/analysed from the QoS data
1924  *
1925  * MT safe.
1926  */
1927 void
1928 gst_message_parse_qos_values (GstMessage * message, gint64 * jitter,
1929     gdouble * proportion, gint * quality)
1930 {
1931   GstStructure *structure;
1932
1933   g_return_if_fail (GST_IS_MESSAGE (message));
1934   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1935
1936   structure = GST_MESSAGE_STRUCTURE (message);
1937   gst_structure_id_get (structure,
1938       GST_QUARK (JITTER), G_TYPE_INT64, jitter,
1939       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
1940       GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
1941 }
1942
1943 /**
1944  * gst_message_parse_qos_stats:
1945  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1946  * @format: (out) (allow-none): Units of the 'processed' and 'dropped' fields.
1947  *     Video sinks and video filters will use GST_FORMAT_BUFFERS (frames).
1948  *     Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT
1949  *     (samples).
1950  * @processed: (out) (allow-none): Total number of units correctly processed
1951  *     since the last state change to READY or a flushing operation.
1952  * @dropped: (out) (allow-none): Total number of units dropped since the last
1953  *     state change to READY or a flushing operation.
1954  *
1955  * Extract the QoS stats representing the history of the current continuous
1956  * pipeline playback period.
1957  *
1958  * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
1959  * invalid. Values of -1 for either @processed or @dropped mean unknown values.
1960  *
1961  * MT safe.
1962  */
1963 void
1964 gst_message_parse_qos_stats (GstMessage * message, GstFormat * format,
1965     guint64 * processed, guint64 * dropped)
1966 {
1967   GstStructure *structure;
1968
1969   g_return_if_fail (GST_IS_MESSAGE (message));
1970   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1971
1972   structure = GST_MESSAGE_STRUCTURE (message);
1973   gst_structure_id_get (structure,
1974       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1975       GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
1976       GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
1977 }
1978
1979 /**
1980  * gst_message_new_progress:
1981  * @src: The object originating the message.
1982  * @type: a #GstProgressType
1983  * @code: a progress code
1984  * @text: free, user visible text describing the progress
1985  *
1986  * Progress messages are posted by elements when they use an asynchronous task
1987  * to perform actions triggered by a state change.
1988  *
1989  * @code contains a well defined string describing the action.
1990  * @test should contain a user visible string detailing the current action.
1991  *
1992  * Returns: (transfer full): The new qos message.
1993  */
1994 GstMessage *
1995 gst_message_new_progress (GstObject * src, GstProgressType type,
1996     const gchar * code, const gchar * text)
1997 {
1998   GstMessage *message;
1999   GstStructure *structure;
2000   gint percent = 100, timeout = -1;
2001
2002   g_return_val_if_fail (code != NULL, NULL);
2003   g_return_val_if_fail (text != NULL, NULL);
2004
2005   if (type == GST_PROGRESS_TYPE_START || type == GST_PROGRESS_TYPE_CONTINUE)
2006     percent = 0;
2007
2008   structure = gst_structure_new_id (GST_QUARK (MESSAGE_PROGRESS),
2009       GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2010       GST_QUARK (CODE), G_TYPE_STRING, code,
2011       GST_QUARK (TEXT), G_TYPE_STRING, text,
2012       GST_QUARK (PERCENT), G_TYPE_INT, percent,
2013       GST_QUARK (TIMEOUT), G_TYPE_INT, timeout, NULL);
2014   message = gst_message_new_custom (GST_MESSAGE_PROGRESS, src, structure);
2015
2016   return message;
2017 }
2018
2019 /**
2020  * gst_message_parse_progress:
2021  * @message: A valid #GstMessage of type GST_MESSAGE_PROGRESS.
2022  * @type: (out) (allow-none): location for the type
2023  * @code: (out) (allow-none) (transfer full): location for the code
2024  * @text: (out) (allow-none) (transfer full): location for the text
2025  *
2026  * Parses the progress @type, @code and @text.
2027  */
2028 void
2029 gst_message_parse_progress (GstMessage * message, GstProgressType * type,
2030     gchar ** code, gchar ** text)
2031 {
2032   GstStructure *structure;
2033
2034   g_return_if_fail (GST_IS_MESSAGE (message));
2035   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_PROGRESS);
2036
2037   structure = GST_MESSAGE_STRUCTURE (message);
2038   gst_structure_id_get (structure,
2039       GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2040       GST_QUARK (CODE), G_TYPE_STRING, code,
2041       GST_QUARK (TEXT), G_TYPE_STRING, text, NULL);
2042 }
2043
2044 /**
2045  * gst_message_new_toc:
2046  * @src: the object originating the message.
2047  * @toc: (transfer none): #GstToc structure for the message.
2048  * @updated: whether TOC was updated or not.
2049  *
2050  * Create a new TOC message. The message is posted by elements
2051  * that discovered or updated a TOC.
2052  *
2053  * Returns: (transfer full): a new TOC message.
2054  *
2055  * MT safe.
2056  */
2057 GstMessage *
2058 gst_message_new_toc (GstObject * src, GstToc * toc, gboolean updated)
2059 {
2060   GstStructure *toc_struct;
2061
2062   g_return_val_if_fail (toc != NULL, NULL);
2063
2064   toc_struct = gst_structure_new_id (GST_QUARK (MESSAGE_TOC),
2065       GST_QUARK (TOC), GST_TYPE_TOC, toc,
2066       GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
2067
2068   return gst_message_new_custom (GST_MESSAGE_TOC, src, toc_struct);
2069 }
2070
2071 /**
2072  * gst_message_parse_toc:
2073  * @message: a valid #GstMessage of type GST_MESSAGE_TOC.
2074  * @toc: (out) (transfer full): return location for the TOC.
2075  * @updated: (out): return location for the updated flag.
2076  *
2077  * Extract the TOC from the #GstMessage. The TOC returned in the
2078  * output argument is a copy; the caller must free it with
2079  * gst_toc_unref() when done.
2080  *
2081  * MT safe.
2082  */
2083 void
2084 gst_message_parse_toc (GstMessage * message, GstToc ** toc, gboolean * updated)
2085 {
2086   g_return_if_fail (GST_IS_MESSAGE (message));
2087   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TOC);
2088   g_return_if_fail (toc != NULL);
2089
2090   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2091       GST_QUARK (TOC), GST_TYPE_TOC, toc,
2092       GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
2093 }
2094
2095 /**
2096  * gst_message_new_reset_time:
2097  * @src: (transfer none): The object originating the message.
2098  * @running_time: the requested running-time
2099  *
2100  * This message is posted when the pipeline running-time should be reset to
2101  * @running_time, like after a flushing seek.
2102  *
2103  * Returns: (transfer full): The new reset_time message.
2104  *
2105  * MT safe.
2106  */
2107 GstMessage *
2108 gst_message_new_reset_time (GstObject * src, GstClockTime running_time)
2109 {
2110   GstMessage *message;
2111   GstStructure *structure;
2112
2113   structure = gst_structure_new_id (GST_QUARK (MESSAGE_RESET_TIME),
2114       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
2115   message = gst_message_new_custom (GST_MESSAGE_RESET_TIME, src, structure);
2116
2117   return message;
2118 }
2119
2120 /**
2121  * gst_message_parse_reset_time:
2122  * @message: A valid #GstMessage of type GST_MESSAGE_RESET_TIME.
2123  * @running_time: (out) (allow-none): Result location for the running_time or
2124  *      %NULL
2125  *
2126  * Extract the running-time from the RESET_TIME message.
2127  *
2128  * MT safe.
2129  */
2130 void
2131 gst_message_parse_reset_time (GstMessage * message, GstClockTime * running_time)
2132 {
2133   GstStructure *structure;
2134
2135   g_return_if_fail (GST_IS_MESSAGE (message));
2136   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_RESET_TIME);
2137
2138   structure = GST_MESSAGE_STRUCTURE (message);
2139   if (running_time)
2140     *running_time =
2141         g_value_get_uint64 (gst_structure_id_get_value (structure,
2142             GST_QUARK (RUNNING_TIME)));
2143 }
2144
2145 /**
2146  * gst_message_new_stream_start:
2147  * @src: (transfer none): The object originating the message.
2148  *
2149  * Create a new stream_start message. This message is generated and posted in
2150  * the sink elements of a GstBin. The bin will only forward the STREAM_START
2151  * message to the application if all sinks have posted an STREAM_START message.
2152  *
2153  * Returns: (transfer full): The new stream_start message.
2154  *
2155  * MT safe.
2156  */
2157 GstMessage *
2158 gst_message_new_stream_start (GstObject * src)
2159 {
2160   GstMessage *message;
2161   GstStructure *s;
2162
2163   s = gst_structure_new_id_empty (GST_QUARK (MESSAGE_STREAM_START));
2164   message = gst_message_new_custom (GST_MESSAGE_STREAM_START, src, s);
2165
2166   return message;
2167 }
2168
2169
2170 /**
2171  * gst_message_set_group_id:
2172  * @message: the message
2173  * @group_id: the group id
2174  *
2175  * Sets the group id on the stream-start message.
2176  *
2177  * All streams that have the same group id are supposed to be played
2178  * together, i.e. all streams inside a container file should have the
2179  * same group id but different stream ids. The group id should change
2180  * each time the stream is started, resulting in different group ids
2181  * each time a file is played for example.
2182  *
2183  * MT safe.
2184  *
2185  * Since: 1.2
2186  */
2187 void
2188 gst_message_set_group_id (GstMessage * message, guint group_id)
2189 {
2190   GstStructure *structure;
2191
2192   g_return_if_fail (GST_IS_MESSAGE (message));
2193   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_START);
2194   g_return_if_fail (gst_message_is_writable (message));
2195
2196   structure = GST_MESSAGE_STRUCTURE (message);
2197   gst_structure_id_set (structure, GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id,
2198       NULL);
2199 }
2200
2201 /**
2202  * gst_message_parse_group_id:
2203  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_START.
2204  * @group_id: (out) (allow-none): Result location for the group id or
2205  *      %NULL
2206  *
2207  * Extract the group from the STREAM_START message.
2208  *
2209  * Returns: %TRUE if the message had a group id set, %FALSE otherwise
2210  *
2211  * MT safe.
2212  *
2213  * Since: 1.2
2214  */
2215 gboolean
2216 gst_message_parse_group_id (GstMessage * message, guint * group_id)
2217 {
2218   GstStructure *structure;
2219   const GValue *v;
2220
2221   g_return_val_if_fail (GST_IS_MESSAGE (message), FALSE);
2222   g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_START,
2223       FALSE);
2224
2225   if (!group_id)
2226     return TRUE;
2227
2228   structure = GST_MESSAGE_STRUCTURE (message);
2229
2230   v = gst_structure_id_get_value (structure, GST_QUARK (GROUP_ID));
2231   if (!v)
2232     return FALSE;
2233
2234   *group_id = g_value_get_uint (v);
2235   return TRUE;
2236 }
2237
2238 /**
2239  * gst_message_new_need_context:
2240  * @src: (transfer none): The object originating the message.
2241  * @context_type: The context type that is needed
2242  *
2243  * This message is posted when an element needs a specific #GstContext.
2244  *
2245  * Returns: (transfer full): The new need-context message.
2246  *
2247  * MT safe.
2248  *
2249  * Since: 1.2
2250  */
2251 GstMessage *
2252 gst_message_new_need_context (GstObject * src, const gchar * context_type)
2253 {
2254   GstMessage *message;
2255   GstStructure *structure;
2256
2257   g_return_val_if_fail (context_type != NULL, NULL);
2258
2259   structure = gst_structure_new_id (GST_QUARK (MESSAGE_NEED_CONTEXT),
2260       GST_QUARK (CONTEXT_TYPE), G_TYPE_STRING, context_type, NULL);
2261   message = gst_message_new_custom (GST_MESSAGE_NEED_CONTEXT, src, structure);
2262
2263   return message;
2264 }
2265
2266 /**
2267  * gst_message_parse_context_type:
2268  * @message: a GST_MESSAGE_NEED_CONTEXT type message
2269  * @context_type: (out) (allow-none): the context type, or %NULL
2270  *
2271  * Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message.
2272  *
2273  * Returns: a #gboolean indicating if the parsing succeeded.
2274  *
2275  * Since: 1.2
2276  */
2277 gboolean
2278 gst_message_parse_context_type (GstMessage * message,
2279     const gchar ** context_type)
2280 {
2281   GstStructure *structure;
2282   const GValue *value;
2283
2284   g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_NEED_CONTEXT,
2285       FALSE);
2286
2287   structure = GST_MESSAGE_STRUCTURE (message);
2288
2289   if (context_type) {
2290     value = gst_structure_id_get_value (structure, GST_QUARK (CONTEXT_TYPE));
2291     *context_type = g_value_get_string (value);
2292   }
2293
2294   return TRUE;
2295 }
2296
2297 /**
2298  * gst_message_new_have_context:
2299  * @src: (transfer none): The object originating the message.
2300  * @context: (transfer full): the context
2301  *
2302  * This message is posted when an element has a new local #GstContext.
2303  *
2304  * Returns: (transfer full): The new have-context message.
2305  *
2306  * MT safe.
2307  *
2308  * Since: 1.2
2309  */
2310 GstMessage *
2311 gst_message_new_have_context (GstObject * src, GstContext * context)
2312 {
2313   GstMessage *message;
2314   GstStructure *structure;
2315
2316   structure = gst_structure_new_id (GST_QUARK (MESSAGE_HAVE_CONTEXT),
2317       GST_QUARK (CONTEXT), GST_TYPE_CONTEXT, context, NULL);
2318   message = gst_message_new_custom (GST_MESSAGE_HAVE_CONTEXT, src, structure);
2319   gst_context_unref (context);
2320
2321   return message;
2322 }
2323
2324 /**
2325  * gst_message_parse_have_context:
2326  * @message: A valid #GstMessage of type GST_MESSAGE_HAVE_CONTEXT.
2327  * @context: (out) (transfer full) (allow-none): Result location for the
2328  *      context or %NULL
2329  *
2330  * Extract the context from the HAVE_CONTEXT message.
2331  *
2332  * MT safe.
2333  *
2334  * Since: 1.2
2335  */
2336 void
2337 gst_message_parse_have_context (GstMessage * message, GstContext ** context)
2338 {
2339   g_return_if_fail (GST_IS_MESSAGE (message));
2340   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_HAVE_CONTEXT);
2341
2342   if (context)
2343     gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2344         GST_QUARK (CONTEXT), GST_TYPE_CONTEXT, context, NULL);
2345 }
2346
2347 /**
2348  * gst_message_new_device_added:
2349  * @src: The #GstObject that created the message
2350  * @device: (transfer none): The new #GstDevice
2351  *
2352  * Creates a new device-added message. The device-added message is produced by
2353  * #GstDeviceProvider or a #GstDeviceMonitor. They announce the appearance
2354  * of monitored devices.
2355  *
2356  * Returns: a newly allocated #GstMessage
2357  *
2358  * Since: 1.4
2359  */
2360 GstMessage *
2361 gst_message_new_device_added (GstObject * src, GstDevice * device)
2362 {
2363   GstMessage *message;
2364   GstStructure *structure;
2365
2366   g_return_val_if_fail (device != NULL, NULL);
2367   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
2368
2369   structure = gst_structure_new_id (GST_QUARK (MESSAGE_DEVICE_ADDED),
2370       GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2371   message = gst_message_new_custom (GST_MESSAGE_DEVICE_ADDED, src, structure);
2372
2373   return message;
2374 }
2375
2376 /**
2377  * gst_message_parse_device_added:
2378  * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED
2379  * @device: (out) (allow-none) (transfer none): A location where to store a
2380  *  pointer to the new #GstDevice, or %NULL
2381  *
2382  * Parses a device-added message. The device-added message is produced by
2383  * #GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance
2384  * of monitored devices.
2385  *
2386  * Since: 1.4
2387  */
2388 void
2389 gst_message_parse_device_added (GstMessage * message, GstDevice ** device)
2390 {
2391   g_return_if_fail (GST_IS_MESSAGE (message));
2392   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_DEVICE_ADDED);
2393
2394   if (device)
2395     gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2396         GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2397 }
2398
2399 /**
2400  * gst_message_new_device_removed:
2401  * @src: The #GstObject that created the message
2402  * @device: (transfer none): The removed #GstDevice
2403  *
2404  * Creates a new device-removed message. The device-removed message is produced
2405  * by #GstDeviceProvider or a #GstDeviceMonitor. They announce the
2406  * disappearance of monitored devices.
2407  *
2408  * Returns: a newly allocated #GstMessage
2409  *
2410  * Since: 1.4
2411  */
2412 GstMessage *
2413 gst_message_new_device_removed (GstObject * src, GstDevice * device)
2414 {
2415   GstMessage *message;
2416   GstStructure *structure;
2417
2418   g_return_val_if_fail (device != NULL, NULL);
2419   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
2420
2421   structure = gst_structure_new_id (GST_QUARK (MESSAGE_DEVICE_REMOVED),
2422       GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2423   message = gst_message_new_custom (GST_MESSAGE_DEVICE_REMOVED, src, structure);
2424
2425   return message;
2426 }
2427
2428 /**
2429  * gst_message_parse_device_removed:
2430  * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED
2431  * @device: (out) (allow-none) (transfer none): A location where to store a
2432  *  pointer to the removed #GstDevice, or %NULL
2433  *
2434  * Parses a device-removed message. The device-removed message is produced by
2435  * #GstDeviceProvider or a #GstDeviceMonitor. It announces the
2436  * disappearance of monitored devices.
2437  *
2438  * Since: 1.4
2439  */
2440 void
2441 gst_message_parse_device_removed (GstMessage * message, GstDevice ** device)
2442 {
2443   g_return_if_fail (GST_IS_MESSAGE (message));
2444   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_DEVICE_REMOVED);
2445
2446   if (device)
2447     gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2448         GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2449 }