GstBus

GstBus — Asynchronous message bus subsystem

Synopsis


#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);


Object Hierarchy


  GObject
   +----GstObject
         +----GstBus

Description

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.

Details

GstBus

typedef struct _GstBus GstBus;


enum GstBusFlags

typedef enum {
  GST_BUS_FLUSHING		= GST_OBJECT_FLAG_LAST,

  GST_BUS_FLAG_LAST		= GST_OBJECT_FLAG_LAST + 1
} GstBusFlags;


enum GstBusSyncReply

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;


GstBusHandler ()

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

GstBusSyncHandler ()

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

gst_bus_new ()

GstBus*     gst_bus_new                     (void);

Creates a new GstBuus instance.

Returns : a new GstBus instance

gst_bus_post ()

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.

gst_bus_have_pending ()

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.

gst_bus_peek ()

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.

gst_bus_pop ()

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.

gst_bus_set_flushing ()

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

gst_bus_set_sync_handler ()

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.

gst_bus_create_watch ()

GSource*    gst_bus_create_watch            (GstBus *bus);

Create watch for this bus.

bus : a GstBus to create the watch for
Returns : A GSource that can be added to a mainloop.

gst_bus_add_watch_full ()

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.

gst_bus_add_watch ()

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.

gst_bus_poll ()

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.

See Also

GstMessage, GstElement