wearable/docs/manual/basics-bus.xml

   1 <chapter id="chapter-bus">
   2   <title>Bus</title>
   3   <para>
   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.
   9   </para>
  10   <para>
  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
  16     message is available.
  17   </para>
  18
  19   <sect1 id="section-bus-howto">
  20     <title>How to use a bus</title>
  21     <para>
  22       There are two different ways to use a bus:
  23       <itemizedlist>
  24         <listitem>
  25           <para>
  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.
  30           </para>
  31           <para>
  32             Typically you would use <function>gst_bus_add_watch ()</function>
  33             or <function>gst_bus_add_signal_watch ()</function> in this case.
  34           </para>
  35           <para>
  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             keep the handler attached to the bus, return FALSE to remove it.
  42           </para>
  43         </listitem>
  44         <listitem>
  45           <para>
  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>.
  49           </para>
  50         </listitem>
  51       </itemizedlist>
  52     </para>
  53     <programlisting><!-- example-begin bus.c a -->
  54 #include &lt;gst/gst.h&gt;
  55
  56 static GMainLoop *loop;
  57
  58 static gboolean
  59 my_bus_callback (GstBus     *bus,
  60                  GstMessage *message,
  61                  gpointer    data)
  62 {
  63   g_print ("Got %s message\n", GST_MESSAGE_TYPE_NAME (message));
  64
  65   switch (GST_MESSAGE_TYPE (message)) {
  66     case GST_MESSAGE_ERROR: {
  67       GError *err;
  68       gchar *debug;
  69
  70       gst_message_parse_error (message, &amp;err, &amp;debug);
  71       g_print ("Error: %s\n", err-&gt;message);
  72       g_error_free (err);
  73       g_free (debug);
  74
  75       g_main_loop_quit (loop);
  76       break;
  77     }
  78     case GST_MESSAGE_EOS:
  79       /* end-of-stream */
  80       g_main_loop_quit (loop);
  81       break;
  82     default:
  83       /* unhandled message */
  84       break;
  85   }
  86
  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)
  90    */
  91   return TRUE;
  92 }
  93
  94 gint
  95 main (gint   argc,
  96       gchar *argv[])
  97 {
  98   GstElement *pipeline;
  99   GstBus *bus;
 100
 101   /* init */
 102   gst_init (&amp;argc, &amp;argv);
 103
 104   /* create pipeline, add handler */
 105   pipeline = gst_pipeline_new ("my_pipeline");
 106
 107   /* adds a watch for new message on our pipeline&apos;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
 110    */
 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()
 123    */
 124   loop = g_main_loop_new (NULL, FALSE);
 125   g_main_loop_run (loop);
 126
 127   /* clean up */
 128   gst_element_set_state (pipeline, GST_STATE_NULL);
 129   gst_object_unref (pipeline);
 130   g_main_loop_unref (loop);
 131
 132   return 0;
 133 }
 134     <!-- example-end bus.c c -->
 135     </programlisting>
 136     <para>
 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
 149       all.
 150     </para>
 151     <para>
 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::&lt;type&gt;</quote>, where &lt;type&gt;
 158       is a specific message type (see the next section for an explanation of
 159       message types).
 160     </para>
 161     <para>
 162       The above snippet could then also be written as:
 163     </para>
 164     <programlisting>
 165 GstBus *bus;
 166
 167 [..]
 168
 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);
 173
 174 [..]
 175     </programlisting>
 176     <para>
 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)
 183     </para>
 184   </sect1>
 185
 186   <sect1 id="section-bus-message-types">
 187     <title>Message types</title>
 188     <para>
 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.
 195     </para>
 196     <para>
 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.
 203     </para>
 204     <itemizedlist>
 205       <listitem>
 206         <para>
 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.
 219         </para>
 220       </listitem>
 221       <listitem>
 222         <para>
 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.
 229         </para>
 230       </listitem>
 231       <listitem>
 232         <para>
 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
 240           needed.
 241         </para>
 242       </listitem>
 243       <listitem>
 244         <para>
 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.
 248         </para>
 249       </listitem>
 250       <listitem>
 251         <para>
 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
 256           ()</function>.
 257         </para>
 258       </listitem>
 259       <listitem>
 260         <para>
 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.
 268         </para>
 269       </listitem>
 270       <listitem>
 271         <para>
 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.
 275         </para>
 276         <para>
 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
 282           streaming thread).
 283         </para>
 284       </listitem>
 285     </itemizedlist>
 286   </sect1>
 287 </chapter>