1 <chapter id="chapter-bus">
4 A bus is a simple system that takes care of forwarding messages from
5 the pipeline threads to an application in its own thread context. The
6 advantage of a bus is that an application does not need to be
7 thread-aware in order to use &GStreamer;, even though &GStreamer;
8 itself is heavily threaded.
11 Every pipeline contains a bus by default, so applications do not need
12 to create a bus or anything. The only thing applications should do is
13 set a message handler on a bus, which is similar to a signal handler
14 to an object. When the mainloop is running, the bus will periodically
15 be checked for new messages, and the callback will be called when any
19 <sect1 id="section-bus-howto">
20 <title>How to use a bus</title>
22 There are two different ways to use a bus:
26 Run a GLib/Gtk+ main loop (or iterate the default GLib main
27 context yourself regularly) and attach some kind of watch to the
28 bus. This way the GLib main loop will check the bus for new
29 messages and notify you whenever there are messages.
32 Typically you would use <function>gst_bus_add_watch ()</function>
33 or <function>gst_bus_add_signal_watch ()</function> in this case.
36 To use a bus, attach a message handler to the bus of a pipeline
37 using <function>gst_bus_add_watch ()</function>. This handler will
38 be called whenever the pipeline emits a message to the bus. In this
39 handler, check the signal type (see next section) and do something
40 accordingly. The return value of the handler should be TRUE to
41 remove the message from the bus.
46 Check for messages on the bus yourself. This can be done using
47 <function>gst_bus_peek ()</function> and/or
48 <function>gst_bus_poll ()</function>.
53 <programlisting><!-- example-begin bus.c a -->
54 #include <gst/gst.h>
56 static GMainLoop *loop;
59 my_bus_callback (GstBus *bus,
63 g_print ("Got %s message\n", GST_MESSAGE_TYPE_NAME (message));
65 switch (GST_MESSAGE_TYPE (message)) {
66 case GST_MESSAGE_ERROR: {
70 gst_message_parse_error (message, &err, &debug);
71 g_print ("Error: %s\n", err->message);
75 g_main_loop_quit (loop);
80 g_main_loop_quit (loop);
83 /* unhandled message */
87 /* we want to be notified again the next time there is a message
88 * on the bus, so returning TRUE (FALSE means we want to stop watching
89 * for messages on the bus and our callback should not be called again)
102 gst_init (&argc, &argv);
104 /* create pipeline, add handler */
105 pipeline = gst_pipeline_new ("my_pipeline");
107 /* adds a watch for new message on our pipeline's message bus to
108 * the default GLib main context, which is the main context that our
109 * GLib main loop is attached to below
111 bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
112 gst_bus_add_watch (bus, my_bus_callback, NULL);
113 gst_object_unref (bus);
114 <!-- example-end bus.c a -->
115 [..]<!-- example-begin bus.c b -->
116 <!-- example-begin bus.c c -->
117 /* create a mainloop that runs/iterates the default GLib main context
118 * (context NULL), in other words: makes the context check if anything
119 * it watches for has happened. When a message has been posted on the
120 * bus, the default main context will automatically call our
121 * my_bus_callback() function to notify us of that message.
122 * The main loop will be run until someone calls g_main_loop_quit()
124 loop = g_main_loop_new (NULL, FALSE);
125 g_main_loop_run (loop);
128 gst_element_set_state (pipeline, GST_STATE_NULL);
129 gst_object_unref (pipeline);
130 g_main_loop_unref (loop);
134 <!-- example-end bus.c c -->
137 It is important to know that the handler will be called in the thread
138 context of the mainloop. This means that the interaction between the
139 pipeline and application over the bus is
140 <emphasis>asynchronous</emphasis>, and thus not suited for some
141 real-time purposes, such as cross-fading between audio tracks, doing
142 (theoretically) gapless playback or video effects. All such things
143 should be done in the pipeline context, which is easiest by writing
144 a &GStreamer; plug-in. It is very useful for its primary purpose,
145 though: passing messages from pipeline to application.
146 The advantage of this approach is that all the threading that
147 &GStreamer; does internally is hidden from the application and the
148 application developer does not have to worry about thread issues at
152 Note that if you're using the default GLib mainloop integration, you
153 can, instead of attaching a watch, connect to the <quote>message</quote>
154 signal on the bus. This way you don't have to
155 <function>switch()</function>
156 on all possible message types; just connect to the interesting signals
157 in form of <quote>message::<type></quote>, where <type>
158 is a specific message type (see the next section for an explanation of
162 The above snippet could then also be written as:
169 bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline);
170 gst_bus_add_signal_watch (bus);
171 g_signal_connect (bus, "message::error", G_CALLBACK (cb_message_error), NULL);
172 g_signal_connect (bus, "message::eos", G_CALLBACK (cb_message_eos), NULL);
177 If you aren't using GLib mainloop, the asynchronous message signals won't
178 be available by default. You can however install a custom sync handler
179 that wakes up the custom mainloop and that uses
180 <function>gst_bus_async_signal_func ()</function> to emit the signals.
181 (see also <ulink type="http"
182 url="&URLAPI;GstBus.html">documentation</ulink> for details)
186 <sect1 id="section-bus-message-types">
187 <title>Message types</title>
189 &GStreamer; has a few pre-defined message types that can be passed
190 over the bus. The messages are extensible, however. Plug-ins can
191 define additional messages, and applications can decide to either
192 have specific code for those or ignore them. All applications are
193 strongly recommended to at least handle error messages by providing
194 visual feedback to the user.
197 All messages have a message source, type and timestamp. The message
198 source can be used to see which element emitted the message. For some
199 messages, for example, only the ones emitted by the top-level pipeline
200 will be interesting to most applications (e.g. for state-change
201 notifications). Below is a list of all messages and a short explanation
202 of what they do and how to parse message-specific content.
207 Error, warning and information notifications: those are used
208 by elements if a message should be shown to the user about the
209 state of the pipeline. Error messages are fatal and terminate
210 the data-passing. The error should be repaired to resume pipeline
211 activity. Warnings are not fatal, but imply a problem nevertheless.
212 Information messages are for non-problem notifications. All those
213 messages contain a <classname>GError</classname> with the main
214 error type and message, and optionally a debug string. Both
215 can be extracted using <function>gst_message_parse_error
216 ()</function>, <function>_parse_warning ()</function> and
217 <function>_parse_info ()</function>. Both error and debug strings
218 should be freed after use.
223 End-of-stream notification: this is emitted when the stream has
224 ended. The state of the pipeline will not change, but further
225 media handling will stall. Applications can use this to skip to
226 the next song in their playlist. After end-of-stream, it is also
227 possible to seek back in the stream. Playback will then continue
228 automatically. This message has no specific arguments.
233 Tags: emitted when metadata was found in the stream. This can be
234 emitted multiple times for a pipeline (e.g. once for descriptive
235 metadata such as artist name or song title, and another one for
236 stream-information, such as samplerate and bitrate). Applications
237 should cache metadata internally. <function>gst_message_parse_tag
238 ()</function> should be used to parse the taglist, which should
239 be <function>gst_tag_list_free ()</function>'ed when no longer
245 State-changes: emitted after a successful state change.
246 <function>gst_message_parse_state_changed ()</function> can be
247 used to parse the old and new state of this transition.
252 Buffering: emitted during caching of network-streams. One can
253 manually extract the progress (in percent) from the message by
254 extracting the <quote>buffer-percent</quote> property from the
255 structure returned by <function>gst_message_get_structure
261 Element messages: these are special messages that are unique to
262 certain elements and usually represent additional features. The
263 element's documentation should mention in detail which
264 element messages a particular element may send. As an example,
265 the 'qtdemux' QuickTime demuxer element may send a 'redirect'
266 element message on certain occasions if the stream contains a
267 redirect instruction.
272 Application-specific messages: any information on those can
273 be extracted by getting the message structure (see above) and
274 reading its fields. Usually these messages can safely be ignored.
277 Application messages are primarily meant for internal
278 use in applications in case the application needs to marshal
279 information from some thread into the main thread. This is
280 particularly useful when the application is making use of element
281 signals (as those signals will be emitted in the context of the