# Gst::Bus Class Reference

A class that encompasses the GStreamer asynchronous message bus subsystem. More...

Inherits Gst::Object.

Collaboration diagram for Gst::Bus:
[legend]

List of all members.

## Public Types

typedef sigc::slot< bool, const Glib::RefPtr< Gst::Bus > &, const Glib::RefPtr < Gst::Message >& > | SlotMessage
| For example, bool on_bus_message(const Glib::RefPtr<Gst::Bus>& bus, const Glib::RefPtr<Gst::Message>& message);.
typedef sigc::slot < BusSyncReply, const Glib::RefPtr< Gst::Bus > &, const Glib::RefPtr < Gst::Message >& > | SlotMessageSync
| For example, BusSyncReply on_bus_sync_message(const Glib::RefPtr<Gst::Bus>& bus, const Glib::RefPtr<Gst::Message>& message);.

## Public Member Functions

virtual | ~Bus ()
GstBus* | gobj ()
| Provides access to the underlying C GObject.
const GstBus* | gobj () const
| Provides access to the underlying C GObject.
GstBus* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
bool | post (const Glib::RefPtr< Gst::Message >& message)
| Post a message on the given bus.
bool | have_pending () const
| Check if there are pending messages on the bus that should be handled.
Glib::RefPtr< Gst::Message > | peek ()
| Peek the message on the top of the bus' queue.
Glib::RefPtr< const Gst::Message > | peek () const
| Peek the message on the top of the bus' queue.
Glib::RefPtr< Gst::Message > | pop ()
| Get a message from the bus.
Glib::RefPtr< Gst::Message > | pop (MessageType message_type)
| Get a message matching type from the bus.
Glib::RefPtr< Gst::Message > | pop (ClockTime timeout)
| Get a message from the bus, waiting up to the specified timeout.
Glib::RefPtr< Gst::Message > | pop (ClockTime timeout, MessageType message_type)
| Get a message from the bus whose type matches the message type mask types, waiting up to the specified timeout (and discarding any messages that do not match the mask provided).
void | set_flushing (bool flushing=true)
| If flushing, flush out and unref any messages queued in the bus.
guint | add_watch (const SlotMessage& slot, int priority=Glib::PRIORITY_DEFAULT)
| Adds a bus watch to the default main context with the given priority.
bool | remove_watch (guint watch_id)
| Removes bus watch with event source id from main context.
void | set_sync_handler (const SlotMessageSync& slot)
| Sets the synchronous handler on the bus.
void | disable_sync_message_emission ()
| Instructs GStreamer to stop emitting the "sync-message" signal for this bus.
void | enable_sync_message_emission ()
| Instructs GStreamer to emit the "sync-message" signal after running the bus's sync handler.
void | add_signal_watch (int priority=Glib::PRIORITY_DEFAULT)
| Adds a bus signal watch to the default main context with the given priority (e.g. PRIORITY_DEFAULT).
void | remove_signal_watch ()
| Removes a signal watch previously added with add_signal_watch().
Glib::RefPtr< Gst::Message > | poll (MessageType message_type, ClockTimeDiff timeout)
| Poll the bus for messages.
Glib::SignalProxy1< void, const Glib::RefPtr < Gst::Message >& > | signal_message ()
| A message has been posted on the bus.
Glib::SignalProxy1< void, const Glib::RefPtr < Gst::Message >& > | signal_sync_message ()
| A message has been posted on the bus.

## Static Public Member Functions

static Glib::RefPtr< Bus > | create ()
| Creates a new Gst::Bus instance.

## Protected Member Functions

| Bus ()
virtual void | on_message (const Glib::RefPtr< Gst::Message >& message)
virtual void | on_sync_message (const Glib::RefPtr< Gst::Message >& message)

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gst::Bus > | wrap (GstBus* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

A class that encompasses the GStreamer asynchronous message bus subsystem.

The Gst::Bus is an object responsible for delivering Messages 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 Gst::Bus 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 Gst::Bus provides support for GSource based notifications. This makes it possible to handle the delivery in the glib mainloop.

TODO: Correct C API reference in following paragraph:

The GSource callback function gst_bus_async_signal_func() can be used to convert all bus messages into signal emissions.

A message is posted on the bus with the post() method. With the peek() and pop() methods one can look at or retrieve a previously posted message.

The bus can be polled with the 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 function using add_watch(). This function will install a GSource in the default glib main loop and will deliver messages a short while after they have been posted. Note that the main loop should be running for the asynchronous callbacks.

It is also possible to get messages from the bus without any thread marshalling with the 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.

Every Gst::Pipeline has one bus.

Note that a Gst::Pipeline will set its bus into flushing state when changing from READY to NULL state.

Last reviewed on 2006-03-12 (0.10.5)

## Member Typedef Documentation

typedef sigc::slot< bool, const Glib::RefPtr<Gst::Bus>&, const Glib::RefPtr<Gst::Message>& > Gst::Bus::SlotMessage

For example, bool on_bus_message(const Glib::RefPtr<Gst::Bus>& bus, const Glib::RefPtr<Gst::Message>& message);.

The message function should return true if it wants to continue to receive messages, or false otherwise.

typedef sigc::slot< BusSyncReply, const Glib::RefPtr<Gst::Bus>&, const Glib::RefPtr<Gst::Message>& > Gst::Bus::SlotMessageSync

For example, BusSyncReply on_bus_sync_message(const Glib::RefPtr<Gst::Bus>& bus, const Glib::RefPtr<Gst::Message>& message);.

## Constructor & Destructor Documentation

virtual Gst::Bus::~Bus | ( |  | ) | `[virtual]`

Gst::Bus::Bus | ( |  | ) | `[protected]`

## Member Function Documentation

void Gst::Bus::add_signal_watch | ( | int | priority = `Glib::PRIORITY_DEFAULT` | ) |

Adds a bus signal watch to the default main context with the given priority (e.g. PRIORITY_DEFAULT).

After calling this statement, the bus will emit the "message" signal for each message posted on the bus when the main loop is running.

This function may be called multiple times. To clean up, the caller is responsible for calling remove_signal_watch() as many times as this function is called.

There can only be a single bus watch per bus, you most remove all signal watch before you can set another type of watch.

MT safe.

Parameters:

  | priority | The priority of the watch.

guint Gst::Bus::add_watch | ( | const SlotMessage & | slot,
|  | int | priority = `Glib::PRIORITY_DEFAULT` |
| ) |  |  |

Adds a bus watch to the default main context with the given priority.

The slot is used to receive asynchronous messages in the main loop.

The watch can be removed using remove_watch() or by returning false from slot.

Parameters:

  | slot | The slot to call when a message is received.
  | priority | The priority of the watch.

Returns:
  The event source id. MT safe.

static Glib::RefPtr<Bus> Gst::Bus::create | ( |  | ) | `[static]`

Creates a new Gst::Bus instance.

Returns:
  The new Gst::Bus instance.

void Gst::Bus::disable_sync_message_emission | ( |  | ) |

Instructs GStreamer to stop emitting the "sync-message" signal for this bus.

See enable_sync_message_emission() for more information.

In the event that multiple pieces of code have called enable_sync_message_emission(), the sync-message emissions will only be stopped after all calls to enable_sync_message_emission() were "cancelled" by calling this function. In this way the semantics are exactly the same as Gst::Object::ref() that which calls enable should also call disable.

MT safe.

void Gst::Bus::enable_sync_message_emission | ( |  | ) |

Instructs GStreamer to emit the "sync-message" signal after running the bus's sync handler.

This function is here so that code can ensure that they can synchronously receive messages without having to affect what the bin's sync handler is.

This function may be called multiple times. To clean up, the caller is responsible for calling disable_sync_message_emission() as many times as this function is called.

While this function looks similar to add_signal_watch(), it is not exactly the same -- this function enables <emphasis>synchronous</emphasis> emission of signals when messages arrive; add_signal_watch() adds an idle callback to pop messages off the bus <emphasis>asynchronously</emphasis>. The sync-message signal comes from the thread of whatever object posted the message; the "message" signal is marshalled to the main thread via the main loop.

MT safe.

const GstBus* Gst::Bus::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Gst::Object.

GstBus* Gst::Bus::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Gst::Object.

GstBus* Gst::Bus::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Reimplemented from Gst::Object.

bool Gst::Bus::have_pending | ( |  | ) | const

Check if there are pending messages on the bus that should be handled.

Returns:
  `true` if there are messages on the bus to be handled, `false` otherwise.

MT safe.

virtual void Gst::Bus::on_message | ( | const Glib::RefPtr< Gst::Message >& | message | ) | `[protected, virtual]`

virtual void Gst::Bus::on_sync_message | ( | const Glib::RefPtr< Gst::Message >& | message | ) | `[protected, virtual]`

Glib::RefPtr<const Gst::Message> Gst::Bus::peek | ( |  | ) | const

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.

Returns:
  The Gst::Message that is on the bus, or `0` if the bus is empty.

MT safe.

Glib::RefPtr<Gst::Message> Gst::Bus::peek | ( |  | ) |

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.

Returns:
  The Gst::Message that is on the bus, or `0` if the bus is empty.

MT safe.

Glib::RefPtr<Gst::Message> Gst::Bus::poll | ( | MessageType | message_type,
|  | ClockTimeDiff | timeout |
| ) |  |  |

Poll the bus for messages.

Will block while waiting for messages to come. You can specify a maximum time to poll with the timeout parameter. If timeout is negative, this function will block indefinitely.

All messages not in events will be popped off the bus and will be ignored.

Because poll is implemented using the "message" signal enabled by add_signal_watch(), calling poll() will cause the "message" signal to be emitted for every message that poll sees. Thus a "message" signal handler will see the same messages that this function sees -- neither will steal messages from the other.

This function will run a main loop from the default main context when polling.

You should never use this function, since it is pure evil. This is especially true for GUI applications based on Gtk+ or Qt, but also for any other non-trivial application that uses the GLib main loop. As this function runs a GLib main loop, any callback attached to the default GLib main context may be invoked. This could be timeouts, GUI events, I/O events etc.; even if poll() is called with a 0 timeout. Any of these callbacks may do things you do not expect, e.g. destroy the main application window or some other resource; change other application state; display a dialog and run another main loop until the user clicks it away. In short, using this function may add a lot of complexity to your code through unexpected re-entrancy and unexpected changes to your application's state.

For 0 timeouts use pop_filtered() instead of this function; for other short timeouts use timed_pop_filtered(); everything else is better handled by setting up an asynchronous bus watch and doing things from there.

Parameters:

  | events | A mask of Gst::MessageType, representing the set of message types to poll for.
  | timeout | The poll timeout, as a Gst::ClockTimeDiff, or -1 to poll indefinitely.

Returns:
  The message that was received, or `0` if the poll timed out. The message is taken from the bus and needs to be unreffed with gst_message_unref() after usage.

Glib::RefPtr<Gst::Message> Gst::Bus::pop | ( |  | ) |

Get a message from the bus.

Returns:
  The Gst::Message that is on the bus, or `0` if the bus is empty. The message is taken from the bus and needs to be unreffed with gst_message_unref() after usage.

MT safe.

Glib::RefPtr<Gst::Message> Gst::Bus::pop | ( | MessageType | message_type | ) |

Get a message matching type from the bus.

Will discard all messages on the bus that do not match type and that have been posted before the first message that does match type. If there is no message matching type on the bus, all messages will be discarded.

Since gstreamermm 0.10:
  .15

Parameters:

  | types | Message types to take into account.

Returns:
  The next Gst::Message matching type that is on the bus, or `0` if the bus is empty or there is no message matching type. The message is taken from the bus and needs to be unreffed with gst_message_unref() after usage.

MT safe.

Glib::RefPtr<Gst::Message> Gst::Bus::pop | ( | ClockTime | timeout | ) |

Get a message from the bus, waiting up to the specified timeout.

If timeout is 0, this function behaves like pop(). If timeout is Gst::CLOCK_TIME_NONE, this function will block forever until a message was posted on the bus.

Since gstreamermm 0.10:
  .12

Parameters:

  | timeout | A timeout.

Returns:
  The Gst::Message that is on the bus after the specified timeout or `0` if the bus is empty after the timeout expired. The message is taken from the bus and needs to be unreffed with gst_message_unref() after usage.

MT safe.

Glib::RefPtr<Gst::Message> Gst::Bus::pop | ( | ClockTime | timeout,
|  | MessageType | message_type |
| ) |  |  |

Get a message from the bus whose type matches the message type mask types, waiting up to the specified timeout (and discarding any messages that do not match the mask provided).

If timeout is 0, this function behaves like pop_filtered(). If timeout is Gst::CLOCK_TIME_NONE, this function will block forever until a matching message was posted on the bus.

Since gstreamermm 0.10:
  .15

Parameters:

  | timeout | A timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever.
  | types | Message types to take into account, GST_MESSAGE_ANY for any type.

Returns:
  A Gst::Message matching the filter in types, or `0` if no matching message was found on the bus until the timeout expired. The message is taken from the bus and needs to be unreffed with gst_message_unref() after usage.

MT safe.

bool Gst::Bus::post | ( | const Glib::RefPtr< Gst::Message >& | message | ) |

Post a message on the given bus.

Ownership of the message is taken by the bus.

Parameters:

  | message | The Gst::Message to post.

Returns:
  `true` if the message could be posted, `false` if the bus is flushing.

MT safe.

void Gst::Bus::remove_signal_watch | ( |  | ) |

Removes a signal watch previously added with add_signal_watch().

MT safe.

bool Gst::Bus::remove_watch | ( | guint | watch_id | ) |

Removes bus watch with event source id from main context.

Parameters:

  | The | event source id.

Returns:
  true if removal was succesful, false otherwise.

void Gst::Bus::set_flushing | ( | bool | flushing = `true` | ) |

If flushing, flush out and unref any messages queued in the bus.

Releases references to the message origin objects. Will flush future messages until set_flushing() sets flushing to #`false`.

MT safe.

Parameters:

  | flushing | Whether or not to flush the bus.

void Gst::Bus::set_sync_handler | ( | const SlotMessageSync & | slot | ) |

Sets the synchronous handler on the bus.

The slot 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 (synchronously). This function is usually only called by the creator of the bus. Applications should handle messages asynchronously using the watch and poll functions or enable the "sync-message" signal emission with enable_sync_message_emission().

Parameters:

  | slot | The handler slot to install.

Glib::SignalProxy1< void,const Glib::RefPtr<Gst::Message>& > Gst::Bus::signal_message | ( |  | ) |

A message has been posted on the bus.

This signal is emitted from a GSource added to the mainloop. this signal will only be emitted when there is a mainloop running.

Prototype:
  `void on_my_message(const Glib::RefPtr<Gst::Message>& message)`

Glib::SignalProxy1< void,const Glib::RefPtr<Gst::Message>& > Gst::Bus::signal_sync_message | ( |  | ) |

A message has been posted on the bus.

This signal is emitted from the thread that posted the message so one has to be careful with locking.

This signal will not be emitted by default, you have to enable it with enable_sync_message_emission().

Prototype:
  `void on_my_sync_message(const Glib::RefPtr<Gst::Message>& message)`

## Friends And Related Function Documentation

Glib::RefPtr< Gst::Bus > wrap | ( | GstBus * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- gstreamermm/bus.h