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., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, 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:
39 * <title>Posting a #GstMessage</title>
41 * gst_bus_post (bus, gst_message_new_eos());
45 * A #GstElement usually posts messages on the bus provided by the parent
46 * container using gst_element_post_message().
48 * Last reviewed on 2005-11-09 (0.9.4)
52 #include "gst_private.h"
53 #include <string.h> /* memcpy */
55 #include "gstenumtypes.h"
57 #include "gstmessage.h"
58 #include "gsttaglist.h"
63 #define GST_MESSAGE_SEQNUM(e) ((GstMessage*)e)->abidata.ABI.seqnum
65 static void gst_message_finalize (GstMessage * message);
66 static GstMessage *_gst_message_copy (GstMessage * message);
68 static GstMiniObjectClass *parent_class = NULL;
71 _gst_message_initialize (void)
73 GST_CAT_INFO (GST_CAT_GST_INIT, "init messages");
75 /* the GstMiniObject types need to be class_ref'd once before it can be
76 * done from multiple threads;
77 * see http://bugzilla.gnome.org/show_bug.cgi?id=304551 */
78 g_type_class_ref (gst_message_get_type ());
88 static GstMessageQuarks message_quarks[] = {
89 {GST_MESSAGE_UNKNOWN, "unknown", 0},
90 {GST_MESSAGE_EOS, "eos", 0},
91 {GST_MESSAGE_ERROR, "error", 0},
92 {GST_MESSAGE_WARNING, "warning", 0},
93 {GST_MESSAGE_INFO, "info", 0},
94 {GST_MESSAGE_TAG, "tag", 0},
95 {GST_MESSAGE_BUFFERING, "buffering", 0},
96 {GST_MESSAGE_STATE_CHANGED, "state-changed", 0},
97 {GST_MESSAGE_STATE_DIRTY, "state-dirty", 0},
98 {GST_MESSAGE_STEP_DONE, "step-done", 0},
99 {GST_MESSAGE_CLOCK_PROVIDE, "clock-provide", 0},
100 {GST_MESSAGE_CLOCK_LOST, "clock-lost", 0},
101 {GST_MESSAGE_NEW_CLOCK, "new-clock", 0},
102 {GST_MESSAGE_STRUCTURE_CHANGE, "structure-change", 0},
103 {GST_MESSAGE_STREAM_STATUS, "stream-status", 0},
104 {GST_MESSAGE_APPLICATION, "application", 0},
105 {GST_MESSAGE_ELEMENT, "element", 0},
106 {GST_MESSAGE_SEGMENT_START, "segment-start", 0},
107 {GST_MESSAGE_SEGMENT_DONE, "segment-done", 0},
108 {GST_MESSAGE_DURATION, "duration", 0},
109 {GST_MESSAGE_LATENCY, "latency", 0},
110 {GST_MESSAGE_ASYNC_START, "async-start", 0},
111 {GST_MESSAGE_ASYNC_DONE, "async-done", 0},
112 {GST_MESSAGE_REQUEST_STATE, "request-state", 0},
117 * gst_message_type_get_name:
118 * @type: the message type
120 * Get a printable name for the given message type. Do not modify or free.
122 * Returns: a reference to the static name of the message.
125 gst_message_type_get_name (GstMessageType type)
129 for (i = 0; message_quarks[i].name; i++) {
130 if (type == message_quarks[i].type)
131 return message_quarks[i].name;
137 * gst_message_type_to_quark:
138 * @type: the message type
140 * Get the unique quark for the given message type.
142 * Returns: the quark associated with the message type
145 gst_message_type_to_quark (GstMessageType type)
149 for (i = 0; message_quarks[i].name; i++) {
150 if (type == message_quarks[i].type)
151 return message_quarks[i].quark;
160 for (i = 0; message_quarks[i].name; i++) { \
161 message_quarks[i].quark = \
162 g_quark_from_static_string (message_quarks[i].name); \
166 G_DEFINE_TYPE_WITH_CODE (GstMessage, gst_message, GST_TYPE_MINI_OBJECT,
170 gst_message_class_init (GstMessageClass * klass)
172 parent_class = g_type_class_peek_parent (klass);
174 klass->mini_object_class.copy = (GstMiniObjectCopyFunction) _gst_message_copy;
175 klass->mini_object_class.finalize =
176 (GstMiniObjectFinalizeFunction) gst_message_finalize;
180 gst_message_init (GstMessage * message)
182 GST_CAT_LOG (GST_CAT_MESSAGE, "new message %p", message);
183 GST_MESSAGE_TIMESTAMP (message) = GST_CLOCK_TIME_NONE;
187 gst_message_finalize (GstMessage * message)
189 g_return_if_fail (message != NULL);
191 GST_CAT_LOG (GST_CAT_MESSAGE, "finalize message %p", message);
193 if (GST_MESSAGE_SRC (message)) {
194 gst_object_unref (GST_MESSAGE_SRC (message));
195 GST_MESSAGE_SRC (message) = NULL;
199 GST_MESSAGE_LOCK (message);
200 GST_MESSAGE_SIGNAL (message);
201 GST_MESSAGE_UNLOCK (message);
204 if (message->structure) {
205 gst_structure_set_parent_refcount (message->structure, NULL);
206 gst_structure_free (message->structure);
209 GST_MINI_OBJECT_CLASS (parent_class)->finalize (GST_MINI_OBJECT (message));
213 _gst_message_copy (GstMessage * message)
217 GST_CAT_LOG (GST_CAT_MESSAGE, "copy message %p", message);
219 copy = (GstMessage *) gst_mini_object_new (GST_TYPE_MESSAGE);
221 /* FIXME, need to copy relevant data from the miniobject. */
222 //memcpy (copy, message, sizeof (GstMessage));
224 GST_MESSAGE_GET_LOCK (copy) = GST_MESSAGE_GET_LOCK (message);
225 GST_MESSAGE_COND (copy) = GST_MESSAGE_COND (message);
226 GST_MESSAGE_TYPE (copy) = GST_MESSAGE_TYPE (message);
227 GST_MESSAGE_TIMESTAMP (copy) = GST_MESSAGE_TIMESTAMP (message);
228 GST_MESSAGE_SEQNUM (copy) = GST_MESSAGE_SEQNUM (message);
230 if (GST_MESSAGE_SRC (message)) {
231 GST_MESSAGE_SRC (copy) = gst_object_ref (GST_MESSAGE_SRC (message));
234 if (message->structure) {
235 copy->structure = gst_structure_copy (message->structure);
236 gst_structure_set_parent_refcount (copy->structure,
237 ©->mini_object.refcount);
244 * gst_message_new_custom:
245 * @type: The #GstMessageType to distinguish messages
246 * @src: The object originating the message.
247 * @structure: The structure for the message. The message will take ownership of
250 * Create a new custom-typed message. This can be used for anything not
251 * handled by other message-specific functions to pass a message to the
252 * app. The structure field can be NULL.
254 * Returns: The new message.
259 gst_message_new_custom (GstMessageType type, GstObject * src,
260 GstStructure * structure)
264 message = (GstMessage *) gst_mini_object_new (GST_TYPE_MESSAGE);
266 GST_CAT_LOG (GST_CAT_MESSAGE, "source %s: creating new message %p %s",
267 (src ? GST_OBJECT_NAME (src) : "NULL"), message,
268 gst_message_type_get_name (type));
270 message->type = type;
273 gst_object_ref (src);
277 gst_structure_set_parent_refcount (structure,
278 &message->mini_object.refcount);
280 message->structure = structure;
282 GST_MESSAGE_SEQNUM (message) = gst_util_seqnum_next ();
288 * gst_message_get_seqnum:
289 * @message: A #GstMessage.
291 * Retrieve the sequence number of a message.
293 * Messages have ever-incrementing sequence numbers, which may also be set
294 * explicitly via gst_message_set_seqnum(). Sequence numbers are typically used
295 * to indicate that a message corresponds to some other set of messages or
296 * events, for example a SEGMENT_DONE message corresponding to a SEEK event. It
297 * is considered good practice to make this correspondence when possible, though
298 * it is not required.
300 * Note that events and messages share the same sequence number incrementor;
301 * two events or messages will never not have the same sequence number unless
302 * that correspondence was made explicitly.
304 * Returns: The message's sequence number.
311 gst_message_get_seqnum (GstMessage * message)
313 g_return_val_if_fail (GST_IS_MESSAGE (message), -1);
315 return GST_MESSAGE_SEQNUM (message);
319 * gst_message_set_seqnum:
320 * @message: A #GstMessage.
321 * @seqnum: A sequence number.
323 * Set the sequence number of a message.
325 * This function might be called by the creator of a message to indicate that
326 * the message relates to other messages or events. See gst_message_get_seqnum()
327 * for more information.
334 gst_message_set_seqnum (GstMessage * message, guint32 seqnum)
336 g_return_if_fail (GST_IS_MESSAGE (message));
338 GST_MESSAGE_SEQNUM (message) = seqnum;
342 * gst_message_new_eos:
343 * @src: The object originating the message.
345 * Create a new eos message. This message is generated and posted in
346 * the sink elements of a GstBin. The bin will only forward the EOS
347 * message to the application if all sinks have posted an EOS message.
349 * Returns: The new eos message.
354 gst_message_new_eos (GstObject * src)
358 message = gst_message_new_custom (GST_MESSAGE_EOS, src, NULL);
364 * gst_message_new_error:
365 * @src: The object originating the message.
366 * @error: The GError for this message.
367 * @debug: A debugging string.
369 * Create a new error message. The message will copy @error and
370 * @debug. This message is posted by element when a fatal event
371 * occured. The pipeline will probably (partially) stop. The application
372 * receiving this message should stop the pipeline.
374 * Returns: The new error message.
379 gst_message_new_error (GstObject * src, GError * error, const gchar * debug)
382 GstStructure *structure;
384 structure = gst_structure_empty_new ("GstMessageError");
385 gst_structure_id_set (structure,
386 GST_QUARK (GERROR), GST_TYPE_G_ERROR, error,
387 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
388 message = gst_message_new_custom (GST_MESSAGE_ERROR, src, structure);
394 * gst_message_new_warning:
395 * @src: The object originating the message.
396 * @error: The GError for this message.
397 * @debug: A debugging string.
399 * Create a new warning message. The message will make copies of @error and
402 * Returns: The new warning message.
407 gst_message_new_warning (GstObject * src, GError * error, const gchar * debug)
410 GstStructure *structure;
412 structure = gst_structure_empty_new ("GstMessageWarning");
413 gst_structure_id_set (structure,
414 GST_QUARK (GERROR), GST_TYPE_G_ERROR, error,
415 GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
416 message = gst_message_new_custom (GST_MESSAGE_WARNING, src, structure);
422 * gst_message_new_info:
423 * @src: The object originating the message.
424 * @error: The GError for this message.
425 * @debug: A debugging string.
427 * Create a new info message. The message will make copies of @error and
430 * Returns: The new info message.
437 gst_message_new_info (GstObject * src, GError * error, const gchar * debug)
440 GstStructure *structure;
442 structure = gst_structure_empty_new ("GstMessageInfo");
443 gst_structure_id_set (structure, GST_QUARK (GERROR), GST_TYPE_G_ERROR,
444 error, GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
445 message = gst_message_new_custom (GST_MESSAGE_INFO, src, structure);
451 * gst_message_new_tag:
452 * @src: The object originating the message.
453 * @tag_list: The tag list for the message.
455 * Create a new tag message. The message will take ownership of the tag list.
456 * The message is posted by elements that discovered a new taglist.
458 * Returns: The new tag message.
463 gst_message_new_tag (GstObject * src, GstTagList * tag_list)
467 g_return_val_if_fail (GST_IS_STRUCTURE (tag_list), NULL);
470 gst_message_new_custom (GST_MESSAGE_TAG, src, (GstStructure *) tag_list);
476 * gst_message_new_buffering:
477 * @src: The object originating the message.
478 * @percent: The buffering percent
480 * Create a new buffering message. This message can be posted by an element that
481 * needs to buffer data before it can continue processing. @percent should be a
482 * value between 0 and 100. A value of 100 means that the buffering completed.
484 * When @percent is < 100 the application should PAUSE a PLAYING pipeline. When
485 * @percent is 100, the application can set the pipeline (back) to PLAYING.
486 * The application must be prepared to receive BUFFERING messages in the
487 * PREROLLING state and may only set the pipeline to PLAYING after receiving a
488 * message with @percent set to 100, which can happen after the pipeline
489 * completed prerolling.
491 * Returns: The new buffering message.
498 gst_message_new_buffering (GstObject * src, gint percent)
501 GstStructure *structure;
503 g_return_val_if_fail (percent >= 0 && percent <= 100, NULL);
505 structure = gst_structure_empty_new ("GstMessageBuffering");
506 gst_structure_id_set (structure,
507 GST_QUARK (BUFFER_PERCENT), G_TYPE_INT, percent,
508 GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, GST_BUFFERING_STREAM,
509 GST_QUARK (AVG_IN_RATE), G_TYPE_INT, -1,
510 GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, -1,
511 GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, G_GINT64_CONSTANT (-1),
512 GST_QUARK (ESTIMATED_TOTAL), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
513 message = gst_message_new_custom (GST_MESSAGE_BUFFERING, src, structure);
519 * gst_message_new_state_changed:
520 * @src: the object originating the message
521 * @oldstate: the previous state
522 * @newstate: the new (current) state
523 * @pending: the pending (target) state
525 * Create a state change message. This message is posted whenever an element
528 * Returns: The new state change message.
533 gst_message_new_state_changed (GstObject * src,
534 GstState oldstate, GstState newstate, GstState pending)
537 GstStructure *structure;
539 structure = gst_structure_empty_new ("GstMessageState");
540 gst_structure_id_set (structure,
541 GST_QUARK (OLD_STATE), GST_TYPE_STATE, (gint) oldstate,
542 GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) newstate,
543 GST_QUARK (PENDING_STATE), GST_TYPE_STATE, (gint) pending, NULL);
544 message = gst_message_new_custom (GST_MESSAGE_STATE_CHANGED, src, structure);
550 * gst_message_new_state_dirty:
551 * @src: the object originating the message
553 * Create a state dirty message. This message is posted whenever an element
554 * changed its state asynchronously and is used internally to update the
555 * states of container objects.
557 * Returns: The new state dirty message.
562 gst_message_new_state_dirty (GstObject * src)
566 message = gst_message_new_custom (GST_MESSAGE_STATE_DIRTY, src, NULL);
572 * gst_message_new_clock_provide:
573 * @src: The object originating the message.
574 * @clock: The clock it provides
575 * @ready: TRUE if the sender can provide a clock
577 * Create a clock provide message. This message is posted whenever an
578 * element is ready to provide a clock or lost its ability to provide
579 * a clock (maybe because it paused or became EOS).
581 * This message is mainly used internally to manage the clock
584 * Returns: The new provide clock message.
589 gst_message_new_clock_provide (GstObject * src, GstClock * clock,
593 GstStructure *structure;
595 structure = gst_structure_empty_new ("GstMessageClockProvide");
596 gst_structure_id_set (structure,
597 GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock,
598 GST_QUARK (READY), G_TYPE_BOOLEAN, ready, NULL);
599 message = gst_message_new_custom (GST_MESSAGE_CLOCK_PROVIDE, src, structure);
605 * gst_message_new_clock_lost:
606 * @src: The object originating the message.
607 * @clock: the clock that was lost
609 * Create a clock lost message. This message is posted whenever the
610 * clock is not valid anymore.
612 * If this message is posted by the pipeline, the pipeline will
613 * select a new clock again when it goes to PLAYING. It might therefore
614 * be needed to set the pipeline to PAUSED and PLAYING again.
616 * Returns: The new clock lost message.
621 gst_message_new_clock_lost (GstObject * src, GstClock * clock)
624 GstStructure *structure;
626 structure = gst_structure_empty_new ("GstMessageClockLost");
627 gst_structure_id_set (structure,
628 GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
629 message = gst_message_new_custom (GST_MESSAGE_CLOCK_LOST, src, structure);
635 * gst_message_new_new_clock:
636 * @src: The object originating the message.
637 * @clock: the new selected clock
639 * Create a new clock message. This message is posted whenever the
640 * pipeline selectes a new clock for the pipeline.
642 * Returns: The new new clock message.
647 gst_message_new_new_clock (GstObject * src, GstClock * clock)
650 GstStructure *structure;
652 structure = gst_structure_empty_new ("GstMessageNewClock");
653 gst_structure_id_set (structure,
654 GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
655 message = gst_message_new_custom (GST_MESSAGE_NEW_CLOCK, src, structure);
661 * gst_message_new_structure_change:
662 * @src: The object originating the message.
663 * @type: The change type.
664 * @owner: The owner element of @src.
665 * @busy: Whether the structure change is busy.
667 * Create a new structure change message. This message is posted when the
668 * structure of a pipeline is in the process of being changed, for example
669 * when pads are linked or unlinked.
671 * @src should be the srcpad that unlinked or linked.
673 * Returns: The new structure change message.
680 gst_message_new_structure_change (GstObject * src, GstStructureChangeType type,
681 GstElement * owner, gboolean busy)
684 GstStructure *structure;
686 g_return_val_if_fail (GST_IS_PAD (src), NULL);
687 g_return_val_if_fail (GST_PAD_DIRECTION (src) == GST_PAD_SRC, NULL);
688 g_return_val_if_fail (GST_IS_ELEMENT (owner), NULL);
690 structure = gst_structure_empty_new ("GstMessageStructureChange");
691 gst_structure_id_set (structure,
692 GST_QUARK (TYPE), GST_TYPE_STRUCTURE_CHANGE_TYPE, type,
693 GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner,
694 GST_QUARK (BUSY), G_TYPE_BOOLEAN, busy, NULL);
696 message = gst_message_new_custom (GST_MESSAGE_STRUCTURE_CHANGE, src,
703 * gst_message_new_segment_start:
704 * @src: The object originating the message.
705 * @format: The format of the position being played
706 * @position: The position of the segment being played
708 * Create a new segment message. This message is posted by elements that
709 * start playback of a segment as a result of a segment seek. This message
710 * is not received by the application but is used for maintenance reasons in
711 * container elements.
713 * Returns: The new segment start message.
718 gst_message_new_segment_start (GstObject * src, GstFormat format,
722 GstStructure *structure;
724 structure = gst_structure_empty_new ("GstMessageSegmentStart");
725 gst_structure_id_set (structure,
726 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
727 GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
728 message = gst_message_new_custom (GST_MESSAGE_SEGMENT_START, src, structure);
734 * gst_message_new_segment_done:
735 * @src: The object originating the message.
736 * @format: The format of the position being done
737 * @position: The position of the segment being done
739 * Create a new segment done message. This message is posted by elements that
740 * finish playback of a segment as a result of a segment seek. This message
741 * is received by the application after all elements that posted a segment_start
742 * have posted the segment_done.
744 * Returns: The new segment done message.
749 gst_message_new_segment_done (GstObject * src, GstFormat format,
753 GstStructure *structure;
755 structure = gst_structure_empty_new ("GstMessageSegmentDone");
756 gst_structure_id_set (structure,
757 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
758 GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
759 message = gst_message_new_custom (GST_MESSAGE_SEGMENT_DONE, src, structure);
765 * gst_message_new_application:
766 * @src: The object originating the message.
767 * @structure: The structure for the message. The message will take ownership of
770 * Create a new application-typed message. GStreamer will never create these
771 * messages; they are a gift from us to you. Enjoy.
773 * Returns: The new application message.
778 gst_message_new_application (GstObject * src, GstStructure * structure)
780 return gst_message_new_custom (GST_MESSAGE_APPLICATION, src, structure);
784 * gst_message_new_element:
785 * @src: The object originating the message.
786 * @structure: The structure for the message. The message will take ownership of
789 * Create a new element-specific message. This is meant as a generic way of
790 * allowing one-way communication from an element to an application, for example
791 * "the firewire cable was unplugged". The format of the message should be
792 * documented in the element's documentation. The structure field can be NULL.
794 * Returns: The new element message.
799 gst_message_new_element (GstObject * src, GstStructure * structure)
801 return gst_message_new_custom (GST_MESSAGE_ELEMENT, src, structure);
805 * gst_message_new_duration:
806 * @src: The object originating the message.
807 * @format: The format of the duration
808 * @duration: The new duration
810 * Create a new duration message. This message is posted by elements that
811 * know the duration of a stream in a specific format. This message
812 * is received by bins and is used to calculate the total duration of a
813 * pipeline. Elements may post a duration message with a duration of
814 * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the
815 * cached duration should be discarded. The new duration can then be
816 * retrieved via a query.
818 * Returns: The new duration message.
823 gst_message_new_duration (GstObject * src, GstFormat format, gint64 duration)
826 GstStructure *structure;
828 structure = gst_structure_empty_new ("GstMessageDuration");
829 gst_structure_id_set (structure,
830 GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
831 GST_QUARK (DURATION), G_TYPE_INT64, duration, NULL);
832 message = gst_message_new_custom (GST_MESSAGE_DURATION, src, structure);
838 * gst_message_new_async_start:
839 * @src: The object originating the message.
840 * @new_base_time: if a new base_time should be set on the element
842 * This message is posted by elements when they start an ASYNC state change.
843 * @new_base_time is set to TRUE when the element lost its state when it was
846 * Returns: The new async_start message.
853 gst_message_new_async_start (GstObject * src, gboolean new_base_time)
856 GstStructure *structure;
858 structure = gst_structure_empty_new ("GstMessageAsyncStart");
859 gst_structure_id_set (structure,
860 GST_QUARK (NEW_BASE_TIME), G_TYPE_BOOLEAN, new_base_time, NULL);
861 message = gst_message_new_custom (GST_MESSAGE_ASYNC_START, src, structure);
867 * gst_message_new_async_done:
868 * @src: The object originating the message.
870 * The message is posted when elements completed an ASYNC state change.
872 * Returns: The new async_done message.
879 gst_message_new_async_done (GstObject * src)
883 message = gst_message_new_custom (GST_MESSAGE_ASYNC_DONE, src, NULL);
889 * gst_message_new_latency:
890 * @src: The object originating the message.
892 * This message can be posted by elements when their latency requirements have
895 * Returns: The new latency message.
902 gst_message_new_latency (GstObject * src)
906 message = gst_message_new_custom (GST_MESSAGE_LATENCY, src, NULL);
912 * gst_message_new_request_state:
913 * @src: The object originating the message.
914 * @state: The new requested state
916 * This message can be posted by elements when they want to have their state
917 * changed. A typical use case would be an audio server that wants to pause the
918 * pipeline because a higher priority stream is being played.
920 * Returns: The new requst state message.
927 gst_message_new_request_state (GstObject * src, GstState state)
930 GstStructure *structure;
932 structure = gst_structure_empty_new ("GstMessageRequestState");
933 gst_structure_id_set (structure,
934 GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) state, NULL);
935 message = gst_message_new_custom (GST_MESSAGE_REQUEST_STATE, src, structure);
941 * gst_message_get_structure:
942 * @message: The #GstMessage.
944 * Access the structure of the message.
946 * Returns: The structure of the message. The structure is still
947 * owned by the message, which means that you should not free it and
948 * that the pointer becomes invalid when you free the message.
953 gst_message_get_structure (GstMessage * message)
955 g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
957 return message->structure;
961 * gst_message_parse_tag:
962 * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
963 * @tag_list: Return location for the tag-list.
965 * Extracts the tag list from the GstMessage. The tag list returned in the
966 * output argument is a copy; the caller must free it when done.
971 gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
973 g_return_if_fail (GST_IS_MESSAGE (message));
974 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TAG);
975 g_return_if_fail (tag_list != NULL);
977 *tag_list = (GstTagList *) gst_structure_copy (message->structure);
981 * gst_message_parse_buffering:
982 * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
983 * @percent: Return location for the percent.
985 * Extracts the buffering percent from the GstMessage. see also
986 * gst_message_new_buffering().
993 gst_message_parse_buffering (GstMessage * message, gint * percent)
995 g_return_if_fail (GST_IS_MESSAGE (message));
996 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
999 *percent = g_value_get_int (gst_structure_id_get_value (message->structure,
1000 GST_QUARK (BUFFER_PERCENT)));
1004 * gst_message_set_buffering_stats:
1005 * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1006 * @mode: a buffering mode
1007 * @avg_in: the average input rate
1008 * @avg_out: the average output rate
1009 * @buffering_left: amount of buffering time left in milliseconds
1011 * Configures the buffering stats values in @message.
1016 gst_message_set_buffering_stats (GstMessage * message, GstBufferingMode mode,
1017 gint avg_in, gint avg_out, gint64 buffering_left)
1019 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1021 gst_structure_id_set (message->structure,
1022 GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, mode,
1023 GST_QUARK (AVG_IN_RATE), G_TYPE_INT, avg_in,
1024 GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, avg_out,
1025 GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
1029 * gst_message_parse_buffering_stats:
1030 * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1031 * @mode: a buffering mode
1032 * @avg_in: the average input rate
1033 * @avg_out: the average output rate
1034 * @buffering_left: amount of buffering time left in milliseconds.
1036 * Extracts the buffering stats values from @message.
1041 gst_message_parse_buffering_stats (GstMessage * message,
1042 GstBufferingMode * mode, gint * avg_in, gint * avg_out,
1043 gint64 * buffering_left)
1045 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1048 *mode = g_value_get_enum (gst_structure_id_get_value (message->structure,
1049 GST_QUARK (BUFFERING_MODE)));
1051 *avg_in = g_value_get_int (gst_structure_id_get_value (message->structure,
1052 GST_QUARK (AVG_IN_RATE)));
1054 *avg_out = g_value_get_int (gst_structure_id_get_value (message->structure,
1055 GST_QUARK (AVG_OUT_RATE)));
1058 g_value_get_int64 (gst_structure_id_get_value (message->structure,
1059 GST_QUARK (BUFFERING_LEFT)));
1063 * gst_message_parse_state_changed:
1064 * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED
1065 * @oldstate: the previous state, or NULL
1066 * @newstate: the new (current) state, or NULL
1067 * @pending: the pending (target) state, or NULL
1069 * Extracts the old and new states from the GstMessage.
1074 gst_message_parse_state_changed (GstMessage * message,
1075 GstState * oldstate, GstState * newstate, GstState * pending)
1077 g_return_if_fail (GST_IS_MESSAGE (message));
1078 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STATE_CHANGED);
1082 g_value_get_enum (gst_structure_id_get_value (message->structure,
1083 GST_QUARK (OLD_STATE)));
1086 g_value_get_enum (gst_structure_id_get_value (message->structure,
1087 GST_QUARK (NEW_STATE)));
1089 *pending = g_value_get_enum (gst_structure_id_get_value (message->structure,
1090 GST_QUARK (PENDING_STATE)));
1094 * gst_message_parse_clock_provide:
1095 * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.
1096 * @clock: A pointer to hold a clock object.
1097 * @ready: A pointer to hold the ready flag.
1099 * Extracts the clock and ready flag from the GstMessage.
1100 * The clock object returned remains valid until the message is freed.
1105 gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock,
1108 const GValue *clock_gvalue;
1110 g_return_if_fail (GST_IS_MESSAGE (message));
1111 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_PROVIDE);
1114 gst_structure_id_get_value (message->structure, GST_QUARK (CLOCK));
1115 g_return_if_fail (clock_gvalue != NULL);
1116 g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1120 g_value_get_boolean (gst_structure_id_get_value (message->structure,
1121 GST_QUARK (READY)));
1123 *clock = (GstClock *) g_value_get_object (clock_gvalue);
1127 * gst_message_parse_clock_lost:
1128 * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST.
1129 * @clock: A pointer to hold the lost clock
1131 * Extracts the lost clock from the GstMessage.
1132 * The clock object returned remains valid until the message is freed.
1137 gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock)
1139 const GValue *clock_gvalue;
1141 g_return_if_fail (GST_IS_MESSAGE (message));
1142 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_LOST);
1145 gst_structure_id_get_value (message->structure, GST_QUARK (CLOCK));
1146 g_return_if_fail (clock_gvalue != NULL);
1147 g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1150 *clock = (GstClock *) g_value_get_object (clock_gvalue);
1154 * gst_message_parse_new_clock:
1155 * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK.
1156 * @clock: A pointer to hold the selected new clock
1158 * Extracts the new clock from the GstMessage.
1159 * The clock object returned remains valid until the message is freed.
1164 gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)
1166 const GValue *clock_gvalue;
1168 g_return_if_fail (GST_IS_MESSAGE (message));
1169 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_NEW_CLOCK);
1172 gst_structure_id_get_value (message->structure, GST_QUARK (CLOCK));
1173 g_return_if_fail (clock_gvalue != NULL);
1174 g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1177 *clock = (GstClock *) g_value_get_object (clock_gvalue);
1181 * gst_message_parse_structure_change:
1182 * @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.
1183 * @type: A pointer to hold the change type
1184 * @owner: The owner element of the message source
1185 * @busy: A pointer to hold whether the change is in progress or has been
1188 * Extracts the change type and completion status from the GstMessage.
1195 gst_message_parse_structure_change (GstMessage * message,
1196 GstStructureChangeType * type, GstElement ** owner, gboolean * busy)
1198 const GValue *owner_gvalue;
1200 g_return_if_fail (GST_IS_MESSAGE (message));
1201 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STRUCTURE_CHANGE);
1204 gst_structure_id_get_value (message->structure, GST_QUARK (OWNER));
1205 g_return_if_fail (owner_gvalue != NULL);
1206 g_return_if_fail (G_VALUE_TYPE (owner_gvalue) == GST_TYPE_ELEMENT);
1209 *type = g_value_get_enum (gst_structure_id_get_value (message->structure,
1212 *owner = (GstElement *) g_value_get_object (owner_gvalue);
1215 g_value_get_boolean (gst_structure_id_get_value (message->structure,
1220 * gst_message_parse_error:
1221 * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
1222 * @gerror: Location for the GError
1223 * @debug: Location for the debug message, or NULL
1225 * Extracts the GError and debug string from the GstMessage. The values returned
1226 * in the output arguments are copies; the caller must free them when done.
1231 gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
1233 const GValue *error_gvalue;
1236 g_return_if_fail (GST_IS_MESSAGE (message));
1237 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ERROR);
1240 gst_structure_id_get_value (message->structure, GST_QUARK (GERROR));
1241 g_return_if_fail (error_gvalue != NULL);
1242 g_return_if_fail (G_VALUE_TYPE (error_gvalue) == GST_TYPE_G_ERROR);
1244 error_val = (GError *) g_value_get_boxed (error_gvalue);
1246 *gerror = g_error_copy (error_val);
1252 g_value_dup_string (gst_structure_id_get_value (message->structure,
1253 GST_QUARK (DEBUG)));
1257 * gst_message_parse_warning:
1258 * @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
1259 * @gerror: Location for the GError
1260 * @debug: Location for the debug message, or NULL
1262 * Extracts the GError and debug string from the GstMessage. The values returned
1263 * in the output arguments are copies; the caller must free them when done.
1268 gst_message_parse_warning (GstMessage * message, GError ** gerror,
1271 const GValue *error_gvalue;
1274 g_return_if_fail (GST_IS_MESSAGE (message));
1275 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_WARNING);
1278 gst_structure_id_get_value (message->structure, GST_QUARK (GERROR));
1279 g_return_if_fail (error_gvalue != NULL);
1280 g_return_if_fail (G_VALUE_TYPE (error_gvalue) == GST_TYPE_G_ERROR);
1282 error_val = (GError *) g_value_get_boxed (error_gvalue);
1284 *gerror = g_error_copy (error_val);
1290 g_value_dup_string (gst_structure_id_get_value (message->structure,
1291 GST_QUARK (DEBUG)));
1295 * gst_message_parse_info:
1296 * @message: A valid #GstMessage of type GST_MESSAGE_INFO.
1297 * @gerror: Location for the GError
1298 * @debug: Location for the debug message, or NULL
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.
1308 gst_message_parse_info (GstMessage * message, GError ** gerror, gchar ** debug)
1310 const GValue *error_gvalue;
1313 g_return_if_fail (GST_IS_MESSAGE (message));
1314 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_INFO);
1317 gst_structure_id_get_value (message->structure, GST_QUARK (GERROR));
1318 g_return_if_fail (error_gvalue != NULL);
1319 g_return_if_fail (G_VALUE_TYPE (error_gvalue) == GST_TYPE_G_ERROR);
1321 error_val = (GError *) g_value_get_boxed (error_gvalue);
1323 *gerror = g_error_copy (error_val);
1329 g_value_dup_string (gst_structure_id_get_value (message->structure,
1330 GST_QUARK (DEBUG)));
1334 * gst_message_parse_segment_start:
1335 * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_START.
1336 * @format: Result location for the format, or NULL
1337 * @position: Result location for the position, or NULL
1339 * Extracts the position and format from the segment start message.
1344 gst_message_parse_segment_start (GstMessage * message, GstFormat * format,
1347 g_return_if_fail (GST_IS_MESSAGE (message));
1348 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_START);
1352 g_value_get_enum (gst_structure_id_get_value (message->structure,
1353 GST_QUARK (FORMAT)));
1356 g_value_get_int64 (gst_structure_id_get_value (message->structure,
1357 GST_QUARK (POSITION)));
1361 * gst_message_parse_segment_done:
1362 * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE.
1363 * @format: Result location for the format, or NULL
1364 * @position: Result location for the position, or NULL
1366 * Extracts the position and format from the segment start message.
1371 gst_message_parse_segment_done (GstMessage * message, GstFormat * format,
1374 g_return_if_fail (GST_IS_MESSAGE (message));
1375 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_DONE);
1379 g_value_get_enum (gst_structure_id_get_value (message->structure,
1380 GST_QUARK (FORMAT)));
1383 g_value_get_int64 (gst_structure_id_get_value (message->structure,
1384 GST_QUARK (POSITION)));
1388 * gst_message_parse_duration:
1389 * @message: A valid #GstMessage of type GST_MESSAGE_DURATION.
1390 * @format: Result location for the format, or NULL
1391 * @duration: Result location for the duration, or NULL
1393 * Extracts the duration and format from the duration message. The duration
1394 * might be GST_CLOCK_TIME_NONE, which indicates that the duration has
1395 * changed. Applications should always use a query to retrieve the duration
1401 gst_message_parse_duration (GstMessage * message, GstFormat * format,
1404 g_return_if_fail (GST_IS_MESSAGE (message));
1405 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_DURATION);
1409 g_value_get_enum (gst_structure_id_get_value (message->structure,
1410 GST_QUARK (FORMAT)));
1413 g_value_get_int64 (gst_structure_id_get_value (message->structure,
1414 GST_QUARK (DURATION)));
1418 * gst_message_parse_async_start:
1419 * @message: A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE.
1420 * @new_base_time: Result location for the new_base_time or NULL
1422 * Extract the new_base_time from the async_start message.
1429 gst_message_parse_async_start (GstMessage * message, gboolean * new_base_time)
1431 g_return_if_fail (GST_IS_MESSAGE (message));
1432 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ASYNC_START);
1436 g_value_get_boolean (gst_structure_id_get_value (message->structure,
1437 GST_QUARK (NEW_BASE_TIME)));
1441 * gst_message_parse_request_state:
1442 * @message: A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE.
1443 * @state: Result location for the requested state or NULL
1445 * Extract the requested state from the request_state message.
1452 gst_message_parse_request_state (GstMessage * message, GstState * state)
1454 g_return_if_fail (GST_IS_MESSAGE (message));
1455 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_REQUEST_STATE);
1458 *state = g_value_get_enum (gst_structure_id_get_value (message->structure,
1459 GST_QUARK (NEW_STATE)));
1463 * gst_message_new_stream_status:
1464 * @src: The object originating the message.
1465 * @type: The stream status type.
1466 * @owner: The owner element of @src.
1468 * Create a new stream status message. This message is posted when a streaming
1469 * thread is created/destroyed or when the state changed.
1471 * Returns: The new stream status message.
1478 gst_message_new_stream_status (GstObject * src, GstStreamStatusType type,
1481 GstMessage *message;
1482 GstStructure *structure;
1484 structure = gst_structure_empty_new ("GstMessageStreamStatus");
1485 gst_structure_id_set (structure,
1486 GST_QUARK (TYPE), GST_TYPE_STREAM_STATUS_TYPE, (gint) type,
1487 GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner, NULL);
1488 message = gst_message_new_custom (GST_MESSAGE_STREAM_STATUS, src, structure);
1494 * gst_message_parse_stream_status:
1495 * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1496 * @type: A pointer to hold the status type
1497 * @owner: The owner element of the message source
1499 * Extracts the stream status type and owner the GstMessage. The returned
1500 * owner remains valid for as long as the reference to @message is valid and
1501 * should thus not be unreffed.
1508 gst_message_parse_stream_status (GstMessage * message,
1509 GstStreamStatusType * type, GstElement ** owner)
1511 const GValue *owner_gvalue;
1513 g_return_if_fail (GST_IS_MESSAGE (message));
1514 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1517 gst_structure_id_get_value (message->structure, GST_QUARK (OWNER));
1518 g_return_if_fail (owner_gvalue != NULL);
1521 *type = g_value_get_enum (gst_structure_id_get_value (message->structure,
1524 *owner = (GstElement *) g_value_get_object (owner_gvalue);
1528 * gst_message_set_stream_status_object:
1529 * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1530 * @object: the object controlling the streaming
1532 * Configures the object handling the streaming thread. This is usually a
1533 * GstTask object but other objects might be added in the future.
1538 gst_message_set_stream_status_object (GstMessage * message,
1539 const GValue * object)
1541 g_return_if_fail (GST_IS_MESSAGE (message));
1542 g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1544 gst_structure_id_set_value (message->structure, GST_QUARK (OBJECT), object);
1548 * gst_message_get_stream_status_object:
1549 * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1551 * Extracts the object managing the streaming thread from @message.
1553 * Returns: a GValue containing the object that manages the streaming thread.
1554 * This object is usually of type GstTask but other types can be added in the
1555 * future. The object remains valid as long as @message is valid.
1560 gst_message_get_stream_status_object (GstMessage * message)
1562 const GValue *result;
1564 g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
1565 g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS,
1568 result = gst_structure_id_get_value (message->structure, GST_QUARK (OBJECT));