2 * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
4 * gstmessage.c: GstMessage subsystem
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.
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.
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.
24 * @short_description: Lightweight objects to signal the application of
26 * @see_also: #GstBus, #GstMiniObject, #GstElement
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
33 * Messages are posted by objects in the pipeline and are passed to the
34 * application using the #GstBus.
36 * The basic use pattern of posting a message on a #GstBus is as follows:
37 * |[<!-- language="C" -->
38 * gst_bus_post (bus, gst_message_new_eos());
41 * A #GstElement usually posts messages on the bus provided by the parent
42 * container using gst_element_post_message().
46 #include "gst_private.h"
47 #include <string.h> /* memcpy */
49 #include "gstenumtypes.h"
51 #include "gstmessage.h"
52 #include "gsttaglist.h"
62 GstStructure *structure;
65 #define GST_MESSAGE_STRUCTURE(m) (((GstMessageImpl *)(m))->structure)
74 static GstMessageQuarks message_quarks[] = {
75 {GST_MESSAGE_UNKNOWN, "unknown", 0},
76 {GST_MESSAGE_EOS, "eos", 0},
77 {GST_MESSAGE_ERROR, "error", 0},
78 {GST_MESSAGE_WARNING, "warning", 0},
79 {GST_MESSAGE_INFO, "info", 0},
80 {GST_MESSAGE_TAG, "tag", 0},
81 {GST_MESSAGE_BUFFERING, "buffering", 0},
82 {GST_MESSAGE_STATE_CHANGED, "state-changed", 0},
83 {GST_MESSAGE_STATE_DIRTY, "state-dirty", 0},
84 {GST_MESSAGE_STEP_DONE, "step-done", 0},
85 {GST_MESSAGE_CLOCK_PROVIDE, "clock-provide", 0},
86 {GST_MESSAGE_CLOCK_LOST, "clock-lost", 0},
87 {GST_MESSAGE_NEW_CLOCK, "new-clock", 0},
88 {GST_MESSAGE_STRUCTURE_CHANGE, "structure-change", 0},
89 {GST_MESSAGE_STREAM_STATUS, "stream-status", 0},
90 {GST_MESSAGE_APPLICATION, "application", 0},
91 {GST_MESSAGE_ELEMENT, "element", 0},
92 {GST_MESSAGE_SEGMENT_START, "segment-start", 0},
93 {GST_MESSAGE_SEGMENT_DONE, "segment-done", 0},
94 {GST_MESSAGE_DURATION_CHANGED, "duration-changed", 0},
95 {GST_MESSAGE_LATENCY, "latency", 0},
96 {GST_MESSAGE_ASYNC_START, "async-start", 0},
97 {GST_MESSAGE_ASYNC_DONE, "async-done", 0},
98 {GST_MESSAGE_REQUEST_STATE, "request-state", 0},
99 {GST_MESSAGE_STEP_START, "step-start", 0},
100 {GST_MESSAGE_QOS, "qos", 0},
101 {GST_MESSAGE_PROGRESS, "progress", 0},
102 {GST_MESSAGE_TOC, "toc", 0},
103 {GST_MESSAGE_RESET_TIME, "reset-time", 0},
104 {GST_MESSAGE_STREAM_START, "stream-start", 0},
105 {GST_MESSAGE_NEED_CONTEXT, "need-context", 0},
106 {GST_MESSAGE_HAVE_CONTEXT, "have-context", 0},
107 {GST_MESSAGE_DEVICE_ADDED, "device-added", 0},
108 {GST_MESSAGE_DEVICE_REMOVED, "device-removed", 0},
109 {GST_MESSAGE_PROPERTY_NOTIFY, "property-notify", 0},
110 {GST_MESSAGE_STREAM_COLLECTION, "stream-collection", 0},
111 {GST_MESSAGE_STREAMS_SELECTED, "streams-selected", 0},
115 static GQuark details_quark = 0;
117 GType _gst_message_type = 0;
118 GST_DEFINE_MINI_OBJECT_TYPE (GstMessage, gst_message);
121 _priv_gst_message_initialize (void)
125 GST_CAT_INFO (GST_CAT_GST_INIT, "init messages");
127 for (i = 0; message_quarks[i].name; i++) {
128 message_quarks[i].quark =
129 g_quark_from_static_string (message_quarks[i].name);
131 details_quark = g_quark_from_static_string ("details");
133 _gst_message_type = gst_message_get_type ();
137 * gst_message_type_get_name:
138 * @type: the message type
140 * Get a printable name for the given message type. Do not modify or free.
142 * Returns: a reference to the static name of the message.
145 gst_message_type_get_name (GstMessageType type)
149 for (i = 0; message_quarks[i].name; i++) {
150 if (type == message_quarks[i].type)
151 return message_quarks[i].name;
157 * gst_message_type_to_quark:
158 * @type: the message type
160 * Get the unique quark for the given message type.
162 * Returns: the quark associated with the message type
165 gst_message_type_to_quark (GstMessageType type)
169 for (i = 0; message_quarks[i].name; i++) {
170 if (type == message_quarks[i].type)
171 return message_quarks[i].quark;
177 _gst_message_dispose (GstMessage * message)
179 gboolean do_free = TRUE;
181 if (GST_MINI_OBJECT_FLAG_IS_SET (message, GST_MESSAGE_FLAG_ASYNC_DELIVERY)) {
182 /* revive message, so bus can finish with it and clean it up */
183 gst_message_ref (message);
185 GST_INFO ("[msg %p] signalling async free", message);
187 GST_MESSAGE_LOCK (message);
188 GST_MESSAGE_SIGNAL (message);
189 GST_MESSAGE_UNLOCK (message);
191 /* don't free it yet, let bus finish with it first */
199 _gst_message_free (GstMessage * message)
201 GstStructure *structure;
203 g_return_if_fail (message != NULL);
205 GST_CAT_LOG (GST_CAT_MESSAGE, "finalize message %p, %s from %s", message,
206 GST_MESSAGE_TYPE_NAME (message), GST_MESSAGE_SRC_NAME (message));
208 if (GST_MESSAGE_SRC (message)) {
209 gst_object_unref (GST_MESSAGE_SRC (message));
210 GST_MESSAGE_SRC (message) = NULL;
213 structure = GST_MESSAGE_STRUCTURE (message);
215 gst_structure_set_parent_refcount (structure, NULL);
216 gst_structure_free (structure);
219 g_slice_free1 (sizeof (GstMessageImpl), message);
223 gst_message_init (GstMessageImpl * message, GstMessageType type,
227 _gst_message_copy (GstMessage * message)
229 GstMessageImpl *copy;
230 GstStructure *structure;
232 GST_CAT_LOG (GST_CAT_MESSAGE, "copy message %p, %s from %s", message,
233 GST_MESSAGE_TYPE_NAME (message),
234 GST_OBJECT_NAME (GST_MESSAGE_SRC (message)));
236 copy = g_slice_new0 (GstMessageImpl);
238 gst_message_init (copy, GST_MESSAGE_TYPE (message),
239 GST_MESSAGE_SRC (message));
241 GST_MESSAGE_TIMESTAMP (copy) = GST_MESSAGE_TIMESTAMP (message);
242 GST_MESSAGE_SEQNUM (copy) = GST_MESSAGE_SEQNUM (message);
244 structure = GST_MESSAGE_STRUCTURE (message);
246 GST_MESSAGE_STRUCTURE (copy) = gst_structure_copy (structure);
247 gst_structure_set_parent_refcount (GST_MESSAGE_STRUCTURE (copy),
248 ©->message.mini_object.refcount);
250 GST_MESSAGE_STRUCTURE (copy) = NULL;
253 return GST_MESSAGE_CAST (copy);
257 gst_message_init (GstMessageImpl * message, GstMessageType type,
260 gst_mini_object_init (GST_MINI_OBJECT_CAST (message), 0, _gst_message_type,
261 (GstMiniObjectCopyFunction) _gst_message_copy,
262 (GstMiniObjectDisposeFunction) _gst_message_dispose,
263 (GstMiniObjectFreeFunction) _gst_message_free);
265 GST_MESSAGE_TYPE (message) = type;
267 gst_object_ref (src);
268 GST_MESSAGE_SRC (message) = src;
269 GST_MESSAGE_TIMESTAMP (message) = GST_CLOCK_TIME_NONE;
270 GST_MESSAGE_SEQNUM (message) = gst_util_seqnum_next ();
275 * gst_message_new_custom:
276 * @type: The #GstMessageType to distinguish messages
277 * @src: (transfer none) (allow-none): The object originating the message.
278 * @structure: (transfer full) (allow-none): the structure for the
279 * message. The message will take ownership of the structure.
281 * Create a new custom-typed message. This can be used for anything not
282 * handled by other message-specific functions to pass a message to the
283 * app. The structure field can be %NULL.
285 * Returns: (transfer full): The new message.
290 gst_message_new_custom (GstMessageType type, GstObject * src,
291 GstStructure * structure)
293 GstMessageImpl *message;
295 message = g_slice_new0 (GstMessageImpl);
297 GST_CAT_LOG (GST_CAT_MESSAGE, "source %s: creating new message %p %s",
298 (src ? GST_OBJECT_NAME (src) : "NULL"), message,
299 gst_message_type_get_name (type));
302 /* structure must not have a parent */
303 if (!gst_structure_set_parent_refcount (structure,
304 &message->message.mini_object.refcount))
307 gst_message_init (message, type, src);
309 GST_MESSAGE_STRUCTURE (message) = structure;
311 return GST_MESSAGE_CAST (message);
316 g_slice_free1 (sizeof (GstMessageImpl), message);
317 g_warning ("structure is already owned by another object");
323 * gst_message_get_seqnum:
324 * @message: A #GstMessage.
326 * Retrieve the sequence number of a message.
328 * Messages have ever-incrementing sequence numbers, which may also be set
329 * explicitly via gst_message_set_seqnum(). Sequence numbers are typically used
330 * to indicate that a message corresponds to some other set of messages or
331 * events, for example a SEGMENT_DONE message corresponding to a SEEK event. It
332 * is considered good practice to make this correspondence when possible, though
333 * it is not required.
335 * Note that events and messages share the same sequence number incrementor;
336 * two events or messages will never have the same sequence number unless
337 * that correspondence was made explicitly.
339 * Returns: The message's sequence number.
344 gst_message_get_seqnum (GstMessage * message)
346 g_return_val_if_fail (GST_IS_MESSAGE (message), -1);
348 return GST_MESSAGE_SEQNUM (message);
352 * gst_message_set_seqnum:
353 * @message: A #GstMessage.
354 * @seqnum: A sequence number.
356 * Set the sequence number of a message.
358 * This function might be called by the creator of a message to indicate that
359 * the message relates to other messages or events. See gst_message_get_seqnum()
360 * for more information.
365 gst_message_set_seqnum (GstMessage * message, guint32 seqnum)
367 g_return_if_fail (GST_IS_MESSAGE (message));
369 GST_MESSAGE_SEQNUM (message) = seqnum;
373 * gst_message_new_eos:
374 * @src: (transfer none) (allow-none): The object originating the message.
376 * Create a new eos message. This message is generated and posted in
377 * the sink elements of a GstBin. The bin will only forward the EOS
378 * message to the application if all sinks have posted an EOS message.
380 * Returns: (transfer full): The new eos message.
385 gst_message_new_eos (GstObject * src)
389 message = gst_message_new_custom (GST_MESSAGE_EOS, src, NULL);
395 * gst_message_new_error_with_details:
396 * @src: (transfer none) (allow-none): The object originating the message.
397 * @error: (transfer none): The GError for this message.
398 * @debug: A debugging string.
399 * @details: (transfer full): (allow-none): A GstStructure with details
401 * Create a new error message. The message will copy @error and
402 * @debug. This message is posted by element when a fatal event
403 * occurred. The pipeline will probably (partially) stop. The application
404 * receiving this message should stop the pipeline.
406 * Returns: (transfer full): the new error message.
413 gst_message_new_error_with_details (GstObject * src, GError * error,
414 const gchar * debug, GstStructure * details)
417 GstStructure *structure;
419 structure = gst_structure_new_id (GST_QUARK (MESSAGE_ERROR),
420 GST_QUARK (GERROR), G_TYPE_ERROR, error,
421 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
422 message = gst_message_new_custom (GST_MESSAGE_ERROR, src, structure);
424 GValue v = G_VALUE_INIT;
426 g_value_init (&v, GST_TYPE_STRUCTURE);
427 g_value_take_boxed (&v, details);
428 gst_structure_id_take_value (GST_MESSAGE_STRUCTURE (message), details_quark,
436 * gst_message_new_error:
437 * @src: (transfer none) (allow-none): The object originating the message.
438 * @error: (transfer none): The GError for this message.
439 * @debug: A debugging string.
441 * Create a new error message. The message will copy @error and
442 * @debug. This message is posted by element when a fatal event
443 * occurred. The pipeline will probably (partially) stop. The application
444 * receiving this message should stop the pipeline.
446 * Returns: (transfer full): the new error message.
451 gst_message_new_error (GstObject * src, GError * error, const gchar * debug)
453 return gst_message_new_error_with_details (src, error, debug, NULL);
457 * gst_message_parse_error_details:
458 * @message: The message object
459 * @structure: (out): A pointer to the returned details
461 * Returns the optional details structure, may be NULL if none.
462 * The returned structure must not be freed.
469 gst_message_parse_error_details (GstMessage * message,
470 const GstStructure ** structure)
474 g_return_if_fail (GST_IS_MESSAGE (message));
475 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ERROR);
476 g_return_if_fail (structure != NULL);
479 v = gst_structure_id_get_value (GST_MESSAGE_STRUCTURE (message),
482 *structure = g_value_get_boxed (v);
487 * gst_message_new_warning_with_details:
488 * @src: (transfer none) (allow-none): The object originating the message.
489 * @error: (transfer none): The GError for this message.
490 * @debug: A debugging string.
491 * @details: (transfer full): (allow-none): A GstStructure with details
493 * Create a new warning message. The message will make copies of @error and
496 * Returns: (transfer full): the new warning message.
503 gst_message_new_warning_with_details (GstObject * src, GError * error,
504 const gchar * debug, GstStructure * details)
507 GstStructure *structure;
509 structure = gst_structure_new_id (GST_QUARK (MESSAGE_WARNING),
510 GST_QUARK (GERROR), G_TYPE_ERROR, error,
511 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
512 message = gst_message_new_custom (GST_MESSAGE_WARNING, src, structure);
514 GValue v = G_VALUE_INIT;
516 g_value_init (&v, GST_TYPE_STRUCTURE);
517 g_value_take_boxed (&v, details);
518 gst_structure_id_take_value (GST_MESSAGE_STRUCTURE (message), details_quark,
526 * gst_message_new_warning:
527 * @src: (transfer none) (allow-none): The object originating the message.
528 * @error: (transfer none): The GError for this message.
529 * @debug: A debugging string.
531 * Create a new warning message. The message will make copies of @error and
534 * Returns: (transfer full): the new warning message.
539 gst_message_new_warning (GstObject * src, GError * error, const gchar * debug)
541 return gst_message_new_warning_with_details (src, error, debug, NULL);
545 * gst_message_parse_warning_details:
546 * @message: The message object
547 * @structure: (out): A pointer to the returned details structure
549 * Returns the optional details structure, may be NULL if none
550 * The returned structure must not be freed.
557 gst_message_parse_warning_details (GstMessage * message,
558 const GstStructure ** structure)
562 g_return_if_fail (GST_IS_MESSAGE (message));
563 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_WARNING);
564 g_return_if_fail (structure != NULL);
567 v = gst_structure_id_get_value (GST_MESSAGE_STRUCTURE (message),
570 *structure = g_value_get_boxed (v);
575 * gst_message_new_info_with_details:
576 * @src: (transfer none) (allow-none): The object originating the message.
577 * @error: (transfer none): The GError for this message.
578 * @debug: A debugging string.
579 * @details: (transfer full): (allow-none): A GstStructure with details
581 * Create a new info message. The message will make copies of @error and
584 * Returns: (transfer full): the new warning message.
591 gst_message_new_info_with_details (GstObject * src, GError * error,
592 const gchar * debug, GstStructure * details)
595 GstStructure *structure;
597 structure = gst_structure_new_id (GST_QUARK (MESSAGE_INFO),
598 GST_QUARK (GERROR), G_TYPE_ERROR, error,
599 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
600 message = gst_message_new_custom (GST_MESSAGE_INFO, src, structure);
602 GValue v = G_VALUE_INIT;
604 g_value_init (&v, GST_TYPE_STRUCTURE);
605 g_value_take_boxed (&v, details);
606 gst_structure_id_take_value (GST_MESSAGE_STRUCTURE (message), details_quark,
614 * gst_message_new_info:
615 * @src: (transfer none) (allow-none): The object originating the message.
616 * @error: (transfer none): The GError for this message.
617 * @debug: A debugging string.
619 * Create a new info message. The message will make copies of @error and
622 * Returns: (transfer full): the new info message.
627 gst_message_new_info (GstObject * src, GError * error, const gchar * debug)
629 return gst_message_new_info_with_details (src, error, debug, NULL);
633 * gst_message_parse_info_details:
634 * @message: The message object
635 * @structure: (out): A pointer to the returned details structure
637 * Returns the optional details structure, may be NULL if none
638 * The returned structure must not be freed.
645 gst_message_parse_info_details (GstMessage * message,
646 const GstStructure ** structure)
650 g_return_if_fail (GST_IS_MESSAGE (message));
651 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_INFO);
652 g_return_if_fail (structure != NULL);
655 v = gst_structure_id_get_value (GST_MESSAGE_STRUCTURE (message),
658 *structure = g_value_get_boxed (v);
663 * gst_message_new_tag:
664 * @src: (transfer none) (allow-none): The object originating the message.
665 * @tag_list: (transfer full): the tag list for the message.
667 * Create a new tag message. The message will take ownership of the tag list.
668 * The message is posted by elements that discovered a new taglist.
670 * Returns: (transfer full): the new tag message.
675 gst_message_new_tag (GstObject * src, GstTagList * tag_list)
679 GValue val = G_VALUE_INIT;
681 g_return_val_if_fail (GST_IS_TAG_LIST (tag_list), NULL);
683 s = gst_structure_new_id_empty (GST_QUARK (MESSAGE_TAG));
684 g_value_init (&val, GST_TYPE_TAG_LIST);
685 g_value_take_boxed (&val, tag_list);
686 gst_structure_id_take_value (s, GST_QUARK (TAGLIST), &val);
687 message = gst_message_new_custom (GST_MESSAGE_TAG, src, s);
692 * gst_message_new_buffering:
693 * @src: (transfer none) (allow-none): The object originating the message.
694 * @percent: The buffering percent
696 * Create a new buffering message. This message can be posted by an element that
697 * needs to buffer data before it can continue processing. @percent should be a
698 * value between 0 and 100. A value of 100 means that the buffering completed.
700 * When @percent is < 100 the application should PAUSE a PLAYING pipeline. When
701 * @percent is 100, the application can set the pipeline (back) to PLAYING.
702 * The application must be prepared to receive BUFFERING messages in the
703 * PREROLLING state and may only set the pipeline to PLAYING after receiving a
704 * message with @percent set to 100, which can happen after the pipeline
705 * completed prerolling.
709 * Returns: (transfer full): The new buffering message.
712 gst_message_new_buffering (GstObject * src, gint percent)
715 GstStructure *structure;
716 gint64 buffering_left;
718 g_return_val_if_fail (percent >= 0 && percent <= 100, NULL);
720 buffering_left = (percent == 100 ? 0 : -1);
722 structure = gst_structure_new_id (GST_QUARK (MESSAGE_BUFFERING),
723 GST_QUARK (BUFFER_PERCENT), G_TYPE_INT, percent,
724 GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, GST_BUFFERING_STREAM,
725 GST_QUARK (AVG_IN_RATE), G_TYPE_INT, -1,
726 GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, -1,
727 GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
728 message = gst_message_new_custom (GST_MESSAGE_BUFFERING, src, structure);
734 * gst_message_new_state_changed:
735 * @src: (transfer none) (allow-none): The object originating the message.
736 * @oldstate: the previous state
737 * @newstate: the new (current) state
738 * @pending: the pending (target) state
740 * Create a state change message. This message is posted whenever an element
743 * Returns: (transfer full): the new state change message.
748 gst_message_new_state_changed (GstObject * src,
749 GstState oldstate, GstState newstate, GstState pending)
752 GstStructure *structure;
754 structure = gst_structure_new_id (GST_QUARK (MESSAGE_STATE_CHANGED),
755 GST_QUARK (OLD_STATE), GST_TYPE_STATE, (gint) oldstate,
756 GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) newstate,
757 GST_QUARK (PENDING_STATE), GST_TYPE_STATE, (gint) pending, NULL);
758 message = gst_message_new_custom (GST_MESSAGE_STATE_CHANGED, src, structure);
764 * gst_message_new_state_dirty:
765 * @src: (transfer none) (allow-none): The object originating the message
767 * Create a state dirty message. This message is posted whenever an element
768 * changed its state asynchronously and is used internally to update the
769 * states of container objects.
771 * Returns: (transfer full): the new state dirty message.
776 gst_message_new_state_dirty (GstObject * src)
780 message = gst_message_new_custom (GST_MESSAGE_STATE_DIRTY, src, NULL);
786 * gst_message_new_clock_provide:
787 * @src: (transfer none) (allow-none): The object originating the message.
788 * @clock: (transfer none): the clock it provides
789 * @ready: %TRUE if the sender can provide a clock
791 * Create a clock provide message. This message is posted whenever an
792 * element is ready to provide a clock or lost its ability to provide
793 * a clock (maybe because it paused or became EOS).
795 * This message is mainly used internally to manage the clock
798 * Returns: (transfer full): the new provide clock message.
803 gst_message_new_clock_provide (GstObject * src, GstClock * clock,
807 GstStructure *structure;
809 structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_PROVIDE),
810 GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock,
811 GST_QUARK (READY), G_TYPE_BOOLEAN, ready, NULL);
812 message = gst_message_new_custom (GST_MESSAGE_CLOCK_PROVIDE, src, structure);
818 * gst_message_new_clock_lost:
819 * @src: (transfer none) (allow-none): The object originating the message.
820 * @clock: (transfer none): the clock that was lost
822 * Create a clock lost message. This message is posted whenever the
823 * clock is not valid anymore.
825 * If this message is posted by the pipeline, the pipeline will
826 * select a new clock again when it goes to PLAYING. It might therefore
827 * be needed to set the pipeline to PAUSED and PLAYING again.
829 * Returns: (transfer full): The new clock lost message.
834 gst_message_new_clock_lost (GstObject * src, GstClock * clock)
837 GstStructure *structure;
839 structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_LOST),
840 GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
841 message = gst_message_new_custom (GST_MESSAGE_CLOCK_LOST, src, structure);
847 * gst_message_new_new_clock:
848 * @src: (transfer none) (allow-none): The object originating the message.
849 * @clock: (transfer none): the new selected clock
851 * Create a new clock message. This message is posted whenever the
852 * pipeline selects a new clock for the pipeline.
854 * Returns: (transfer full): The new new clock message.
859 gst_message_new_new_clock (GstObject * src, GstClock * clock)
862 GstStructure *structure;
864 structure = gst_structure_new_id (GST_QUARK (MESSAGE_NEW_CLOCK),
865 GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
866 message = gst_message_new_custom (GST_MESSAGE_NEW_CLOCK, src, structure);
872 * gst_message_new_structure_change:
873 * @src: (transfer none) (allow-none): The object originating the message.
874 * @type: The change type.
875 * @owner: (transfer none): The owner element of @src.
876 * @busy: Whether the structure change is busy.
878 * Create a new structure change message. This message is posted when the
879 * structure of a pipeline is in the process of being changed, for example
880 * when pads are linked or unlinked.
882 * @src should be the sinkpad that unlinked or linked.
884 * Returns: (transfer full): the new structure change message.
889 gst_message_new_structure_change (GstObject * src, GstStructureChangeType type,
890 GstElement * owner, gboolean busy)
893 GstStructure *structure;
895 g_return_val_if_fail (GST_IS_PAD (src), NULL);
896 /* g_return_val_if_fail (GST_PAD_DIRECTION (src) == GST_PAD_SINK, NULL); */
897 g_return_val_if_fail (GST_IS_ELEMENT (owner), NULL);
899 structure = gst_structure_new_id (GST_QUARK (MESSAGE_STRUCTURE_CHANGE),
900 GST_QUARK (TYPE), GST_TYPE_STRUCTURE_CHANGE_TYPE, type,
901 GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner,
902 GST_QUARK (BUSY), G_TYPE_BOOLEAN, busy, NULL);
904 message = gst_message_new_custom (GST_MESSAGE_STRUCTURE_CHANGE, src,
911 * gst_message_new_segment_start:
912 * @src: (transfer none) (allow-none): The object originating the message.
913 * @format: The format of the position being played
914 * @position: The position of the segment being played
916 * Create a new segment message. This message is posted by elements that
917 * start playback of a segment as a result of a segment seek. This message
918 * is not received by the application but is used for maintenance reasons in
919 * container elements.
921 * Returns: (transfer full): the new segment start message.
926 gst_message_new_segment_start (GstObject * src, GstFormat format,
930 GstStructure *structure;
932 structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_START),
933 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
934 GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
935 message = gst_message_new_custom (GST_MESSAGE_SEGMENT_START, src, structure);
941 * gst_message_new_segment_done:
942 * @src: (transfer none) (allow-none): The object originating the message.
943 * @format: The format of the position being done
944 * @position: The position of the segment being done
946 * Create a new segment done message. This message is posted by elements that
947 * finish playback of a segment as a result of a segment seek. This message
948 * is received by the application after all elements that posted a segment_start
949 * have posted the segment_done.
951 * Returns: (transfer full): the new segment done message.
956 gst_message_new_segment_done (GstObject * src, GstFormat format,
960 GstStructure *structure;
962 structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_DONE),
963 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
964 GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
965 message = gst_message_new_custom (GST_MESSAGE_SEGMENT_DONE, src, structure);
971 * gst_message_new_application:
972 * @src: (transfer none) (allow-none): The object originating the message.
973 * @structure: (transfer full): the structure for the message. The message
974 * will take ownership of the structure.
976 * Create a new application-typed message. GStreamer will never create these
977 * messages; they are a gift from us to you. Enjoy.
979 * Returns: (transfer full): The new application message.
984 gst_message_new_application (GstObject * src, GstStructure * structure)
986 g_return_val_if_fail (structure != NULL, NULL);
988 return gst_message_new_custom (GST_MESSAGE_APPLICATION, src, structure);
992 * gst_message_new_element:
993 * @src: (transfer none) (allow-none): The object originating the message.
994 * @structure: (transfer full): The structure for the
995 * message. The message will take ownership of the structure.
997 * Create a new element-specific message. This is meant as a generic way of
998 * allowing one-way communication from an element to an application, for example
999 * "the firewire cable was unplugged". The format of the message should be
1000 * documented in the element's documentation. The structure field can be %NULL.
1002 * Returns: (transfer full): The new element message.
1007 gst_message_new_element (GstObject * src, GstStructure * structure)
1009 g_return_val_if_fail (structure != NULL, NULL);
1011 return gst_message_new_custom (GST_MESSAGE_ELEMENT, src, structure);
1015 * gst_message_new_duration_changed:
1016 * @src: (transfer none) (allow-none): The object originating the message.
1018 * Create a new duration changed message. This message is posted by elements
1019 * that know the duration of a stream when the duration changes. This message
1020 * is received by bins and is used to calculate the total duration of a
1021 * pipeline. Elements may post a duration message with a duration of
1022 * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the
1023 * cached duration should be discarded. The new duration can then be
1024 * retrieved via a query.
1026 * Returns: (transfer full): The new duration-changed message.
1031 gst_message_new_duration_changed (GstObject * src)
1033 GstMessage *message;
1035 message = gst_message_new_custom (GST_MESSAGE_DURATION_CHANGED, src,
1036 gst_structure_new_id_empty (GST_QUARK (MESSAGE_DURATION_CHANGED)));
1042 * gst_message_new_async_start:
1043 * @src: (transfer none) (allow-none): The object originating the message.
1045 * This message is posted by elements when they start an ASYNC state change.
1047 * Returns: (transfer full): The new async_start message.
1052 gst_message_new_async_start (GstObject * src)
1054 GstMessage *message;
1056 message = gst_message_new_custom (GST_MESSAGE_ASYNC_START, src, NULL);
1062 * gst_message_new_async_done:
1063 * @src: (transfer none) (allow-none): The object originating the message.
1064 * @running_time: the desired running_time
1066 * The message is posted when elements completed an ASYNC state change.
1067 * @running_time contains the time of the desired running_time when this
1068 * elements goes to PLAYING. A value of #GST_CLOCK_TIME_NONE for @running_time
1069 * means that the element has no clock interaction and thus doesn't care about
1070 * the running_time of the pipeline.
1072 * Returns: (transfer full): The new async_done message.
1077 gst_message_new_async_done (GstObject * src, GstClockTime running_time)
1079 GstMessage *message;
1080 GstStructure *structure;
1082 structure = gst_structure_new_id (GST_QUARK (MESSAGE_ASYNC_DONE),
1083 GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
1084 message = gst_message_new_custom (GST_MESSAGE_ASYNC_DONE, src, structure);
1090 * gst_message_new_latency:
1091 * @src: (transfer none) (allow-none): The object originating the message.
1093 * This message can be posted by elements when their latency requirements have
1096 * Returns: (transfer full): The new latency message.
1101 gst_message_new_latency (GstObject * src)
1103 GstMessage *message;
1105 message = gst_message_new_custom (GST_MESSAGE_LATENCY, src, NULL);
1111 * gst_message_new_request_state:
1112 * @src: (transfer none) (allow-none): The object originating the message.
1113 * @state: The new requested state
1115 * This message can be posted by elements when they want to have their state
1116 * changed. A typical use case would be an audio server that wants to pause the
1117 * pipeline because a higher priority stream is being played.
1119 * Returns: (transfer full): the new request state message.
1124 gst_message_new_request_state (GstObject * src, GstState state)
1126 GstMessage *message;
1127 GstStructure *structure;
1129 structure = gst_structure_new_id (GST_QUARK (MESSAGE_REQUEST_STATE),
1130 GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) state, NULL);
1131 message = gst_message_new_custom (GST_MESSAGE_REQUEST_STATE, src, structure);
1137 * gst_message_get_structure:
1138 * @message: The #GstMessage.
1140 * Access the structure of the message.
1142 * Returns: (transfer none): The structure of the message. The structure is
1143 * still owned by the message, which means that you should not free it and
1144 * that the pointer becomes invalid when you free the message.
1148 const GstStructure *
1149 gst_message_get_structure (GstMessage * message)
1151 g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
1153 return GST_MESSAGE_STRUCTURE (message);
1157 * gst_message_has_name:
1158 * @message: The #GstMessage.
1159 * @name: name to check
1161 * Checks if @message has the given @name. This function is usually used to
1162 * check the name of a custom message.
1164 * Returns: %TRUE if @name matches the name of the message structure.
1167 gst_message_has_name (GstMessage * message, const gchar * name)
1169 GstStructure *structure;
1171 g_return_val_if_fail (GST_IS_MESSAGE (message), FALSE);
1173 structure = GST_MESSAGE_STRUCTURE (message);
1174 if (structure == NULL)
1177 return gst_structure_has_name (structure, name);
1181 * gst_message_parse_tag:
1182 * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
1183 * @tag_list: (out callee-allocates): return location for the tag-list.
1185 * Extracts the tag list from the GstMessage. The tag list returned in the
1186 * output argument is a copy; the caller must free it when done.
1188 * Typical usage of this function might be:
1189 * |[<!-- language="C" -->
1191 * switch (GST_MESSAGE_TYPE (msg)) {
1192 * case GST_MESSAGE_TAG: {
1193 * GstTagList *tags = NULL;
1195 * gst_message_parse_tag (msg, &tags);
1196 * g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
1197 * handle_tags (tags);
1198 * gst_tag_list_unref (tags);
1209 gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
1211 g_return_if_fail (GST_IS_MESSAGE (message));
1212 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TAG);
1213 g_return_if_fail (tag_list != NULL);
1215 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1216 GST_QUARK (TAGLIST), GST_TYPE_TAG_LIST, tag_list, NULL);
1220 * gst_message_parse_buffering:
1221 * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1222 * @percent: (out) (allow-none): Return location for the percent.
1224 * Extracts the buffering percent from the GstMessage. see also
1225 * gst_message_new_buffering().
1230 gst_message_parse_buffering (GstMessage * message, gint * percent)
1232 g_return_if_fail (GST_IS_MESSAGE (message));
1233 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1237 g_value_get_int (gst_structure_id_get_value (GST_MESSAGE_STRUCTURE
1238 (message), GST_QUARK (BUFFER_PERCENT)));
1242 * gst_message_set_buffering_stats:
1243 * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1244 * @mode: a buffering mode
1245 * @avg_in: the average input rate
1246 * @avg_out: the average output rate
1247 * @buffering_left: amount of buffering time left in milliseconds
1249 * Configures the buffering stats values in @message.
1252 gst_message_set_buffering_stats (GstMessage * message, GstBufferingMode mode,
1253 gint avg_in, gint avg_out, gint64 buffering_left)
1255 g_return_if_fail (GST_IS_MESSAGE (message));
1256 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1258 gst_structure_id_set (GST_MESSAGE_STRUCTURE (message),
1259 GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, mode,
1260 GST_QUARK (AVG_IN_RATE), G_TYPE_INT, avg_in,
1261 GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, avg_out,
1262 GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
1266 * gst_message_parse_buffering_stats:
1267 * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1268 * @mode: (out) (allow-none): a buffering mode, or %NULL
1269 * @avg_in: (out) (allow-none): the average input rate, or %NULL
1270 * @avg_out: (out) (allow-none): the average output rate, or %NULL
1271 * @buffering_left: (out) (allow-none): amount of buffering time left in
1272 * milliseconds, or %NULL
1274 * Extracts the buffering stats values from @message.
1277 gst_message_parse_buffering_stats (GstMessage * message,
1278 GstBufferingMode * mode, gint * avg_in, gint * avg_out,
1279 gint64 * buffering_left)
1281 GstStructure *structure;
1283 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1285 structure = GST_MESSAGE_STRUCTURE (message);
1287 *mode = (GstBufferingMode)
1288 g_value_get_enum (gst_structure_id_get_value (structure,
1289 GST_QUARK (BUFFERING_MODE)));
1291 *avg_in = g_value_get_int (gst_structure_id_get_value (structure,
1292 GST_QUARK (AVG_IN_RATE)));
1294 *avg_out = g_value_get_int (gst_structure_id_get_value (structure,
1295 GST_QUARK (AVG_OUT_RATE)));
1298 g_value_get_int64 (gst_structure_id_get_value (structure,
1299 GST_QUARK (BUFFERING_LEFT)));
1303 * gst_message_parse_state_changed:
1304 * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED
1305 * @oldstate: (out) (allow-none): the previous state, or %NULL
1306 * @newstate: (out) (allow-none): the new (current) state, or %NULL
1307 * @pending: (out) (allow-none): the pending (target) state, or %NULL
1309 * Extracts the old and new states from the GstMessage.
1311 * Typical usage of this function might be:
1312 * |[<!-- language="C" -->
1314 * switch (GST_MESSAGE_TYPE (msg)) {
1315 * case GST_MESSAGE_STATE_CHANGED: {
1316 * GstState old_state, new_state;
1318 * gst_message_parse_state_changed (msg, &old_state, &new_state, NULL);
1319 * g_print ("Element %s changed state from %s to %s.\n",
1320 * GST_OBJECT_NAME (msg->src),
1321 * gst_element_state_get_name (old_state),
1322 * gst_element_state_get_name (new_state));
1333 gst_message_parse_state_changed (GstMessage * message,
1334 GstState * oldstate, GstState * newstate, GstState * pending)
1336 GstStructure *structure;
1338 g_return_if_fail (GST_IS_MESSAGE (message));
1339 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STATE_CHANGED);
1341 structure = GST_MESSAGE_STRUCTURE (message);
1343 *oldstate = (GstState)
1344 g_value_get_enum (gst_structure_id_get_value (structure,
1345 GST_QUARK (OLD_STATE)));
1347 *newstate = (GstState)
1348 g_value_get_enum (gst_structure_id_get_value (structure,
1349 GST_QUARK (NEW_STATE)));
1351 *pending = (GstState)
1352 g_value_get_enum (gst_structure_id_get_value (structure,
1353 GST_QUARK (PENDING_STATE)));
1357 * gst_message_parse_clock_provide:
1358 * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.
1359 * @clock: (out) (allow-none) (transfer none): a pointer to hold a clock
1361 * @ready: (out) (allow-none): a pointer to hold the ready flag, or %NULL
1363 * Extracts the clock and ready flag from the GstMessage.
1364 * The clock object returned remains valid until the message is freed.
1369 gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock,
1372 const GValue *clock_gvalue;
1373 GstStructure *structure;
1375 g_return_if_fail (GST_IS_MESSAGE (message));
1376 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_PROVIDE);
1378 structure = GST_MESSAGE_STRUCTURE (message);
1379 clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1380 g_return_if_fail (clock_gvalue != NULL);
1381 g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1385 g_value_get_boolean (gst_structure_id_get_value (structure,
1386 GST_QUARK (READY)));
1388 *clock = (GstClock *) g_value_get_object (clock_gvalue);
1392 * gst_message_parse_clock_lost:
1393 * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST.
1394 * @clock: (out) (allow-none) (transfer none): a pointer to hold the lost clock
1396 * Extracts the lost clock from the GstMessage.
1397 * The clock object returned remains valid until the message is freed.
1402 gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock)
1404 const GValue *clock_gvalue;
1405 GstStructure *structure;
1407 g_return_if_fail (GST_IS_MESSAGE (message));
1408 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_LOST);
1410 structure = GST_MESSAGE_STRUCTURE (message);
1411 clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1412 g_return_if_fail (clock_gvalue != NULL);
1413 g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1416 *clock = (GstClock *) g_value_get_object (clock_gvalue);
1420 * gst_message_parse_new_clock:
1421 * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK.
1422 * @clock: (out) (allow-none) (transfer none): a pointer to hold the selected
1425 * Extracts the new clock from the GstMessage.
1426 * The clock object returned remains valid until the message is freed.
1431 gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)
1433 const GValue *clock_gvalue;
1434 GstStructure *structure;
1436 g_return_if_fail (GST_IS_MESSAGE (message));
1437 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_NEW_CLOCK);
1439 structure = GST_MESSAGE_STRUCTURE (message);
1440 clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1441 g_return_if_fail (clock_gvalue != NULL);
1442 g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1445 *clock = (GstClock *) g_value_get_object (clock_gvalue);
1449 * gst_message_parse_structure_change:
1450 * @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.
1451 * @type: (out): A pointer to hold the change type
1452 * @owner: (out) (allow-none) (transfer none): The owner element of the
1454 * @busy: (out) (allow-none): a pointer to hold whether the change is in
1455 * progress or has been completed
1457 * Extracts the change type and completion status from the GstMessage.
1462 gst_message_parse_structure_change (GstMessage * message,
1463 GstStructureChangeType * type, GstElement ** owner, gboolean * busy)
1465 const GValue *owner_gvalue;
1466 GstStructure *structure;
1468 g_return_if_fail (GST_IS_MESSAGE (message));
1469 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STRUCTURE_CHANGE);
1471 structure = GST_MESSAGE_STRUCTURE (message);
1472 owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1473 g_return_if_fail (owner_gvalue != NULL);
1474 g_return_if_fail (G_VALUE_TYPE (owner_gvalue) == GST_TYPE_ELEMENT);
1477 *type = (GstStructureChangeType)
1478 g_value_get_enum (gst_structure_id_get_value (structure,
1481 *owner = (GstElement *) g_value_get_object (owner_gvalue);
1484 g_value_get_boolean (gst_structure_id_get_value (structure,
1489 * gst_message_parse_error:
1490 * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
1491 * @gerror: (out) (allow-none) (transfer full): location for the GError
1492 * @debug: (out) (allow-none) (transfer full): location for the debug message,
1495 * Extracts the GError and debug string from the GstMessage. The values returned
1496 * in the output arguments are copies; the caller must free them when done.
1498 * Typical usage of this function might be:
1499 * |[<!-- language="C" -->
1501 * switch (GST_MESSAGE_TYPE (msg)) {
1502 * case GST_MESSAGE_ERROR: {
1503 * GError *err = NULL;
1504 * gchar *dbg_info = NULL;
1506 * gst_message_parse_error (msg, &err, &dbg_info);
1507 * g_printerr ("ERROR from element %s: %s\n",
1508 * GST_OBJECT_NAME (msg->src), err->message);
1509 * g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none");
1510 * g_error_free (err);
1511 * g_free (dbg_info);
1522 gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
1524 g_return_if_fail (GST_IS_MESSAGE (message));
1525 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ERROR);
1527 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1528 GST_QUARK (GERROR), G_TYPE_ERROR, gerror,
1529 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
1533 * gst_message_parse_warning:
1534 * @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
1535 * @gerror: (out) (allow-none) (transfer full): location for the GError
1536 * @debug: (out) (allow-none) (transfer full): location for the debug message,
1539 * Extracts the GError and debug string from the GstMessage. The values returned
1540 * in the output arguments are copies; the caller must free them when done.
1545 gst_message_parse_warning (GstMessage * message, GError ** gerror,
1548 g_return_if_fail (GST_IS_MESSAGE (message));
1549 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_WARNING);
1551 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1552 GST_QUARK (GERROR), G_TYPE_ERROR, gerror,
1553 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
1557 * gst_message_parse_info:
1558 * @message: A valid #GstMessage of type GST_MESSAGE_INFO.
1559 * @gerror: (out) (allow-none) (transfer full): location for the GError
1560 * @debug: (out) (allow-none) (transfer full): location for the debug message,
1563 * Extracts the GError and debug string from the GstMessage. The values returned
1564 * in the output arguments are copies; the caller must free them when done.
1569 gst_message_parse_info (GstMessage * message, GError ** gerror, gchar ** debug)
1571 g_return_if_fail (GST_IS_MESSAGE (message));
1572 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_INFO);
1574 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1575 GST_QUARK (GERROR), G_TYPE_ERROR, gerror,
1576 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
1580 * gst_message_parse_segment_start:
1581 * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_START.
1582 * @format: (out) (allow-none): Result location for the format, or %NULL
1583 * @position: (out) (allow-none): Result location for the position, or %NULL
1585 * Extracts the position and format from the segment start message.
1590 gst_message_parse_segment_start (GstMessage * message, GstFormat * format,
1593 GstStructure *structure;
1595 g_return_if_fail (GST_IS_MESSAGE (message));
1596 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_START);
1598 structure = GST_MESSAGE_STRUCTURE (message);
1600 *format = (GstFormat)
1601 g_value_get_enum (gst_structure_id_get_value (structure,
1602 GST_QUARK (FORMAT)));
1605 g_value_get_int64 (gst_structure_id_get_value (structure,
1606 GST_QUARK (POSITION)));
1610 * gst_message_parse_segment_done:
1611 * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE.
1612 * @format: (out) (allow-none): Result location for the format, or %NULL
1613 * @position: (out) (allow-none): Result location for the position, or %NULL
1615 * Extracts the position and format from the segment done message.
1620 gst_message_parse_segment_done (GstMessage * message, GstFormat * format,
1623 GstStructure *structure;
1625 g_return_if_fail (GST_IS_MESSAGE (message));
1626 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_DONE);
1628 structure = GST_MESSAGE_STRUCTURE (message);
1630 *format = (GstFormat)
1631 g_value_get_enum (gst_structure_id_get_value (structure,
1632 GST_QUARK (FORMAT)));
1635 g_value_get_int64 (gst_structure_id_get_value (structure,
1636 GST_QUARK (POSITION)));
1640 * gst_message_parse_async_done:
1641 * @message: A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE.
1642 * @running_time: (out) (allow-none): Result location for the running_time or %NULL
1644 * Extract the running_time from the async_done message.
1649 gst_message_parse_async_done (GstMessage * message, GstClockTime * running_time)
1651 GstStructure *structure;
1653 g_return_if_fail (GST_IS_MESSAGE (message));
1654 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ASYNC_DONE);
1656 structure = GST_MESSAGE_STRUCTURE (message);
1659 g_value_get_uint64 (gst_structure_id_get_value (structure,
1660 GST_QUARK (RUNNING_TIME)));
1664 * gst_message_parse_request_state:
1665 * @message: A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE.
1666 * @state: (out) (allow-none): Result location for the requested state or %NULL
1668 * Extract the requested state from the request_state message.
1673 gst_message_parse_request_state (GstMessage * message, GstState * state)
1675 GstStructure *structure;
1677 g_return_if_fail (GST_IS_MESSAGE (message));
1678 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_REQUEST_STATE);
1680 structure = GST_MESSAGE_STRUCTURE (message);
1683 g_value_get_enum (gst_structure_id_get_value (structure,
1684 GST_QUARK (NEW_STATE)));
1688 * gst_message_new_stream_status:
1689 * @src: The object originating the message.
1690 * @type: The stream status type.
1691 * @owner: (transfer none): the owner element of @src.
1693 * Create a new stream status message. This message is posted when a streaming
1694 * thread is created/destroyed or when the state changed.
1696 * Returns: (transfer full): the new stream status message.
1701 gst_message_new_stream_status (GstObject * src, GstStreamStatusType type,
1704 GstMessage *message;
1705 GstStructure *structure;
1707 structure = gst_structure_new_id (GST_QUARK (MESSAGE_STREAM_STATUS),
1708 GST_QUARK (TYPE), GST_TYPE_STREAM_STATUS_TYPE, (gint) type,
1709 GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner, NULL);
1710 message = gst_message_new_custom (GST_MESSAGE_STREAM_STATUS, src, structure);
1716 * gst_message_parse_stream_status:
1717 * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1718 * @type: (out): A pointer to hold the status type
1719 * @owner: (out) (transfer none): The owner element of the message source
1721 * Extracts the stream status type and owner the GstMessage. The returned
1722 * owner remains valid for as long as the reference to @message is valid and
1723 * should thus not be unreffed.
1728 gst_message_parse_stream_status (GstMessage * message,
1729 GstStreamStatusType * type, GstElement ** owner)
1731 const GValue *owner_gvalue;
1732 GstStructure *structure;
1734 g_return_if_fail (GST_IS_MESSAGE (message));
1735 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1737 structure = GST_MESSAGE_STRUCTURE (message);
1738 owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1739 g_return_if_fail (owner_gvalue != NULL);
1742 *type = (GstStreamStatusType)
1743 g_value_get_enum (gst_structure_id_get_value (structure,
1746 *owner = (GstElement *) g_value_get_object (owner_gvalue);
1750 * gst_message_set_stream_status_object:
1751 * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1752 * @object: the object controlling the streaming
1754 * Configures the object handling the streaming thread. This is usually a
1755 * GstTask object but other objects might be added in the future.
1758 gst_message_set_stream_status_object (GstMessage * message,
1759 const GValue * object)
1761 GstStructure *structure;
1763 g_return_if_fail (GST_IS_MESSAGE (message));
1764 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1766 structure = GST_MESSAGE_STRUCTURE (message);
1767 gst_structure_id_set_value (structure, GST_QUARK (OBJECT), object);
1771 * gst_message_get_stream_status_object:
1772 * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1774 * Extracts the object managing the streaming thread from @message.
1776 * Returns: a GValue containing the object that manages the streaming thread.
1777 * This object is usually of type GstTask but other types can be added in the
1778 * future. The object remains valid as long as @message is valid.
1781 gst_message_get_stream_status_object (GstMessage * message)
1783 const GValue *result;
1784 GstStructure *structure;
1786 g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
1787 g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS,
1790 structure = GST_MESSAGE_STRUCTURE (message);
1791 result = gst_structure_id_get_value (structure, GST_QUARK (OBJECT));
1797 * gst_message_new_step_done:
1798 * @src: The object originating the message.
1799 * @format: the format of @amount
1800 * @amount: the amount of stepped data
1801 * @rate: the rate of the stepped amount
1802 * @flush: is this an flushing step
1803 * @intermediate: is this an intermediate step
1804 * @duration: the duration of the data
1805 * @eos: the step caused EOS
1807 * This message is posted by elements when they complete a part, when @intermediate set
1808 * to %TRUE, or a complete step operation.
1810 * @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped
1811 * @amount of media in format @format.
1813 * Returns: (transfer full): the new step_done message.
1818 gst_message_new_step_done (GstObject * src, GstFormat format, guint64 amount,
1819 gdouble rate, gboolean flush, gboolean intermediate, guint64 duration,
1822 GstMessage *message;
1823 GstStructure *structure;
1825 structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_DONE),
1826 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1827 GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1828 GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1829 GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1830 GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1831 GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1832 GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1833 message = gst_message_new_custom (GST_MESSAGE_STEP_DONE, src, structure);
1839 * gst_message_parse_step_done:
1840 * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1841 * @format: (out) (allow-none): result location for the format
1842 * @amount: (out) (allow-none): result location for the amount
1843 * @rate: (out) (allow-none): result location for the rate
1844 * @flush: (out) (allow-none): result location for the flush flag
1845 * @intermediate: (out) (allow-none): result location for the intermediate flag
1846 * @duration: (out) (allow-none): result location for the duration
1847 * @eos: (out) (allow-none): result location for the EOS flag
1849 * Extract the values the step_done message.
1854 gst_message_parse_step_done (GstMessage * message, GstFormat * format,
1855 guint64 * amount, gdouble * rate, gboolean * flush, gboolean * intermediate,
1856 guint64 * duration, gboolean * eos)
1858 GstStructure *structure;
1860 g_return_if_fail (GST_IS_MESSAGE (message));
1861 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_DONE);
1863 structure = GST_MESSAGE_STRUCTURE (message);
1864 gst_structure_id_get (structure,
1865 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1866 GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1867 GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1868 GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1869 GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1870 GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1871 GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1875 * gst_message_new_step_start:
1876 * @src: The object originating the message.
1877 * @active: if the step is active or queued
1878 * @format: the format of @amount
1879 * @amount: the amount of stepped data
1880 * @rate: the rate of the stepped amount
1881 * @flush: is this an flushing step
1882 * @intermediate: is this an intermediate step
1884 * This message is posted by elements when they accept or activate a new step
1885 * event for @amount in @format.
1887 * @active is set to %FALSE when the element accepted the new step event and has
1888 * queued it for execution in the streaming threads.
1890 * @active is set to %TRUE when the element has activated the step operation and
1891 * is now ready to start executing the step in the streaming thread. After this
1892 * message is emitted, the application can queue a new step operation in the
1895 * Returns: (transfer full): The new step_start message.
1900 gst_message_new_step_start (GstObject * src, gboolean active, GstFormat format,
1901 guint64 amount, gdouble rate, gboolean flush, gboolean intermediate)
1903 GstMessage *message;
1904 GstStructure *structure;
1906 structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_START),
1907 GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1908 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1909 GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1910 GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1911 GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1912 GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1913 message = gst_message_new_custom (GST_MESSAGE_STEP_START, src, structure);
1919 * gst_message_parse_step_start:
1920 * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1921 * @active: (out) (allow-none): result location for the active flag
1922 * @format: (out) (allow-none): result location for the format
1923 * @amount: (out) (allow-none): result location for the amount
1924 * @rate: (out) (allow-none): result location for the rate
1925 * @flush: (out) (allow-none): result location for the flush flag
1926 * @intermediate: (out) (allow-none): result location for the intermediate flag
1928 * Extract the values from step_start message.
1933 gst_message_parse_step_start (GstMessage * message, gboolean * active,
1934 GstFormat * format, guint64 * amount, gdouble * rate, gboolean * flush,
1935 gboolean * intermediate)
1937 GstStructure *structure;
1939 g_return_if_fail (GST_IS_MESSAGE (message));
1940 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_START);
1942 structure = GST_MESSAGE_STRUCTURE (message);
1943 gst_structure_id_get (structure,
1944 GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1945 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1946 GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1947 GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1948 GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1949 GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1953 * gst_message_new_qos:
1954 * @src: The object originating the message.
1955 * @live: if the message was generated by a live element
1956 * @running_time: the running time of the buffer that generated the message
1957 * @stream_time: the stream time of the buffer that generated the message
1958 * @timestamp: the timestamps of the buffer that generated the message
1959 * @duration: the duration of the buffer that generated the message
1961 * A QOS message is posted on the bus whenever an element decides to drop a
1962 * buffer because of QoS reasons or whenever it changes its processing strategy
1963 * because of QoS reasons (quality adjustments such as processing at lower
1966 * This message can be posted by an element that performs synchronisation against the
1967 * clock (live) or it could be dropped by an element that performs QoS because of QOS
1968 * events received from a downstream element (!live).
1970 * @running_time, @stream_time, @timestamp, @duration should be set to the
1971 * respective running-time, stream-time, timestamp and duration of the (dropped)
1972 * buffer that generated the QoS event. Values can be left to
1973 * GST_CLOCK_TIME_NONE when unknown.
1975 * Returns: (transfer full): The new qos message.
1980 gst_message_new_qos (GstObject * src, gboolean live, guint64 running_time,
1981 guint64 stream_time, guint64 timestamp, guint64 duration)
1983 GstMessage *message;
1984 GstStructure *structure;
1986 structure = gst_structure_new_id (GST_QUARK (MESSAGE_QOS),
1987 GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
1988 GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
1989 GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
1990 GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
1991 GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1992 GST_QUARK (JITTER), G_TYPE_INT64, (gint64) 0,
1993 GST_QUARK (PROPORTION), G_TYPE_DOUBLE, (gdouble) 1.0,
1994 GST_QUARK (QUALITY), G_TYPE_INT, (gint) 1000000,
1995 GST_QUARK (FORMAT), GST_TYPE_FORMAT, GST_FORMAT_UNDEFINED,
1996 GST_QUARK (PROCESSED), G_TYPE_UINT64, (guint64) - 1,
1997 GST_QUARK (DROPPED), G_TYPE_UINT64, (guint64) - 1, NULL);
1998 message = gst_message_new_custom (GST_MESSAGE_QOS, src, structure);
2004 * gst_message_set_qos_values:
2005 * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2006 * @jitter: The difference of the running-time against the deadline.
2007 * @proportion: Long term prediction of the ideal rate relative to normal rate
2008 * to get optimal quality.
2009 * @quality: An element dependent integer value that specifies the current
2010 * quality level of the element. The default maximum quality is 1000000.
2012 * Set the QoS values that have been calculated/analysed from the QoS data
2017 gst_message_set_qos_values (GstMessage * message, gint64 jitter,
2018 gdouble proportion, gint quality)
2020 GstStructure *structure;
2022 g_return_if_fail (GST_IS_MESSAGE (message));
2023 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2025 structure = GST_MESSAGE_STRUCTURE (message);
2026 gst_structure_id_set (structure,
2027 GST_QUARK (JITTER), G_TYPE_INT64, jitter,
2028 GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
2029 GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
2033 * gst_message_set_qos_stats:
2034 * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2035 * @format: Units of the 'processed' and 'dropped' fields. Video sinks and video
2036 * filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters
2037 * will likely use GST_FORMAT_DEFAULT (samples).
2038 * @processed: Total number of units correctly processed since the last state
2039 * change to READY or a flushing operation.
2040 * @dropped: Total number of units dropped since the last state change to READY
2041 * or a flushing operation.
2043 * Set the QoS stats representing the history of the current continuous pipeline
2046 * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
2047 * invalid. Values of -1 for either @processed or @dropped mean unknown values.
2052 gst_message_set_qos_stats (GstMessage * message, GstFormat format,
2053 guint64 processed, guint64 dropped)
2055 GstStructure *structure;
2057 g_return_if_fail (GST_IS_MESSAGE (message));
2058 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2060 structure = GST_MESSAGE_STRUCTURE (message);
2061 gst_structure_id_set (structure,
2062 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
2063 GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
2064 GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
2068 * gst_message_parse_qos:
2069 * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2070 * @live: (out) (allow-none): if the message was generated by a live element
2071 * @running_time: (out) (allow-none): the running time of the buffer that
2072 * generated the message
2073 * @stream_time: (out) (allow-none): the stream time of the buffer that
2074 * generated the message
2075 * @timestamp: (out) (allow-none): the timestamps of the buffer that
2076 * generated the message
2077 * @duration: (out) (allow-none): the duration of the buffer that
2078 * generated the message
2080 * Extract the timestamps and live status from the QoS message.
2082 * The returned values give the running_time, stream_time, timestamp and
2083 * duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown
2089 gst_message_parse_qos (GstMessage * message, gboolean * live,
2090 guint64 * running_time, guint64 * stream_time, guint64 * timestamp,
2093 GstStructure *structure;
2095 g_return_if_fail (GST_IS_MESSAGE (message));
2096 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2098 structure = GST_MESSAGE_STRUCTURE (message);
2099 gst_structure_id_get (structure,
2100 GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
2101 GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
2102 GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
2103 GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
2104 GST_QUARK (DURATION), G_TYPE_UINT64, duration, NULL);
2108 * gst_message_parse_qos_values:
2109 * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2110 * @jitter: (out) (allow-none): The difference of the running-time against
2112 * @proportion: (out) (allow-none): Long term prediction of the ideal rate
2113 * relative to normal rate to get optimal quality.
2114 * @quality: (out) (allow-none): An element dependent integer value that
2115 * specifies the current quality level of the element. The default
2116 * maximum quality is 1000000.
2118 * Extract the QoS values that have been calculated/analysed from the QoS data
2123 gst_message_parse_qos_values (GstMessage * message, gint64 * jitter,
2124 gdouble * proportion, gint * quality)
2126 GstStructure *structure;
2128 g_return_if_fail (GST_IS_MESSAGE (message));
2129 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2131 structure = GST_MESSAGE_STRUCTURE (message);
2132 gst_structure_id_get (structure,
2133 GST_QUARK (JITTER), G_TYPE_INT64, jitter,
2134 GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
2135 GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
2139 * gst_message_parse_qos_stats:
2140 * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2141 * @format: (out) (allow-none): Units of the 'processed' and 'dropped' fields.
2142 * Video sinks and video filters will use GST_FORMAT_BUFFERS (frames).
2143 * Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT
2145 * @processed: (out) (allow-none): Total number of units correctly processed
2146 * since the last state change to READY or a flushing operation.
2147 * @dropped: (out) (allow-none): Total number of units dropped since the last
2148 * state change to READY or a flushing operation.
2150 * Extract the QoS stats representing the history of the current continuous
2151 * pipeline playback period.
2153 * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
2154 * invalid. Values of -1 for either @processed or @dropped mean unknown values.
2159 gst_message_parse_qos_stats (GstMessage * message, GstFormat * format,
2160 guint64 * processed, guint64 * dropped)
2162 GstStructure *structure;
2164 g_return_if_fail (GST_IS_MESSAGE (message));
2165 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2167 structure = GST_MESSAGE_STRUCTURE (message);
2168 gst_structure_id_get (structure,
2169 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
2170 GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
2171 GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
2175 * gst_message_new_progress:
2176 * @src: The object originating the message.
2177 * @type: a #GstProgressType
2178 * @code: a progress code
2179 * @text: free, user visible text describing the progress
2181 * Progress messages are posted by elements when they use an asynchronous task
2182 * to perform actions triggered by a state change.
2184 * @code contains a well defined string describing the action.
2185 * @test should contain a user visible string detailing the current action.
2187 * Returns: (transfer full): The new qos message.
2190 gst_message_new_progress (GstObject * src, GstProgressType type,
2191 const gchar * code, const gchar * text)
2193 GstMessage *message;
2194 GstStructure *structure;
2195 gint percent = 100, timeout = -1;
2197 g_return_val_if_fail (code != NULL, NULL);
2198 g_return_val_if_fail (text != NULL, NULL);
2200 if (type == GST_PROGRESS_TYPE_START || type == GST_PROGRESS_TYPE_CONTINUE)
2203 structure = gst_structure_new_id (GST_QUARK (MESSAGE_PROGRESS),
2204 GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2205 GST_QUARK (CODE), G_TYPE_STRING, code,
2206 GST_QUARK (TEXT), G_TYPE_STRING, text,
2207 GST_QUARK (PERCENT), G_TYPE_INT, percent,
2208 GST_QUARK (TIMEOUT), G_TYPE_INT, timeout, NULL);
2209 message = gst_message_new_custom (GST_MESSAGE_PROGRESS, src, structure);
2215 * gst_message_parse_progress:
2216 * @message: A valid #GstMessage of type GST_MESSAGE_PROGRESS.
2217 * @type: (out) (allow-none): location for the type
2218 * @code: (out) (allow-none) (transfer full): location for the code
2219 * @text: (out) (allow-none) (transfer full): location for the text
2221 * Parses the progress @type, @code and @text.
2224 gst_message_parse_progress (GstMessage * message, GstProgressType * type,
2225 gchar ** code, gchar ** text)
2227 GstStructure *structure;
2229 g_return_if_fail (GST_IS_MESSAGE (message));
2230 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_PROGRESS);
2232 structure = GST_MESSAGE_STRUCTURE (message);
2233 gst_structure_id_get (structure,
2234 GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2235 GST_QUARK (CODE), G_TYPE_STRING, code,
2236 GST_QUARK (TEXT), G_TYPE_STRING, text, NULL);
2240 * gst_message_new_toc:
2241 * @src: the object originating the message.
2242 * @toc: (transfer none): #GstToc structure for the message.
2243 * @updated: whether TOC was updated or not.
2245 * Create a new TOC message. The message is posted by elements
2246 * that discovered or updated a TOC.
2248 * Returns: (transfer full): a new TOC message.
2253 gst_message_new_toc (GstObject * src, GstToc * toc, gboolean updated)
2255 GstStructure *toc_struct;
2257 g_return_val_if_fail (toc != NULL, NULL);
2259 toc_struct = gst_structure_new_id (GST_QUARK (MESSAGE_TOC),
2260 GST_QUARK (TOC), GST_TYPE_TOC, toc,
2261 GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
2263 return gst_message_new_custom (GST_MESSAGE_TOC, src, toc_struct);
2267 * gst_message_parse_toc:
2268 * @message: a valid #GstMessage of type GST_MESSAGE_TOC.
2269 * @toc: (out) (transfer full): return location for the TOC.
2270 * @updated: (out): return location for the updated flag.
2272 * Extract the TOC from the #GstMessage. The TOC returned in the
2273 * output argument is a copy; the caller must free it with
2274 * gst_toc_unref() when done.
2279 gst_message_parse_toc (GstMessage * message, GstToc ** toc, gboolean * updated)
2281 g_return_if_fail (GST_IS_MESSAGE (message));
2282 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TOC);
2283 g_return_if_fail (toc != NULL);
2285 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2286 GST_QUARK (TOC), GST_TYPE_TOC, toc,
2287 GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
2291 * gst_message_new_reset_time:
2292 * @src: (transfer none) (allow-none): The object originating the message.
2293 * @running_time: the requested running-time
2295 * This message is posted when the pipeline running-time should be reset to
2296 * @running_time, like after a flushing seek.
2298 * Returns: (transfer full): The new reset_time message.
2303 gst_message_new_reset_time (GstObject * src, GstClockTime running_time)
2305 GstMessage *message;
2306 GstStructure *structure;
2308 structure = gst_structure_new_id (GST_QUARK (MESSAGE_RESET_TIME),
2309 GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
2310 message = gst_message_new_custom (GST_MESSAGE_RESET_TIME, src, structure);
2316 * gst_message_parse_reset_time:
2317 * @message: A valid #GstMessage of type GST_MESSAGE_RESET_TIME.
2318 * @running_time: (out) (allow-none): Result location for the running_time or
2321 * Extract the running-time from the RESET_TIME message.
2326 gst_message_parse_reset_time (GstMessage * message, GstClockTime * running_time)
2328 GstStructure *structure;
2330 g_return_if_fail (GST_IS_MESSAGE (message));
2331 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_RESET_TIME);
2333 structure = GST_MESSAGE_STRUCTURE (message);
2336 g_value_get_uint64 (gst_structure_id_get_value (structure,
2337 GST_QUARK (RUNNING_TIME)));
2341 * gst_message_new_stream_start:
2342 * @src: (transfer none) (allow-none): The object originating the message.
2344 * Create a new stream_start message. This message is generated and posted in
2345 * the sink elements of a GstBin. The bin will only forward the STREAM_START
2346 * message to the application if all sinks have posted an STREAM_START message.
2348 * Returns: (transfer full): The new stream_start message.
2353 gst_message_new_stream_start (GstObject * src)
2355 GstMessage *message;
2358 s = gst_structure_new_id_empty (GST_QUARK (MESSAGE_STREAM_START));
2359 message = gst_message_new_custom (GST_MESSAGE_STREAM_START, src, s);
2366 * gst_message_set_group_id:
2367 * @message: the message
2368 * @group_id: the group id
2370 * Sets the group id on the stream-start message.
2372 * All streams that have the same group id are supposed to be played
2373 * together, i.e. all streams inside a container file should have the
2374 * same group id but different stream ids. The group id should change
2375 * each time the stream is started, resulting in different group ids
2376 * each time a file is played for example.
2383 gst_message_set_group_id (GstMessage * message, guint group_id)
2385 GstStructure *structure;
2387 g_return_if_fail (GST_IS_MESSAGE (message));
2388 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_START);
2389 g_return_if_fail (gst_message_is_writable (message));
2391 structure = GST_MESSAGE_STRUCTURE (message);
2392 gst_structure_id_set (structure, GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id,
2397 * gst_message_parse_group_id:
2398 * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_START.
2399 * @group_id: (out) (allow-none): Result location for the group id or
2402 * Extract the group from the STREAM_START message.
2404 * Returns: %TRUE if the message had a group id set, %FALSE otherwise
2411 gst_message_parse_group_id (GstMessage * message, guint * group_id)
2413 GstStructure *structure;
2416 g_return_val_if_fail (GST_IS_MESSAGE (message), FALSE);
2417 g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_START,
2423 structure = GST_MESSAGE_STRUCTURE (message);
2425 v = gst_structure_id_get_value (structure, GST_QUARK (GROUP_ID));
2429 *group_id = g_value_get_uint (v);
2434 * gst_message_new_need_context:
2435 * @src: (transfer none) (allow-none): The object originating the message.
2436 * @context_type: The context type that is needed
2438 * This message is posted when an element needs a specific #GstContext.
2440 * Returns: (transfer full): The new need-context message.
2447 gst_message_new_need_context (GstObject * src, const gchar * context_type)
2449 GstMessage *message;
2450 GstStructure *structure;
2452 g_return_val_if_fail (context_type != NULL, NULL);
2454 structure = gst_structure_new_id (GST_QUARK (MESSAGE_NEED_CONTEXT),
2455 GST_QUARK (CONTEXT_TYPE), G_TYPE_STRING, context_type, NULL);
2456 message = gst_message_new_custom (GST_MESSAGE_NEED_CONTEXT, src, structure);
2462 * gst_message_parse_context_type:
2463 * @message: a GST_MESSAGE_NEED_CONTEXT type message
2464 * @context_type: (out) (allow-none): the context type, or %NULL
2466 * Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message.
2468 * Returns: a #gboolean indicating if the parsing succeeded.
2473 gst_message_parse_context_type (GstMessage * message,
2474 const gchar ** context_type)
2476 GstStructure *structure;
2477 const GValue *value;
2479 g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_NEED_CONTEXT,
2482 structure = GST_MESSAGE_STRUCTURE (message);
2485 value = gst_structure_id_get_value (structure, GST_QUARK (CONTEXT_TYPE));
2486 *context_type = g_value_get_string (value);
2493 * gst_message_new_have_context:
2494 * @src: (transfer none) (allow-none): The object originating the message.
2495 * @context: (transfer full): the context
2497 * This message is posted when an element has a new local #GstContext.
2499 * Returns: (transfer full): The new have-context message.
2506 gst_message_new_have_context (GstObject * src, GstContext * context)
2508 GstMessage *message;
2509 GstStructure *structure;
2511 structure = gst_structure_new_id (GST_QUARK (MESSAGE_HAVE_CONTEXT),
2512 GST_QUARK (CONTEXT), GST_TYPE_CONTEXT, context, NULL);
2513 message = gst_message_new_custom (GST_MESSAGE_HAVE_CONTEXT, src, structure);
2514 gst_context_unref (context);
2520 * gst_message_parse_have_context:
2521 * @message: A valid #GstMessage of type GST_MESSAGE_HAVE_CONTEXT.
2522 * @context: (out) (transfer full) (allow-none): Result location for the
2525 * Extract the context from the HAVE_CONTEXT message.
2532 gst_message_parse_have_context (GstMessage * message, GstContext ** context)
2534 g_return_if_fail (GST_IS_MESSAGE (message));
2535 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_HAVE_CONTEXT);
2538 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2539 GST_QUARK (CONTEXT), GST_TYPE_CONTEXT, context, NULL);
2543 * gst_message_new_device_added:
2544 * @src: The #GstObject that created the message
2545 * @device: (transfer none): The new #GstDevice
2547 * Creates a new device-added message. The device-added message is produced by
2548 * #GstDeviceProvider or a #GstDeviceMonitor. They announce the appearance
2549 * of monitored devices.
2551 * Returns: a newly allocated #GstMessage
2556 gst_message_new_device_added (GstObject * src, GstDevice * device)
2558 GstMessage *message;
2559 GstStructure *structure;
2561 g_return_val_if_fail (device != NULL, NULL);
2562 g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
2564 structure = gst_structure_new_id (GST_QUARK (MESSAGE_DEVICE_ADDED),
2565 GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2566 message = gst_message_new_custom (GST_MESSAGE_DEVICE_ADDED, src, structure);
2572 * gst_message_parse_device_added:
2573 * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED
2574 * @device: (out) (allow-none) (transfer full): A location where to store a
2575 * pointer to the new #GstDevice, or %NULL
2577 * Parses a device-added message. The device-added message is produced by
2578 * #GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance
2579 * of monitored devices.
2584 gst_message_parse_device_added (GstMessage * message, GstDevice ** device)
2586 g_return_if_fail (GST_IS_MESSAGE (message));
2587 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_DEVICE_ADDED);
2590 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2591 GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2595 * gst_message_new_device_removed:
2596 * @src: The #GstObject that created the message
2597 * @device: (transfer none): The removed #GstDevice
2599 * Creates a new device-removed message. The device-removed message is produced
2600 * by #GstDeviceProvider or a #GstDeviceMonitor. They announce the
2601 * disappearance of monitored devices.
2603 * Returns: a newly allocated #GstMessage
2608 gst_message_new_device_removed (GstObject * src, GstDevice * device)
2610 GstMessage *message;
2611 GstStructure *structure;
2613 g_return_val_if_fail (device != NULL, NULL);
2614 g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
2616 structure = gst_structure_new_id (GST_QUARK (MESSAGE_DEVICE_REMOVED),
2617 GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2618 message = gst_message_new_custom (GST_MESSAGE_DEVICE_REMOVED, src, structure);
2624 * gst_message_parse_device_removed:
2625 * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED
2626 * @device: (out) (allow-none) (transfer full): A location where to store a
2627 * pointer to the removed #GstDevice, or %NULL
2629 * Parses a device-removed message. The device-removed message is produced by
2630 * #GstDeviceProvider or a #GstDeviceMonitor. It announces the
2631 * disappearance of monitored devices.
2636 gst_message_parse_device_removed (GstMessage * message, GstDevice ** device)
2638 g_return_if_fail (GST_IS_MESSAGE (message));
2639 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_DEVICE_REMOVED);
2642 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2643 GST_QUARK (DEVICE), GST_TYPE_DEVICE, device, NULL);
2647 * gst_message_new_property_notify:
2648 * @src: The #GstObject whose property changed (may or may not be a #GstElement)
2649 * @property_name: name of the property that changed
2650 * @val: (allow-none) (transfer full): new property value, or %NULL
2652 * Returns: a newly allocated #GstMessage
2657 gst_message_new_property_notify (GstObject * src, const gchar * property_name,
2660 GstStructure *structure;
2661 GValue name_val = G_VALUE_INIT;
2663 g_return_val_if_fail (property_name != NULL, NULL);
2665 structure = gst_structure_new_id_empty (GST_QUARK (MESSAGE_PROPERTY_NOTIFY));
2666 g_value_init (&name_val, G_TYPE_STRING);
2667 /* should already be interned, but let's make sure */
2668 g_value_set_static_string (&name_val, g_intern_string (property_name));
2669 gst_structure_id_take_value (structure, GST_QUARK (PROPERTY_NAME), &name_val);
2671 gst_structure_id_take_value (structure, GST_QUARK (PROPERTY_VALUE), val);
2673 return gst_message_new_custom (GST_MESSAGE_PROPERTY_NOTIFY, src, structure);
2677 * gst_message_parse_property_notify:
2678 * @message: a #GstMessage of type %GST_MESSAGE_PROPERTY_NOTIFY
2679 * @object: (out) (allow-none) (transfer none): location where to store a
2680 * pointer to the object whose property got changed, or %NULL
2681 * @property_name: (out) (allow-none): return location for the name of the
2682 * property that got changed, or %NULL
2683 * @property_value: (out) (allow-none): return location for the new value of
2684 * the property that got changed, or %NULL. This will only be set if the
2685 * property notify watch was told to include the value when it was set up
2687 * Parses a property-notify message. These will be posted on the bus only
2688 * when set up with gst_element_add_property_notify_watch() or
2689 * gst_element_add_property_deep_notify_watch().
2694 gst_message_parse_property_notify (GstMessage * message, GstObject ** object,
2695 const gchar ** property_name, const GValue ** property_value)
2697 const GstStructure *s = GST_MESSAGE_STRUCTURE (message);
2699 g_return_if_fail (GST_IS_MESSAGE (message));
2700 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_PROPERTY_NOTIFY);
2703 *object = GST_MESSAGE_SRC (message);
2705 if (property_name) {
2706 const GValue *name_value;
2708 name_value = gst_structure_id_get_value (s, GST_QUARK (PROPERTY_NAME));
2709 *property_name = g_value_get_string (name_value);
2714 gst_structure_id_get_value (s, GST_QUARK (PROPERTY_VALUE));
2718 * gst_message_new_stream_collection:
2719 * @src: The #GstObject that created the message
2720 * @collection: (transfer none): The #GstStreamCollection
2722 * Creates a new stream-collection message. The message is used to announce new
2723 * #GstStreamCollection
2725 * Returns: a newly allocated #GstMessage
2730 gst_message_new_stream_collection (GstObject * src,
2731 GstStreamCollection * collection)
2733 GstMessage *message;
2734 GstStructure *structure;
2736 g_return_val_if_fail (collection != NULL, NULL);
2737 g_return_val_if_fail (GST_IS_STREAM_COLLECTION (collection), NULL);
2740 gst_structure_new_id (GST_QUARK (MESSAGE_STREAM_COLLECTION),
2741 GST_QUARK (COLLECTION), GST_TYPE_STREAM_COLLECTION, collection, NULL);
2743 gst_message_new_custom (GST_MESSAGE_STREAM_COLLECTION, src, structure);
2749 * gst_message_parse_stream_collection:
2750 * @message: a #GstMessage of type %GST_MESSAGE_STREAM_COLLECTION
2751 * @collection: (out) (allow-none) (transfer full): A location where to store a
2752 * pointer to the #GstStreamCollection, or %NULL
2754 * Parses a stream-collection message.
2759 gst_message_parse_stream_collection (GstMessage * message,
2760 GstStreamCollection ** collection)
2762 g_return_if_fail (GST_IS_MESSAGE (message));
2763 g_return_if_fail (GST_MESSAGE_TYPE (message) ==
2764 GST_MESSAGE_STREAM_COLLECTION);
2767 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2768 GST_QUARK (COLLECTION), GST_TYPE_STREAM_COLLECTION, collection, NULL);
2772 * gst_message_new_streams_selected:
2773 * @src: The #GstObject that created the message
2774 * @collection: (transfer none): The #GstStreamCollection
2776 * Creates a new steams-selected message. The message is used to announce
2777 * that an array of streams has been selected. This is generally in response
2778 * to a #GST_EVENT_SELECT_STREAMS event, or when an element (such as decodebin3)
2779 * makes an initial selection of streams.
2781 * The message also contains the #GstStreamCollection to which the various streams
2784 * Users of gst_message_new_streams_selected() can add the selected streams with
2785 * gst_message_streams_selected_add().
2787 * Returns: a newly allocated #GstMessage
2792 gst_message_new_streams_selected (GstObject * src,
2793 GstStreamCollection * collection)
2795 GstMessage *message;
2796 GstStructure *structure;
2797 GValue val = G_VALUE_INIT;
2799 g_return_val_if_fail (collection != NULL, NULL);
2800 g_return_val_if_fail (GST_IS_STREAM_COLLECTION (collection), NULL);
2803 gst_structure_new_id (GST_QUARK (MESSAGE_STREAMS_SELECTED),
2804 GST_QUARK (COLLECTION), GST_TYPE_STREAM_COLLECTION, collection, NULL);
2805 g_value_init (&val, GST_TYPE_ARRAY);
2806 gst_structure_id_take_value (structure, GST_QUARK (STREAMS), &val);
2808 gst_message_new_custom (GST_MESSAGE_STREAMS_SELECTED, src, structure);
2814 * gst_message_streams_selected_get_size:
2815 * @message: a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED
2817 * Returns the number of streams contained in the @message.
2819 * Returns: The number of streams contained within.
2824 gst_message_streams_selected_get_size (GstMessage * msg)
2828 g_return_val_if_fail (GST_IS_MESSAGE (msg), 0);
2829 g_return_val_if_fail (GST_MESSAGE_TYPE (msg) == GST_MESSAGE_STREAMS_SELECTED,
2833 gst_structure_id_get_value (GST_MESSAGE_STRUCTURE (msg),
2834 GST_QUARK (STREAMS));
2835 return gst_value_array_get_size (val);
2839 * gst_message_streams_selected_add:
2840 * @message: a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED
2841 * @stream: (transfer none): a #GstStream to add to @message
2843 * Adds the @stream to the @message.
2848 gst_message_streams_selected_add (GstMessage * msg, GstStream * stream)
2851 GValue to_add = G_VALUE_INIT;
2853 g_return_if_fail (GST_IS_MESSAGE (msg));
2854 g_return_if_fail (GST_MESSAGE_TYPE (msg) == GST_MESSAGE_STREAMS_SELECTED);
2855 g_return_if_fail (GST_IS_STREAM (stream));
2858 (GValue *) gst_structure_id_get_value (GST_MESSAGE_STRUCTURE (msg),
2859 GST_QUARK (STREAMS));
2860 g_value_init (&to_add, GST_TYPE_STREAM);
2861 g_value_set_object (&to_add, stream);
2862 gst_value_array_append_and_take_value (val, &to_add);
2866 * gst_message_streams_selected_get_stream:
2867 * @message: a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED
2868 * @idx: Index of the stream to retrieve
2870 * Retrieves the #GstStream with index @index from the @message.
2872 * Returns: (transfer full): A #GstStream
2877 gst_message_streams_selected_get_stream (GstMessage * msg, guint idx)
2879 const GValue *streams, *val;
2881 g_return_val_if_fail (GST_IS_MESSAGE (msg), NULL);
2882 g_return_val_if_fail (GST_MESSAGE_TYPE (msg) == GST_MESSAGE_STREAMS_SELECTED,
2886 gst_structure_id_get_value (GST_MESSAGE_STRUCTURE (msg),
2887 GST_QUARK (STREAMS));
2888 val = gst_value_array_get_value (streams, idx);
2890 return (GstStream *) g_value_dup_object (val);
2897 * gst_message_parse_streams_selected:
2898 * @message: a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED
2899 * @collection: (out) (allow-none) (transfer full): A location where to store a
2900 * pointer to the #GstStreamCollection, or %NULL
2902 * Parses a streams-selected message.
2907 gst_message_parse_streams_selected (GstMessage * message,
2908 GstStreamCollection ** collection)
2910 g_return_if_fail (GST_IS_MESSAGE (message));
2911 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAMS_SELECTED);
2914 gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2915 GST_QUARK (COLLECTION), GST_TYPE_STREAM_COLLECTION, collection, NULL);