mobile/docs/gst/html/GstBus.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>GstBus</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GStreamer 0.10 Core Reference Manual">
   8 <link rel="up" href="libgstreamer.html" title="GStreamer Core Library">
   9 <link rel="prev" href="gstreamer-GstBufferList.html" title="GstBufferList">
  10 <link rel="next" href="gstreamer-GstCaps.html" title="GstCaps">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="gstreamer-GstBufferList.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="libgstreamer.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GStreamer 0.10 Core Reference Manual</th>
  21 <td><a accesskey="n" href="gstreamer-GstCaps.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#GstBus.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#GstBus.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#GstBus.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29                    |
  30                   <a href="#GstBus.signals" class="shortcut">Signals</a>
  31 </td></tr>
  32 </table>
  33 <div class="refentry">
  34 <a name="GstBus"></a><div class="titlepage"></div>
  35 <div class="refnamediv"><table width="100%"><tr>
  36 <td valign="top">
  37 <h2><span class="refentrytitle"><a name="GstBus.top_of_page"></a>GstBus</span></h2>
  38 <p>GstBus — Asynchronous message bus subsystem</p>
  39 </td>
  40 <td valign="top" align="right"></td>
  41 </tr></table></div>
  42 <div class="refsynopsisdiv">
  43 <a name="GstBus.synopsis"></a><h2>Synopsis</h2>
  44 <pre class="synopsis">
  45 #include &lt;gst/gst.h&gt;
  46
  47 struct              <a class="link" href="GstBus.html#GstBus-struct" title="struct GstBus">GstBus</a>;
  48 enum                <a class="link" href="GstBus.html#GstBusFlags" title="enum GstBusFlags">GstBusFlags</a>;
  49 enum                <a class="link" href="GstBus.html#GstBusSyncReply" title="enum GstBusSyncReply">GstBusSyncReply</a>;
  50 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (<a class="link" href="GstBus.html#GstBusFunc" title="GstBusFunc ()">*GstBusFunc</a>)                       (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
  52                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  53 <a class="link" href="GstBus.html#GstBusSyncReply" title="enum GstBusSyncReply"><span class="returnvalue">GstBusSyncReply</span></a>     (<a class="link" href="GstBus.html#GstBusSyncHandler" title="GstBusSyncHandler ()">*GstBusSyncHandler</a>)                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  54                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
  55                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  56 <a class="link" href="GstBus.html" title="GstBus"><span class="returnvalue">GstBus</span></a> *            <a class="link" href="GstBus.html#gst-bus-new" title="gst_bus_new ()">gst_bus_new</a>                         (<em class="parameter"><code><span class="type">void</span></code></em>);
  57 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GstBus.html#gst-bus-post" title="gst_bus_post ()">gst_bus_post</a>                        (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  58                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>);
  59 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GstBus.html#gst-bus-have-pending" title="gst_bus_have_pending ()">gst_bus_have_pending</a>                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  60 <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        <a class="link" href="GstBus.html#gst-bus-peek" title="gst_bus_peek ()">gst_bus_peek</a>                        (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  61 <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        <a class="link" href="GstBus.html#gst-bus-pop" title="gst_bus_pop ()">gst_bus_pop</a>                         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  62 <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        <a class="link" href="GstBus.html#gst-bus-pop-filtered" title="gst_bus_pop_filtered ()">gst_bus_pop_filtered</a>                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  63                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessageType" title="enum GstMessageType"><span class="type">GstMessageType</span></a> types</code></em>);
  64 <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        <a class="link" href="GstBus.html#gst-bus-timed-pop" title="gst_bus_timed_pop ()">gst_bus_timed_pop</a>                   (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  65                                                          <em class="parameter"><code><a class="link" href="GstClock.html#GstClockTime" title="GstClockTime"><span class="type">GstClockTime</span></a> timeout</code></em>);
  66 <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        <a class="link" href="GstBus.html#gst-bus-timed-pop-filtered" title="gst_bus_timed_pop_filtered ()">gst_bus_timed_pop_filtered</a>          (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  67                                                          <em class="parameter"><code><a class="link" href="GstClock.html#GstClockTime" title="GstClockTime"><span class="type">GstClockTime</span></a> timeout</code></em>,
  68                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessageType" title="enum GstMessageType"><span class="type">GstMessageType</span></a> types</code></em>);
  69 <span class="returnvalue">void</span>                <a class="link" href="GstBus.html#gst-bus-set-flushing" title="gst_bus_set_flushing ()">gst_bus_set_flushing</a>                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  70                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> flushing</code></em>);
  71 <span class="returnvalue">void</span>                <a class="link" href="GstBus.html#gst-bus-set-sync-handler" title="gst_bus_set_sync_handler ()">gst_bus_set_sync_handler</a>            (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  72                                                          <em class="parameter"><code><a class="link" href="GstBus.html#GstBusSyncHandler" title="GstBusSyncHandler ()"><span class="type">GstBusSyncHandler</span></a> func</code></em>,
  73                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  74 <a class="link" href="GstBus.html#GstBusSyncReply" title="enum GstBusSyncReply"><span class="returnvalue">GstBusSyncReply</span></a>     <a class="link" href="GstBus.html#gst-bus-sync-signal-handler" title="gst_bus_sync_signal_handler ()">gst_bus_sync_signal_handler</a>         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  75                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
  76                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  77 <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> *           <a class="link" href="GstBus.html#gst-bus-create-watch" title="gst_bus_create_watch ()">gst_bus_create_watch</a>                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  78 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="GstBus.html#gst-bus-add-watch-full" title="gst_bus_add_watch_full ()">gst_bus_add_watch_full</a>              (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  79                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
  80                                                          <em class="parameter"><code><a class="link" href="GstBus.html#GstBusFunc" title="GstBusFunc ()"><span class="type">GstBusFunc</span></a> func</code></em>,
  81                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
  82                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
  83 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="GstBus.html#gst-bus-add-watch" title="gst_bus_add_watch ()">gst_bus_add_watch</a>                   (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  84                                                          <em class="parameter"><code><a class="link" href="GstBus.html#GstBusFunc" title="GstBusFunc ()"><span class="type">GstBusFunc</span></a> func</code></em>,
  85                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  86 <span class="returnvalue">void</span>                <a class="link" href="GstBus.html#gst-bus-disable-sync-message-emission" title="gst_bus_disable_sync_message_emission ()">gst_bus_disable_sync_message_emission</a>
  87                                                         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  88 <span class="returnvalue">void</span>                <a class="link" href="GstBus.html#gst-bus-enable-sync-message-emission" title="gst_bus_enable_sync_message_emission ()">gst_bus_enable_sync_message_emission</a>
  89                                                         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  90 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GstBus.html#gst-bus-async-signal-func" title="gst_bus_async_signal_func ()">gst_bus_async_signal_func</a>           (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  91                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
  92                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  93 <span class="returnvalue">void</span>                <a class="link" href="GstBus.html#gst-bus-add-signal-watch" title="gst_bus_add_signal_watch ()">gst_bus_add_signal_watch</a>            (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  94 <span class="returnvalue">void</span>                <a class="link" href="GstBus.html#gst-bus-add-signal-watch-full" title="gst_bus_add_signal_watch_full ()">gst_bus_add_signal_watch_full</a>       (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  95                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>);
  96 <span class="returnvalue">void</span>                <a class="link" href="GstBus.html#gst-bus-remove-signal-watch" title="gst_bus_remove_signal_watch ()">gst_bus_remove_signal_watch</a>         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);
  97 <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        <a class="link" href="GstBus.html#gst-bus-poll" title="gst_bus_poll ()">gst_bus_poll</a>                        (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
  98                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessageType" title="enum GstMessageType"><span class="type">GstMessageType</span></a> events</code></em>,
  99                                                          <em class="parameter"><code><a class="link" href="GstClock.html#GstClockTimeDiff" title="GstClockTimeDiff"><span class="type">GstClockTimeDiff</span></a> timeout</code></em>);
 100 </pre>
 101 </div>
 102 <div class="refsect1">
 103 <a name="GstBus.object-hierarchy"></a><h2>Object Hierarchy</h2>
 104 <pre class="synopsis">
 105   <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>
 106    +----<a class="link" href="GstObject.html" title="GstObject">GstObject</a>
 107          +----GstBus
 108 </pre>
 109 </div>
 110 <div class="refsect1">
 111 <a name="GstBus.signals"></a><h2>Signals</h2>
 112 <pre class="synopsis">
 113   "<a class="link" href="GstBus.html#GstBus-message" title='The "message" signal'>message</a>"                                        : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-DETAILED:CAPS"><code class="literal">Has Details</code></a>
 114   "<a class="link" href="GstBus.html#GstBus-sync-message" title='The "sync-message" signal'>sync-message</a>"                                   : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-DETAILED:CAPS"><code class="literal">Has Details</code></a>
 115 </pre>
 116 </div>
 117 <div class="refsect1">
 118 <a name="GstBus.description"></a><h2>Description</h2>
 119 <p>
 120 The <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> is an object responsible for delivering <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> packets in
 121 a first-in first-out way from the streaming threads (see <a class="link" href="GstTask.html" title="GstTask"><span class="type">GstTask</span></a>) to the
 122 application.
 123 </p>
 124 <p>
 125 Since the application typically only wants to deal with delivery of these
 126 messages from one thread, the GstBus will marshall the messages between
 127 different threads. This is important since the actual streaming of media
 128 is done in another thread than the application.
 129 </p>
 130 <p>
 131 The GstBus provides support for <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> based notifications. This makes it
 132 possible to handle the delivery in the glib mainloop.
 133 </p>
 134 <p>
 135 The <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> callback function <a class="link" href="GstBus.html#gst-bus-async-signal-func" title="gst_bus_async_signal_func ()"><code class="function">gst_bus_async_signal_func()</code></a> can be used to
 136 convert all bus messages into signal emissions.
 137 </p>
 138 <p>
 139 A message is posted on the bus with the <a class="link" href="GstBus.html#gst-bus-post" title="gst_bus_post ()"><code class="function">gst_bus_post()</code></a> method. With the
 140 <a class="link" href="GstBus.html#gst-bus-peek" title="gst_bus_peek ()"><code class="function">gst_bus_peek()</code></a> and <a class="link" href="GstBus.html#gst-bus-pop" title="gst_bus_pop ()"><code class="function">gst_bus_pop()</code></a> methods one can look at or retrieve a
 141 previously posted message.
 142 </p>
 143 <p>
 144 The bus can be polled with the <a class="link" href="GstBus.html#gst-bus-poll" title="gst_bus_poll ()"><code class="function">gst_bus_poll()</code></a> method. This methods blocks
 145 up to the specified timeout value until one of the specified messages types
 146 is posted on the bus. The application can then <a class="link" href="GstBus.html#gst-bus-pop" title="gst_bus_pop ()"><code class="function">gst_bus_pop()</code></a> the messages
 147 from the bus to handle them.
 148 Alternatively the application can register an asynchronous bus function
 149 using <a class="link" href="GstBus.html#gst-bus-add-watch-full" title="gst_bus_add_watch_full ()"><code class="function">gst_bus_add_watch_full()</code></a> or <a class="link" href="GstBus.html#gst-bus-add-watch" title="gst_bus_add_watch ()"><code class="function">gst_bus_add_watch()</code></a>. This function will
 150 install a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> in the default glib main loop and will deliver messages
 151 a short while after they have been posted. Note that the main loop should
 152 be running for the asynchronous callbacks.
 153 </p>
 154 <p>
 155 It is also possible to get messages from the bus without any thread
 156 marshalling with the <a class="link" href="GstBus.html#gst-bus-set-sync-handler" title="gst_bus_set_sync_handler ()"><code class="function">gst_bus_set_sync_handler()</code></a> method. This makes it
 157 possible to react to a message in the same thread that posted the
 158 message on the bus. This should only be used if the application is able
 159 to deal with messages from different threads.
 160 </p>
 161 <p>
 162 Every <a class="link" href="GstPipeline.html" title="GstPipeline"><span class="type">GstPipeline</span></a> has one bus.
 163 </p>
 164 <p>
 165 Note that a <a class="link" href="GstPipeline.html" title="GstPipeline"><span class="type">GstPipeline</span></a> will set its bus into flushing state when changing
 166 from READY to NULL state.
 167 </p>
 168 <p>
 169 Last reviewed on 2006-03-12 (0.10.5)
 170 </p>
 171 </div>
 172 <div class="refsect1">
 173 <a name="GstBus.details"></a><h2>Details</h2>
 174 <div class="refsect2">
 175 <a name="GstBus-struct"></a><h3>struct GstBus</h3>
 176 <pre class="programlisting">struct GstBus;</pre>
 177 <p>
 178 The opaque <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> data structure.
 179 </p>
 180 </div>
 181 <hr>
 182 <div class="refsect2">
 183 <a name="GstBusFlags"></a><h3>enum GstBusFlags</h3>
 184 <pre class="programlisting">typedef enum {
 185   GST_BUS_FLUSHING      = (GST_OBJECT_FLAG_LAST &lt;&lt; 0),
 186   /* padding */
 187   GST_BUS_FLAG_LAST     = (GST_OBJECT_FLAG_LAST &lt;&lt; 1)
 188 } GstBusFlags;
 189 </pre>
 190 <p>
 191 The standard flags that a bus may have.
 192 </p>
 193 <div class="variablelist"><table border="0">
 194 <col align="left" valign="top">
 195 <tbody>
 196 <tr>
 197 <td><p><a name="GST-BUS-FLUSHING:CAPS"></a><span class="term"><code class="literal">GST_BUS_FLUSHING</code></span></p></td>
 198 <td>The bus is currently dropping all messages
 199 </td>
 200 </tr>
 201 <tr>
 202 <td><p><a name="GST-BUS-FLAG-LAST:CAPS"></a><span class="term"><code class="literal">GST_BUS_FLAG_LAST</code></span></p></td>
 203 <td>offset to define more flags
 204 </td>
 205 </tr>
 206 </tbody>
 207 </table></div>
 208 </div>
 209 <hr>
 210 <div class="refsect2">
 211 <a name="GstBusSyncReply"></a><h3>enum GstBusSyncReply</h3>
 212 <pre class="programlisting">typedef enum {
 213   GST_BUS_DROP = 0,
 214   GST_BUS_PASS = 1,
 215   GST_BUS_ASYNC = 2
 216 } GstBusSyncReply;
 217 </pre>
 218 <p>
 219 The result values for a GstBusSyncHandler.
 220 </p>
 221 <div class="variablelist"><table border="0">
 222 <col align="left" valign="top">
 223 <tbody>
 224 <tr>
 225 <td><p><a name="GST-BUS-DROP:CAPS"></a><span class="term"><code class="literal">GST_BUS_DROP</code></span></p></td>
 226 <td>drop the message
 227 </td>
 228 </tr>
 229 <tr>
 230 <td><p><a name="GST-BUS-PASS:CAPS"></a><span class="term"><code class="literal">GST_BUS_PASS</code></span></p></td>
 231 <td>pass the message to the async queue
 232 </td>
 233 </tr>
 234 <tr>
 235 <td><p><a name="GST-BUS-ASYNC:CAPS"></a><span class="term"><code class="literal">GST_BUS_ASYNC</code></span></p></td>
 236 <td>pass message to async queue, continue if message is handled
 237 </td>
 238 </tr>
 239 </tbody>
 240 </table></div>
 241 </div>
 242 <hr>
 243 <div class="refsect2">
 244 <a name="GstBusFunc"></a><h3>GstBusFunc ()</h3>
 245 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (*GstBusFunc)                       (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 246                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
 247                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 248 <p>
 249 Specifies the type of function passed to <a class="link" href="GstBus.html#gst-bus-add-watch" title="gst_bus_add_watch ()"><code class="function">gst_bus_add_watch()</code></a> or
 250 <a class="link" href="GstBus.html#gst-bus-add-watch-full" title="gst_bus_add_watch_full ()"><code class="function">gst_bus_add_watch_full()</code></a>, which is called from the mainloop when a message
 251 is available on the bus.
 252 </p>
 253 <p>
 254 The message passed to the function will be unreffed after execution of this
 255 function so it should not be freed in the function.
 256 </p>
 257 <p>
 258 Note that this function is used as a GSourceFunc which means that returning
 259 FALSE will remove the GSource from the mainloop.
 260 </p>
 261 <div class="variablelist"><table border="0">
 262 <col align="left" valign="top">
 263 <tbody>
 264 <tr>
 265 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 266 <td>the <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> that sent the message</td>
 267 </tr>
 268 <tr>
 269 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
 270 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a>
 271 </td>
 272 </tr>
 273 <tr>
 274 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 275 <td>user data that has been given, when registering the handler</td>
 276 </tr>
 277 <tr>
 278 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 279 <td>
 280 <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the event source should be removed.</td>
 281 </tr>
 282 </tbody>
 283 </table></div>
 284 </div>
 285 <hr>
 286 <div class="refsect2">
 287 <a name="GstBusSyncHandler"></a><h3>GstBusSyncHandler ()</h3>
 288 <pre class="programlisting"><a class="link" href="GstBus.html#GstBusSyncReply" title="enum GstBusSyncReply"><span class="returnvalue">GstBusSyncReply</span></a>     (*GstBusSyncHandler)                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 289                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
 290                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 291 <p>
 292 Handler will be invoked synchronously, when a new message has been injected
 293 into the bus. This function is mostly used internally. Only one sync handler
 294 can be attached to a given bus.
 295 </p>
 296 <p>
 297 If the handler returns GST_BUS_DROP, it should unref the message, else the
 298 message should not be unreffed by the sync handler.
 299 </p>
 300 <div class="variablelist"><table border="0">
 301 <col align="left" valign="top">
 302 <tbody>
 303 <tr>
 304 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 305 <td>the <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> that sent the message</td>
 306 </tr>
 307 <tr>
 308 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
 309 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a>
 310 </td>
 311 </tr>
 312 <tr>
 313 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 314 <td>user data that has been given, when registering the handler</td>
 315 </tr>
 316 <tr>
 317 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 318 <td>
 319 <a class="link" href="GstBus.html#GstBusSyncReply" title="enum GstBusSyncReply"><span class="type">GstBusSyncReply</span></a> stating what to do with the message</td>
 320 </tr>
 321 </tbody>
 322 </table></div>
 323 </div>
 324 <hr>
 325 <div class="refsect2">
 326 <a name="gst-bus-new"></a><h3>gst_bus_new ()</h3>
 327 <pre class="programlisting"><a class="link" href="GstBus.html" title="GstBus"><span class="returnvalue">GstBus</span></a> *            gst_bus_new                         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 328 <p>
 329 Creates a new <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> instance.
 330 </p>
 331 <div class="variablelist"><table border="0">
 332 <col align="left" valign="top">
 333 <tbody><tr>
 334 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 335 <td>a new <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> instance. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 336 </td>
 337 </tr></tbody>
 338 </table></div>
 339 </div>
 340 <hr>
 341 <div class="refsect2">
 342 <a name="gst-bus-post"></a><h3>gst_bus_post ()</h3>
 343 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            gst_bus_post                        (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 344                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>);</pre>
 345 <p>
 346 Post a message on the given bus. Ownership of the message
 347 is taken by the bus.
 348 </p>
 349 <div class="variablelist"><table border="0">
 350 <col align="left" valign="top">
 351 <tbody>
 352 <tr>
 353 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 354 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to post on</td>
 355 </tr>
 356 <tr>
 357 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
 358 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> to post. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 359 </td>
 360 </tr>
 361 <tr>
 362 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 363 <td>TRUE if the message could be posted, FALSE if the bus is flushing.
 364 MT safe.</td>
 365 </tr>
 366 </tbody>
 367 </table></div>
 368 </div>
 369 <hr>
 370 <div class="refsect2">
 371 <a name="gst-bus-have-pending"></a><h3>gst_bus_have_pending ()</h3>
 372 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            gst_bus_have_pending                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 373 <p>
 374 Check if there are pending messages on the bus that
 375 should be handled.
 376 </p>
 377 <div class="variablelist"><table border="0">
 378 <col align="left" valign="top">
 379 <tbody>
 380 <tr>
 381 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 382 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to check</td>
 383 </tr>
 384 <tr>
 385 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 386 <td>TRUE if there are messages on the bus to be handled, FALSE
 387 otherwise.
 388 MT safe.</td>
 389 </tr>
 390 </tbody>
 391 </table></div>
 392 </div>
 393 <hr>
 394 <div class="refsect2">
 395 <a name="gst-bus-peek"></a><h3>gst_bus_peek ()</h3>
 396 <pre class="programlisting"><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        gst_bus_peek                        (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 397 <p>
 398 Peek the message on the top of the bus' queue. The message will remain
 399 on the bus' message queue. A reference is returned, and needs to be unreffed
 400 by the caller.
 401 </p>
 402 <div class="variablelist"><table border="0">
 403 <col align="left" valign="top">
 404 <tbody>
 405 <tr>
 406 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 407 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a>
 408 </td>
 409 </tr>
 410 <tr>
 411 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 412 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> that is on the bus, or NULL if the
 413 bus is empty.
 414 MT safe. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 415 </td>
 416 </tr>
 417 </tbody>
 418 </table></div>
 419 </div>
 420 <hr>
 421 <div class="refsect2">
 422 <a name="gst-bus-pop"></a><h3>gst_bus_pop ()</h3>
 423 <pre class="programlisting"><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        gst_bus_pop                         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 424 <p>
 425 Get a message from the bus.
 426 </p>
 427 <div class="variablelist"><table border="0">
 428 <col align="left" valign="top">
 429 <tbody>
 430 <tr>
 431 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 432 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to pop</td>
 433 </tr>
 434 <tr>
 435 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 436 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> that is on the bus, or NULL if the
 437 bus is empty. The message is taken from the bus and needs to be unreffed
 438 with <a class="link" href="gstreamer-GstMessage.html#gst-message-unref" title="gst_message_unref ()"><code class="function">gst_message_unref()</code></a> after usage.
 439 MT safe. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 440 </td>
 441 </tr>
 442 </tbody>
 443 </table></div>
 444 </div>
 445 <hr>
 446 <div class="refsect2">
 447 <a name="gst-bus-pop-filtered"></a><h3>gst_bus_pop_filtered ()</h3>
 448 <pre class="programlisting"><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        gst_bus_pop_filtered                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 449                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessageType" title="enum GstMessageType"><span class="type">GstMessageType</span></a> types</code></em>);</pre>
 450 <p>
 451 Get a message matching <em class="parameter"><code>type</code></em> from the bus.  Will discard all messages on
 452 the bus that do not match <em class="parameter"><code>type</code></em> and that have been posted before the first
 453 message that does match <em class="parameter"><code>type</code></em>.  If there is no message matching <em class="parameter"><code>type</code></em> on
 454 the bus, all messages will be discarded.
 455 </p>
 456 <div class="variablelist"><table border="0">
 457 <col align="left" valign="top">
 458 <tbody>
 459 <tr>
 460 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 461 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to pop</td>
 462 </tr>
 463 <tr>
 464 <td><p><span class="term"><em class="parameter"><code>types</code></em> :</span></p></td>
 465 <td>message types to take into account</td>
 466 </tr>
 467 <tr>
 468 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 469 <td>the next <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> matching <em class="parameter"><code>type</code></em> that is on
 470 the bus, or NULL if the bus is empty or there is no message matching
 471 <em class="parameter"><code>type</code></em>. The message is taken from the bus and needs to be unreffed with
 472 <a class="link" href="gstreamer-GstMessage.html#gst-message-unref" title="gst_message_unref ()"><code class="function">gst_message_unref()</code></a> after usage.
 473 MT safe. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 474 </td>
 475 </tr>
 476 </tbody>
 477 </table></div>
 478 <p class="since">Since 0.10.15</p>
 479 </div>
 480 <hr>
 481 <div class="refsect2">
 482 <a name="gst-bus-timed-pop"></a><h3>gst_bus_timed_pop ()</h3>
 483 <pre class="programlisting"><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        gst_bus_timed_pop                   (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 484                                                          <em class="parameter"><code><a class="link" href="GstClock.html#GstClockTime" title="GstClockTime"><span class="type">GstClockTime</span></a> timeout</code></em>);</pre>
 485 <p>
 486 Get a message from the bus, waiting up to the specified timeout.
 487 </p>
 488 <p>
 489 If <em class="parameter"><code>timeout</code></em> is 0, this function behaves like <a class="link" href="GstBus.html#gst-bus-pop" title="gst_bus_pop ()"><code class="function">gst_bus_pop()</code></a>. If <em class="parameter"><code>timeout</code></em> is
 490 <a class="link" href="GstClock.html#GST-CLOCK-TIME-NONE:CAPS" title="GST_CLOCK_TIME_NONE"><span class="type">GST_CLOCK_TIME_NONE</span></a>, this function will block forever until a message was
 491 posted on the bus.
 492 </p>
 493 <div class="variablelist"><table border="0">
 494 <col align="left" valign="top">
 495 <tbody>
 496 <tr>
 497 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 498 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to pop</td>
 499 </tr>
 500 <tr>
 501 <td><p><span class="term"><em class="parameter"><code>timeout</code></em> :</span></p></td>
 502 <td>a timeout</td>
 503 </tr>
 504 <tr>
 505 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 506 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> that is on the bus after the
 507 specified timeout or NULL if the bus is empty after the timeout expired.
 508 The message is taken from the bus and needs to be unreffed with
 509 <a class="link" href="gstreamer-GstMessage.html#gst-message-unref" title="gst_message_unref ()"><code class="function">gst_message_unref()</code></a> after usage.
 510 MT safe. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 511 </td>
 512 </tr>
 513 </tbody>
 514 </table></div>
 515 <p class="since">Since 0.10.12</p>
 516 </div>
 517 <hr>
 518 <div class="refsect2">
 519 <a name="gst-bus-timed-pop-filtered"></a><h3>gst_bus_timed_pop_filtered ()</h3>
 520 <pre class="programlisting"><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        gst_bus_timed_pop_filtered          (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 521                                                          <em class="parameter"><code><a class="link" href="GstClock.html#GstClockTime" title="GstClockTime"><span class="type">GstClockTime</span></a> timeout</code></em>,
 522                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessageType" title="enum GstMessageType"><span class="type">GstMessageType</span></a> types</code></em>);</pre>
 523 <p>
 524 Get a message from the bus whose type matches the message type mask <em class="parameter"><code>types</code></em>,
 525 waiting up to the specified timeout (and discarding any messages that do not
 526 match the mask provided).
 527 </p>
 528 <p>
 529 If <em class="parameter"><code>timeout</code></em> is 0, this function behaves like <a class="link" href="GstBus.html#gst-bus-pop-filtered" title="gst_bus_pop_filtered ()"><code class="function">gst_bus_pop_filtered()</code></a>. If
 530 <em class="parameter"><code>timeout</code></em> is <a class="link" href="GstClock.html#GST-CLOCK-TIME-NONE:CAPS" title="GST_CLOCK_TIME_NONE"><span class="type">GST_CLOCK_TIME_NONE</span></a>, this function will block forever until a
 531 matching message was posted on the bus.
 532 </p>
 533 <div class="variablelist"><table border="0">
 534 <col align="left" valign="top">
 535 <tbody>
 536 <tr>
 537 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 538 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to pop from</td>
 539 </tr>
 540 <tr>
 541 <td><p><span class="term"><em class="parameter"><code>timeout</code></em> :</span></p></td>
 542 <td>a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever</td>
 543 </tr>
 544 <tr>
 545 <td><p><span class="term"><em class="parameter"><code>types</code></em> :</span></p></td>
 546 <td>message types to take into account, GST_MESSAGE_ANY for any type</td>
 547 </tr>
 548 <tr>
 549 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 550 <td>a <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> matching the filter in <em class="parameter"><code>types</code></em>,
 551 or NULL if no matching message was found on the bus until the timeout
 552 expired. The message is taken from the bus and needs to be unreffed
 553 with <a class="link" href="gstreamer-GstMessage.html#gst-message-unref" title="gst_message_unref ()"><code class="function">gst_message_unref()</code></a> after usage.
 554 MT safe. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 555 </td>
 556 </tr>
 557 </tbody>
 558 </table></div>
 559 <p class="since">Since 0.10.15</p>
 560 </div>
 561 <hr>
 562 <div class="refsect2">
 563 <a name="gst-bus-set-flushing"></a><h3>gst_bus_set_flushing ()</h3>
 564 <pre class="programlisting"><span class="returnvalue">void</span>                gst_bus_set_flushing                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 565                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> flushing</code></em>);</pre>
 566 <p>
 567 If <em class="parameter"><code>flushing</code></em>, flush out and unref any messages queued in the bus. Releases
 568 references to the message origin objects. Will flush future messages until
 569 <a class="link" href="GstBus.html#gst-bus-set-flushing" title="gst_bus_set_flushing ()"><code class="function">gst_bus_set_flushing()</code></a> sets <em class="parameter"><code>flushing</code></em> to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><span class="type">FALSE</span></a>.
 570 </p>
 571 <p>
 572 MT safe.
 573 </p>
 574 <div class="variablelist"><table border="0">
 575 <col align="left" valign="top">
 576 <tbody>
 577 <tr>
 578 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 579 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a>
 580 </td>
 581 </tr>
 582 <tr>
 583 <td><p><span class="term"><em class="parameter"><code>flushing</code></em> :</span></p></td>
 584 <td>whether or not to flush the bus</td>
 585 </tr>
 586 </tbody>
 587 </table></div>
 588 </div>
 589 <hr>
 590 <div class="refsect2">
 591 <a name="gst-bus-set-sync-handler"></a><h3>gst_bus_set_sync_handler ()</h3>
 592 <pre class="programlisting"><span class="returnvalue">void</span>                gst_bus_set_sync_handler            (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 593                                                          <em class="parameter"><code><a class="link" href="GstBus.html#GstBusSyncHandler" title="GstBusSyncHandler ()"><span class="type">GstBusSyncHandler</span></a> func</code></em>,
 594                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 595 <p>
 596 Sets the synchronous handler on the bus. The function will be called
 597 every time a new message is posted on the bus. Note that the function
 598 will be called in the same thread context as the posting object. This
 599 function is usually only called by the creator of the bus. Applications
 600 should handle messages asynchronously using the gst_bus watch and poll
 601 functions.
 602 </p>
 603 <p>
 604 You cannot replace an existing sync_handler. You can pass NULL to this
 605 function, which will clear the existing handler.
 606 </p>
 607 <div class="variablelist"><table border="0">
 608 <col align="left" valign="top">
 609 <tbody>
 610 <tr>
 611 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 612 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to install the handler on</td>
 613 </tr>
 614 <tr>
 615 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 616 <td>The handler function to install</td>
 617 </tr>
 618 <tr>
 619 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 620 <td>User data that will be sent to the handler function.</td>
 621 </tr>
 622 </tbody>
 623 </table></div>
 624 </div>
 625 <hr>
 626 <div class="refsect2">
 627 <a name="gst-bus-sync-signal-handler"></a><h3>gst_bus_sync_signal_handler ()</h3>
 628 <pre class="programlisting"><a class="link" href="GstBus.html#GstBusSyncReply" title="enum GstBusSyncReply"><span class="returnvalue">GstBusSyncReply</span></a>     gst_bus_sync_signal_handler         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 629                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
 630                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 631 <p>
 632 A helper GstBusSyncHandler that can be used to convert all synchronous
 633 messages into signals.
 634 </p>
 635 <div class="variablelist"><table border="0">
 636 <col align="left" valign="top">
 637 <tbody>
 638 <tr>
 639 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 640 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a>
 641 </td>
 642 </tr>
 643 <tr>
 644 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
 645 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> received</td>
 646 </tr>
 647 <tr>
 648 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 649 <td>user data</td>
 650 </tr>
 651 <tr>
 652 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 653 <td>GST_BUS_PASS</td>
 654 </tr>
 655 </tbody>
 656 </table></div>
 657 </div>
 658 <hr>
 659 <div class="refsect2">
 660 <a name="gst-bus-create-watch"></a><h3>gst_bus_create_watch ()</h3>
 661 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> *           gst_bus_create_watch                (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 662 <p>
 663 Create watch for this bus. The GSource will be dispatched whenever
 664 a message is on the bus. After the GSource is dispatched, the
 665 message is popped off the bus and unreffed.
 666 </p>
 667 <div class="variablelist"><table border="0">
 668 <col align="left" valign="top">
 669 <tbody>
 670 <tr>
 671 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 672 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to create the watch for</td>
 673 </tr>
 674 <tr>
 675 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 676 <td>a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> that can be added to a mainloop. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 677 </td>
 678 </tr>
 679 </tbody>
 680 </table></div>
 681 </div>
 682 <hr>
 683 <div class="refsect2">
 684 <a name="gst-bus-add-watch-full"></a><h3>gst_bus_add_watch_full ()</h3>
 685 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               gst_bus_add_watch_full              (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 686                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
 687                                                          <em class="parameter"><code><a class="link" href="GstBus.html#GstBusFunc" title="GstBusFunc ()"><span class="type">GstBusFunc</span></a> func</code></em>,
 688                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
 689                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
 690 <p>
 691 Adds a bus watch to the default main context with the given <em class="parameter"><code>priority</code></em> (e.g.
 692 <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>). Since 0.10.33 it is also possible to use a non-default
 693 main context set up using <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default"><code class="function">g_main_context_push_thread_default()</code></a> (before
 694 one had to create a bus watch source and attach it to the desired main
 695 context 'manually').
 696 </p>
 697 <p>
 698 This function is used to receive asynchronous messages in the main loop.
 699 There can only be a single bus watch per bus, you must remove it before you
 700 can set a new one.
 701 </p>
 702 <p>
 703 When <em class="parameter"><code>func</code></em> is called, the message belongs to the caller; if you want to
 704 keep a copy of it, call <a class="link" href="gstreamer-GstMessage.html#gst-message-ref" title="gst_message_ref ()"><code class="function">gst_message_ref()</code></a> before leaving <em class="parameter"><code>func</code></em>.
 705 </p>
 706 <p>
 707 The watch can be removed using <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-source-remove"><code class="function">g_source_remove()</code></a> or by returning FALSE
 708 from <em class="parameter"><code>func</code></em>.
 709 </p>
 710 <div class="variablelist"><table border="0">
 711 <col align="left" valign="top">
 712 <tbody>
 713 <tr>
 714 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 715 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to create the watch for.</td>
 716 </tr>
 717 <tr>
 718 <td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
 719 <td>The priority of the watch.</td>
 720 </tr>
 721 <tr>
 722 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 723 <td>A function to call when a message is received.</td>
 724 </tr>
 725 <tr>
 726 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 727 <td>user data passed to <em class="parameter"><code>func</code></em>.</td>
 728 </tr>
 729 <tr>
 730 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
 731 <td>the function to call when the source is removed.</td>
 732 </tr>
 733 <tr>
 734 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 735 <td>The event source id.
 736 MT safe.</td>
 737 </tr>
 738 </tbody>
 739 </table></div>
 740 </div>
 741 <hr>
 742 <div class="refsect2">
 743 <a name="gst-bus-add-watch"></a><h3>gst_bus_add_watch ()</h3>
 744 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               gst_bus_add_watch                   (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 745                                                          <em class="parameter"><code><a class="link" href="GstBus.html#GstBusFunc" title="GstBusFunc ()"><span class="type">GstBusFunc</span></a> func</code></em>,
 746                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 747 <p>
 748 Adds a bus watch to the default main context with the default priority
 749 (<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>). Since 0.10.33 it is also possible to use a non-default
 750 main context set up using <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default"><code class="function">g_main_context_push_thread_default()</code></a> (before
 751 one had to create a bus watch source and attach it to the desired main
 752 context 'manually').
 753 </p>
 754 <p>
 755 This function is used to receive asynchronous messages in the main loop.
 756 There can only be a single bus watch per bus, you must remove it before you
 757 can set a new one.
 758 </p>
 759 <p>
 760 The watch can be removed using <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-source-remove"><code class="function">g_source_remove()</code></a> or by returning FALSE
 761 from <em class="parameter"><code>func</code></em>.
 762 </p>
 763 <div class="variablelist"><table border="0">
 764 <col align="left" valign="top">
 765 <tbody>
 766 <tr>
 767 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 768 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> to create the watch for</td>
 769 </tr>
 770 <tr>
 771 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 772 <td>A function to call when a message is received.</td>
 773 </tr>
 774 <tr>
 775 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 776 <td>user data passed to <em class="parameter"><code>func</code></em>.</td>
 777 </tr>
 778 <tr>
 779 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 780 <td>The event source id.
 781 MT safe.</td>
 782 </tr>
 783 </tbody>
 784 </table></div>
 785 </div>
 786 <hr>
 787 <div class="refsect2">
 788 <a name="gst-bus-disable-sync-message-emission"></a><h3>gst_bus_disable_sync_message_emission ()</h3>
 789 <pre class="programlisting"><span class="returnvalue">void</span>                gst_bus_disable_sync_message_emission
 790                                                         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 791 <p>
 792 Instructs GStreamer to stop emitting the "sync-message" signal for this bus.
 793 See <a class="link" href="GstBus.html#gst-bus-enable-sync-message-emission" title="gst_bus_enable_sync_message_emission ()"><code class="function">gst_bus_enable_sync_message_emission()</code></a> for more information.
 794 </p>
 795 <p>
 796 In the event that multiple pieces of code have called
 797 <a class="link" href="GstBus.html#gst-bus-enable-sync-message-emission" title="gst_bus_enable_sync_message_emission ()"><code class="function">gst_bus_enable_sync_message_emission()</code></a>, the sync-message emissions will only
 798 be stopped after all calls to <a class="link" href="GstBus.html#gst-bus-enable-sync-message-emission" title="gst_bus_enable_sync_message_emission ()"><code class="function">gst_bus_enable_sync_message_emission()</code></a> were
 799 "cancelled" by calling this function. In this way the semantics are exactly
 800 the same as <a class="link" href="GstObject.html#gst-object-ref" title="gst_object_ref ()"><code class="function">gst_object_ref()</code></a> that which calls enable should also call
 801 disable.
 802 </p>
 803 <p>
 804 MT safe.
 805 </p>
 806 <div class="variablelist"><table border="0">
 807 <col align="left" valign="top">
 808 <tbody><tr>
 809 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 810 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> on which you previously called
 811 <a class="link" href="GstBus.html#gst-bus-enable-sync-message-emission" title="gst_bus_enable_sync_message_emission ()"><code class="function">gst_bus_enable_sync_message_emission()</code></a>
 812 </td>
 813 </tr></tbody>
 814 </table></div>
 815 </div>
 816 <hr>
 817 <div class="refsect2">
 818 <a name="gst-bus-enable-sync-message-emission"></a><h3>gst_bus_enable_sync_message_emission ()</h3>
 819 <pre class="programlisting"><span class="returnvalue">void</span>                gst_bus_enable_sync_message_emission
 820                                                         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 821 <p>
 822 Instructs GStreamer to emit the "sync-message" signal after running the bus's
 823 sync handler. This function is here so that code can ensure that they can
 824 synchronously receive messages without having to affect what the bin's sync
 825 handler is.
 826 </p>
 827 <p>
 828 This function may be called multiple times. To clean up, the caller is
 829 responsible for calling <a class="link" href="GstBus.html#gst-bus-disable-sync-message-emission" title="gst_bus_disable_sync_message_emission ()"><code class="function">gst_bus_disable_sync_message_emission()</code></a> as many times
 830 as this function is called.
 831 </p>
 832 <p>
 833 While this function looks similar to <a class="link" href="GstBus.html#gst-bus-add-signal-watch" title="gst_bus_add_signal_watch ()"><code class="function">gst_bus_add_signal_watch()</code></a>, it is not
 834 exactly the same -- this function enables <span class="emphasis"><em>synchronous</em></span> emission of
 835 signals when messages arrive; <a class="link" href="GstBus.html#gst-bus-add-signal-watch" title="gst_bus_add_signal_watch ()"><code class="function">gst_bus_add_signal_watch()</code></a> adds an idle callback
 836 to pop messages off the bus <span class="emphasis"><em>asynchronously</em></span>. The sync-message signal
 837 comes from the thread of whatever object posted the message; the "message"
 838 signal is marshalled to the main thread via the main loop.
 839 </p>
 840 <p>
 841 MT safe.
 842 </p>
 843 <div class="variablelist"><table border="0">
 844 <col align="left" valign="top">
 845 <tbody><tr>
 846 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 847 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> on which you want to receive the "sync-message" signal</td>
 848 </tr></tbody>
 849 </table></div>
 850 </div>
 851 <hr>
 852 <div class="refsect2">
 853 <a name="gst-bus-async-signal-func"></a><h3>gst_bus_async_signal_func ()</h3>
 854 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            gst_bus_async_signal_func           (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 855                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message</code></em>,
 856                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 857 <p>
 858 A helper <a class="link" href="GstBus.html#GstBusFunc" title="GstBusFunc ()"><span class="type">GstBusFunc</span></a> that can be used to convert all asynchronous messages
 859 into signals.
 860 </p>
 861 <div class="variablelist"><table border="0">
 862 <col align="left" valign="top">
 863 <tbody>
 864 <tr>
 865 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 866 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a>
 867 </td>
 868 </tr>
 869 <tr>
 870 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
 871 <td>the <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> received</td>
 872 </tr>
 873 <tr>
 874 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 875 <td>user data</td>
 876 </tr>
 877 <tr>
 878 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 879 <td>TRUE</td>
 880 </tr>
 881 </tbody>
 882 </table></div>
 883 </div>
 884 <hr>
 885 <div class="refsect2">
 886 <a name="gst-bus-add-signal-watch"></a><h3>gst_bus_add_signal_watch ()</h3>
 887 <pre class="programlisting"><span class="returnvalue">void</span>                gst_bus_add_signal_watch            (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 888 <p>
 889 Adds a bus signal watch to the default main context with the default priority
 890 (<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>). Since 0.10.33 it is also possible to use a non-default
 891 main context set up using <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default"><code class="function">g_main_context_push_thread_default()</code></a> (before
 892 one had to create a bus watch source and attach it to the desired main
 893 context 'manually').
 894 </p>
 895 <p>
 896 After calling this statement, the bus will emit the "message" signal for each
 897 message posted on the bus.
 898 </p>
 899 <p>
 900 This function may be called multiple times. To clean up, the caller is
 901 responsible for calling <a class="link" href="GstBus.html#gst-bus-remove-signal-watch" title="gst_bus_remove_signal_watch ()"><code class="function">gst_bus_remove_signal_watch()</code></a> as many times as this
 902 function is called.
 903 </p>
 904 <p>
 905 MT safe.
 906 </p>
 907 <div class="variablelist"><table border="0">
 908 <col align="left" valign="top">
 909 <tbody><tr>
 910 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 911 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> on which you want to receive the "message" signal</td>
 912 </tr></tbody>
 913 </table></div>
 914 </div>
 915 <hr>
 916 <div class="refsect2">
 917 <a name="gst-bus-add-signal-watch-full"></a><h3>gst_bus_add_signal_watch_full ()</h3>
 918 <pre class="programlisting"><span class="returnvalue">void</span>                gst_bus_add_signal_watch_full       (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 919                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>);</pre>
 920 <p>
 921 Adds a bus signal watch to the default main context with the given <em class="parameter"><code>priority</code></em>
 922 (e.g. <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>). Since 0.10.33 it is also possible to use a
 923 non-default main context set up using <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default"><code class="function">g_main_context_push_thread_default()</code></a>
 924 (before one had to create a bus watch source and attach it to the desired
 925 main context 'manually').
 926 </p>
 927 <p>
 928 After calling this statement, the bus will emit the "message" signal for each
 929 message posted on the bus when the main loop is running.
 930 </p>
 931 <p>
 932 This function may be called multiple times. To clean up, the caller is
 933 responsible for calling <a class="link" href="GstBus.html#gst-bus-remove-signal-watch" title="gst_bus_remove_signal_watch ()"><code class="function">gst_bus_remove_signal_watch()</code></a> as many times as this
 934 function is called.
 935 </p>
 936 <p>
 937 There can only be a single bus watch per bus, you must remove any signal
 938 watch before you can set another type of watch.
 939 </p>
 940 <p>
 941 MT safe.
 942 </p>
 943 <div class="variablelist"><table border="0">
 944 <col align="left" valign="top">
 945 <tbody>
 946 <tr>
 947 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 948 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> on which you want to receive the "message" signal</td>
 949 </tr>
 950 <tr>
 951 <td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
 952 <td>The priority of the watch.</td>
 953 </tr>
 954 </tbody>
 955 </table></div>
 956 </div>
 957 <hr>
 958 <div class="refsect2">
 959 <a name="gst-bus-remove-signal-watch"></a><h3>gst_bus_remove_signal_watch ()</h3>
 960 <pre class="programlisting"><span class="returnvalue">void</span>                gst_bus_remove_signal_watch         (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>);</pre>
 961 <p>
 962 Removes a signal watch previously added with <a class="link" href="GstBus.html#gst-bus-add-signal-watch" title="gst_bus_add_signal_watch ()"><code class="function">gst_bus_add_signal_watch()</code></a>.
 963 </p>
 964 <p>
 965 MT safe.
 966 </p>
 967 <div class="variablelist"><table border="0">
 968 <col align="left" valign="top">
 969 <tbody><tr>
 970 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
 971 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> you previously added a signal watch to</td>
 972 </tr></tbody>
 973 </table></div>
 974 </div>
 975 <hr>
 976 <div class="refsect2">
 977 <a name="gst-bus-poll"></a><h3>gst_bus_poll ()</h3>
 978 <pre class="programlisting"><a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="returnvalue">GstMessage</span></a> *        gst_bus_poll                        (<em class="parameter"><code><a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a> *bus</code></em>,
 979                                                          <em class="parameter"><code><a class="link" href="gstreamer-GstMessage.html#GstMessageType" title="enum GstMessageType"><span class="type">GstMessageType</span></a> events</code></em>,
 980                                                          <em class="parameter"><code><a class="link" href="GstClock.html#GstClockTimeDiff" title="GstClockTimeDiff"><span class="type">GstClockTimeDiff</span></a> timeout</code></em>);</pre>
 981 <p>
 982 Poll the bus for messages. Will block while waiting for messages to come.
 983 You can specify a maximum time to poll with the <em class="parameter"><code>timeout</code></em> parameter. If
 984 <em class="parameter"><code>timeout</code></em> is negative, this function will block indefinitely.
 985 </p>
 986 <p>
 987 All messages not in <em class="parameter"><code>events</code></em> will be popped off the bus and will be ignored.
 988 </p>
 989 <p>
 990 Because poll is implemented using the "message" signal enabled by
 991 <a class="link" href="GstBus.html#gst-bus-add-signal-watch" title="gst_bus_add_signal_watch ()"><code class="function">gst_bus_add_signal_watch()</code></a>, calling <a class="link" href="GstBus.html#gst-bus-poll" title="gst_bus_poll ()"><code class="function">gst_bus_poll()</code></a> will cause the "message"
 992 signal to be emitted for every message that poll sees. Thus a "message"
 993 signal handler will see the same messages that this function sees -- neither
 994 will steal messages from the other.
 995 </p>
 996 <p>
 997 This function will run a main loop from the default main context when
 998 polling.
 999 </p>
1000 <p>
1001 You should never use this function, since it is pure evil. This is
1002 especially true for GUI applications based on Gtk+ or Qt, but also for any
1003 other non-trivial application that uses the GLib main loop. As this function
1004 runs a GLib main loop, any callback attached to the default GLib main
1005 context may be invoked. This could be timeouts, GUI events, I/O events etc.;
1006 even if <a class="link" href="GstBus.html#gst-bus-poll" title="gst_bus_poll ()"><code class="function">gst_bus_poll()</code></a> is called with a 0 timeout. Any of these callbacks
1007 may do things you do not expect, e.g. destroy the main application window or
1008 some other resource; change other application state; display a dialog and
1009 run another main loop until the user clicks it away. In short, using this
1010 function may add a lot of complexity to your code through unexpected
1011 re-entrancy and unexpected changes to your application's state.
1012 </p>
1013 <p>
1014 For 0 timeouts use <a class="link" href="GstBus.html#gst-bus-pop-filtered" title="gst_bus_pop_filtered ()"><code class="function">gst_bus_pop_filtered()</code></a> instead of this function; for
1015 other short timeouts use <a class="link" href="GstBus.html#gst-bus-timed-pop-filtered" title="gst_bus_timed_pop_filtered ()"><code class="function">gst_bus_timed_pop_filtered()</code></a>; everything else is
1016 better handled by setting up an asynchronous bus watch and doing things
1017 from there.
1018 </p>
1019 <div class="variablelist"><table border="0">
1020 <col align="left" valign="top">
1021 <tbody>
1022 <tr>
1023 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
1024 <td>a <a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a>
1025 </td>
1026 </tr>
1027 <tr>
1028 <td><p><span class="term"><em class="parameter"><code>events</code></em> :</span></p></td>
1029 <td>a mask of <a class="link" href="gstreamer-GstMessage.html#GstMessageType" title="enum GstMessageType"><span class="type">GstMessageType</span></a>, representing the set of message types to
1030 poll for.</td>
1031 </tr>
1032 <tr>
1033 <td><p><span class="term"><em class="parameter"><code>timeout</code></em> :</span></p></td>
1034 <td>the poll timeout, as a <a class="link" href="GstClock.html#GstClockTimeDiff" title="GstClockTimeDiff"><span class="type">GstClockTimeDiff</span></a>, or -1 to poll
1035 indefinitely.</td>
1036 </tr>
1037 <tr>
1038 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1039 <td>the message that was received, or NULL if the
1040 poll timed out. The message is taken from the bus and needs to be
1041 unreffed with <a class="link" href="gstreamer-GstMessage.html#gst-message-unref" title="gst_message_unref ()"><code class="function">gst_message_unref()</code></a> after usage. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
1042 </td>
1043 </tr>
1044 </tbody>
1045 </table></div>
1046 </div>
1047 </div>
1048 <div class="refsect1">
1049 <a name="GstBus.signal-details"></a><h2>Signal Details</h2>
1050 <div class="refsect2">
1051 <a name="GstBus-message"></a><h3>The <code class="literal">"message"</code> signal</h3>
1052 <pre class="programlisting"><span class="returnvalue">void</span>                user_function                      (<a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a>     *bus,
1053                                                         <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message,
1054                                                         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>    user_data)      : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-DETAILED:CAPS"><code class="literal">Has Details</code></a></pre>
1055 <p>
1056 A message has been posted on the bus. This signal is emitted from a
1057 GSource added to the mainloop. this signal will only be emitted when
1058 there is a mainloop running.
1059 </p>
1060 <div class="variablelist"><table border="0">
1061 <col align="left" valign="top">
1062 <tbody>
1063 <tr>
1064 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
1065 <td>the object which received the signal</td>
1066 </tr>
1067 <tr>
1068 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
1069 <td>the message that has been posted asynchronously</td>
1070 </tr>
1071 <tr>
1072 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
1073 <td>user data set when the signal handler was connected.</td>
1074 </tr>
1075 </tbody>
1076 </table></div>
1077 </div>
1078 <hr>
1079 <div class="refsect2">
1080 <a name="GstBus-sync-message"></a><h3>The <code class="literal">"sync-message"</code> signal</h3>
1081 <pre class="programlisting"><span class="returnvalue">void</span>                user_function                      (<a class="link" href="GstBus.html" title="GstBus"><span class="type">GstBus</span></a>     *bus,
1082                                                         <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a> *message,
1083                                                         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>    user_data)      : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-DETAILED:CAPS"><code class="literal">Has Details</code></a></pre>
1084 <p>
1085 A message has been posted on the bus. This signal is emitted from the
1086 thread that posted the message so one has to be careful with locking.
1087 </p>
1088 <p>
1089 This signal will not be emitted by default, you have to set up
1090 <a class="link" href="GstBus.html#gst-bus-sync-signal-handler" title="gst_bus_sync_signal_handler ()"><code class="function">gst_bus_sync_signal_handler()</code></a> as a sync handler if you want this
1091 signal to be emitted when a message is posted on the bus, like this:
1092 </p>
1093 <pre class="programlisting">
1094 gst_bus_set_sync_handler (bus, gst_bus_sync_signal_handler, yourdata);
1095 </pre>
1096 <p>
1097 </p>
1098 <div class="variablelist"><table border="0">
1099 <col align="left" valign="top">
1100 <tbody>
1101 <tr>
1102 <td><p><span class="term"><em class="parameter"><code>bus</code></em> :</span></p></td>
1103 <td>the object which received the signal</td>
1104 </tr>
1105 <tr>
1106 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
1107 <td>the message that has been posted synchronously</td>
1108 </tr>
1109 <tr>
1110 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
1111 <td>user data set when the signal handler was connected.</td>
1112 </tr>
1113 </tbody>
1114 </table></div>
1115 </div>
1116 </div>
1117 <div class="refsect1">
1118 <a name="GstBus.see-also"></a><h2>See Also</h2>
1119 <a class="link" href="gstreamer-GstMessage.html#GstMessage" title="struct GstMessage"><span class="type">GstMessage</span></a>, <a class="link" href="GstElement.html" title="GstElement"><span class="type">GstElement</span></a>
1120 </div>
1121 </div>
1122 <div class="footer">
1123 <hr>
1124           Generated by GTK-Doc V1.18</div>
1125 </body>
1126 </html>