![]() |
![]() |
![]() |
GStreamer 0.9 Core Reference Manual | ![]() |
---|
GstBusGstBus — Asynchronous message bus subsystem |
#include <gst/gst.h> GstBus; enum GstBusFlags; enum GstBusSyncReply; gboolean (*GstBusHandler) (GstBus *bus, GstMessage *message, gpointer data); GstBusSyncReply (*GstBusSyncHandler) (GstBus *bus, GstMessage *message, gpointer data); GstBus* gst_bus_new (void); gboolean gst_bus_post (GstBus *bus, GstMessage *message); gboolean gst_bus_have_pending (GstBus *bus); GstMessage* gst_bus_peek (GstBus *bus); GstMessage* gst_bus_pop (GstBus *bus); void gst_bus_set_flushing (GstBus *bus, gboolean flushing); void gst_bus_set_sync_handler (GstBus *bus, GstBusSyncHandler func, gpointer data); GSource* gst_bus_create_watch (GstBus *bus); guint gst_bus_add_watch_full (GstBus *bus, gint priority, GstBusHandler handler, gpointer user_data, GDestroyNotify notify); guint gst_bus_add_watch (GstBus *bus, GstBusHandler handler, gpointer user_data); GstMessageType gst_bus_poll (GstBus *bus, GstMessageType events, GstClockTimeDiff timeout);
The GstBus is an object responsible for delivering GstMessages in a first-in first-out way from the streaming threads to the application.
Since the application typically only wants to deal with delivery of these messages from one thread, the GstBus will marshall the messages between different threads. This is important since the actual streaming of media is done in another thread than the application.
The GstBus provides support for GSource based notifications. This makes it possible to handle the delivery in the glib mainloop.
A message is posted on the bus with the gst_bus_post()
method. With the
gst_bus_peek()
and _pop()
methods one can look at or retrieve a previously
posted message.
The bus can be polled with the gst_bus_poll()
method. This methods blocks
up to the specified timeout value until one of the specified messages types
is posted on the bus. The application can then _pop()
the messages from the
bus to handle them.
Alternatively the application can register an asynchronous bus handler using
gst_bus_add_watch_full()
orgst_bus_add_watch()
. This handler will receive
messages a short while after they have been posted.
It is also possible to get messages from the bus without any thread
marshalling with the gst_bus_set_sync_handler()
method. This makes it
possible to react to a message in the same thread that posted the
message on the bus. This should only be used if the application is able
to deal with messages from different threads.
It is important to make sure that every message is popped from the bus at
some point in time. Otherwise it will be presented to the watches (GSource
elements) again and again. One way to implement it is having one watch with a
low priority (see gst_add_watch_full()
) that pops all messages.
Every GstPipeline has one bus.
typedef enum { GST_BUS_FLUSHING = GST_OBJECT_FLAG_LAST, GST_BUS_FLAG_LAST = GST_OBJECT_FLAG_LAST + 1 } GstBusFlags;
typedef enum { GST_BUS_DROP = 0, /* drop message */ GST_BUS_PASS = 1, /* pass message to async queue */ GST_BUS_ASYNC = 2, /* pass message to async queue, continue if message is handled */ } GstBusSyncReply;
gboolean (*GstBusHandler) (GstBus *bus, GstMessage *message, gpointer data);
Handler will be invoked asynchronously, after a new message has been injected
into the bus. Return TRUE
if the message has been handled. It will then be
taken from the bus and _unref()
'ed.
bus : |
the GstBus that sent the message |
message : |
|
data : |
user data that has been given, when registering the handler |
Returns : | TRUE if message should be taken from the bus
|
GstBusSyncReply (*GstBusSyncHandler) (GstBus *bus, GstMessage *message, gpointer data);
Handler will be invoked synchronously, when a new message has been injected into the bus.
bus : |
the GstBus that sent the message |
message : |
|
data : |
user data that has been given, when registering the handler |
Returns : | GstBusSyncReply stating what to do with the message |
GstBus* gst_bus_new (void);
Creates a new GstBuus instance.
Returns : | a new GstBus instance |
gboolean gst_bus_post (GstBus *bus, GstMessage *message);
Post a message on the given bus. Ownership of the message is taken by the bus.
bus : |
a GstBus to post on |
message : |
The GstMessage to post |
Returns : | TRUE if the message could be posted. MT safe. |
gboolean gst_bus_have_pending (GstBus *bus);
Check if there are pending messages on the bus that should be handled.
bus : |
a GstBus to check |
Returns : | TRUE if there are messages on the bus to be handled. MT safe. |
GstMessage* gst_bus_peek (GstBus *bus);
Peek the message on the top of the bus' queue. The message will remain on the bus' message queue. A reference is returned, and needs to be unreffed by the caller.
bus : |
a GstBus |
Returns : | The GstMessage that is on the bus, or NULL if the bus is empty. MT safe. |
GstMessage* gst_bus_pop (GstBus *bus);
Get a message from the bus.
bus : |
a GstBus to pop |
Returns : | The GstMessage that is on the bus, or NULL if the bus is empty. MT safe. |
void gst_bus_set_flushing (GstBus *bus, gboolean flushing);
If flushing
, flush out and unref any messages queued in the bus. Releases
references to the message origin objects. Will flush future messages until
gst_bus_set_flushing()
sets flushing
to FALSE.
MT safe.
bus : |
a GstBus |
flushing : |
whether or not to flush the bus |
void gst_bus_set_sync_handler (GstBus *bus, GstBusSyncHandler func, gpointer data);
Sets the synchronous handler on the bus. The function will be called every time a new message is posted on the bus. Note that the function will be called in the same thread context as the posting object. This function is usually only called by the creator of the bus. Applications should handle messages asynchronously using the gst_bus watch and poll functions.
bus : |
a GstBus to install the handler on |
func : |
The handler function to install |
data : |
User data that will be sent to the handler function. |
guint gst_bus_add_watch_full (GstBus *bus, gint priority, GstBusHandler handler, gpointer user_data, GDestroyNotify notify);
Adds the bus to the mainloop with the given priority. If the handler returns TRUE, the message will then be popped off the queue. When the handler is called, the message belongs to the caller; if you want to keep a copy of it, call gst_message_ref before leaving the handler.
bus : |
a GstBus to create the watch for. |
priority : |
The priority of the watch. |
handler : |
A function to call when a message is received. |
user_data : |
user data passed to handler .
|
notify : |
the function to call when the source is removed. |
Returns : | The event source id. MT safe. |
guint gst_bus_add_watch (GstBus *bus, GstBusHandler handler, gpointer user_data);
Adds the bus to the mainloop with the default priority.
bus : |
a GstBus to create the watch for |
handler : |
A function to call when a message is received. |
user_data : |
user data passed to handler .
|
Returns : | The event source id. MT safe. |
GstMessageType gst_bus_poll (GstBus *bus, GstMessageType events, GstClockTimeDiff timeout);
Poll the bus for events. Will block while waiting for events to come. You can
specify a maximum time to poll with the timeout
parameter. If timeout
is
negative, this function will block indefinitely.
This function will enter the default mainloop while polling.
bus : |
a GstBus |
events : |
a mask of GstMessageType, representing the set of message types to poll for. |
timeout : |
the poll timeout, as a GstClockTimeDiff, or -1 to poll indefinitely. |
Returns : | The type of the message that was received, or GST_MESSAGE_UNKNOWN if
the poll timed out. The message will remain in the bus queue; you will need
to gst_bus_pop() it off before entering gst_bus_poll() again.
|
<< GstBuffer | GstCaps >> |