Gst::Bus Class Reference

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

`#include <gstreamermm/bus.h>`

Inheritance diagram for Gst::Bus:
[legend]

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

## Public Member Functions

| Bus (Bus&& src) noexcept
Bus& | operator= (Bus&& src) noexcept
| ~Bus () noexcept override
GstBus* | gobj ()
| Provides access to the underlying C GObject. More...
const GstBus* | gobj () const
| Provides access to the underlying C GObject. More...
GstBus* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
bool | post (Glib::RefPtr< Gst::Message >&& message)
| Post a message on the given bus. More...
bool | have_pending () const
| Check if there are pending messages on the bus that should be handled. More...
Glib::RefPtr< Gst::Message > | peek ()
| Peek the message on the top of the bus' queue. More...
Glib::RefPtr< const Gst::Message > | peek () const
| Peek the message on the top of the bus' queue. More...
Glib::RefPtr< Gst::Message > | pop ()
| Get a message from the bus. More...
Glib::RefPtr< Gst::Message > | pop (MessageType message_type)
| Get a message matching type from the bus. More...
Glib::RefPtr< Gst::Message > | pop (ClockTime timeout)
| Get a message from the bus, waiting up to the specified timeout. More...
Glib::RefPtr< Gst::Message > | pop (ClockTime timeout, MessageType message_type)
| Get a message from the bus whose type matches the message type mask message_type, waiting up to the specified timeout (and discarding any messages that do not match the mask provided). More...
void | set_flushing (bool flushing=true)
| If flushing, flush out and unref any messages queued in the bus. More...
guint | add_watch (const SlotMessage& slot, int priority=Glib::PRIORITY_DEFAULT)
| Adds a bus watch to the default main context with the given priority. More...
bool | remove_watch (guint watch_id)
| Removes bus watch with event source id from main context. More...
void | set_sync_handler (const SlotMessageSync& slot)
| Sets the synchronous handler on the bus. More...
void | disable_sync_message_emission ()
| Instructs GStreamer to stop emitting the "sync-message" signal for this bus. More...
void | enable_sync_message_emission ()
| Instructs GStreamer to emit the "sync-message" signal after running the bus's sync handler. More...
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). More...
void | remove_signal_watch ()
| Removes a signal watch previously added with add_signal_watch(). More...
Glib::RefPtr< Gst::Message > | poll (MessageType message_type, ClockTime timeout)
| Poll the bus for messages. More...
Glib::SignalProxy< void, const Glib::RefPtr< Gst::Message >&> | signal_message ()
Glib::SignalProxy< void, const Glib::RefPtr< Gst::Message >&> | signal_sync_message ()
Public Member Functions inherited from Gst::Object
| Object (Object&& src) noexcept
Object& | operator= (Object&& src) noexcept
| ~Object () noexcept override
GstObject* | gobj ()
| Provides access to the underlying C GObject. More...
const GstObject* | gobj () const
| Provides access to the underlying C GObject. More...
GstObject* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
bool | is_element () const
bool | is_element_factory () const
bool | is_pad () const
bool | is_pad_template () const
bool | is_bin () const
guint32 | get_flags () const
| Returns the entire set of flags for the object. More...
bool | set_name (const Glib::ustring& name)
| Sets the name of object, or gives object a guaranteed unique name (if name is `nullptr`). More...
Glib::ustring | get_name () const
| Returns a copy of the name of object. More...
bool | set_parent (const Glib::RefPtr< Gst::Object >& parent)
| Sets the parent of object to parent. More...
Glib::RefPtr< Gst::Object > | get_parent ()
| Returns the parent of object. More...
Glib::RefPtr< const Gst::Object > | get_parent () const
| Returns the parent of object. More...
void | unparent ()
| Clear the parent of object, removing the associated reference. More...
void | set_control_rate (Gst::ClockTime control_rate)
| Change the control-rate for this object. More...
Gst::ClockTime | get_control_rate () const
| Obtain the control-rate for this object. More...
Gst::ClockTime | suggest_next_sync () const
| Returns a suggestion for timestamps where buffers should be split to get best controller results. More...
bool | sync_values (Gst::ClockTime timestamp)
| Sets the properties of the object, according to the Gst::ControlSources that (maybe) handle them and for the given timestamp. More...
void | set_control_bindings_disabled (bool disabled)
| This function is used to disable all controlled properties of the object for some time, i.e. sync_values() will do nothing. More...
bool | has_asctive_control_bindings () const
| Check if the object has an active controlled properties. More...
bool | has_ancestor (const Glib::RefPtr< const Gst::Object >& ancestor) const
| Check if object has an ancestor ancestor somewhere up in the hierarchy. More...
bool | has_as_ancestor (const Glib::RefPtr< Gst::Object >& ancestor) const
| Check if object has an ancestor ancestor somewhere up in the hierarchy. More...
bool | has_as_parent (const Glib::RefPtr< Gst::Object >& parent) const
| Check if parent is the parent of object. More...
Glib::ustring | get_path_string ()
| Generates a string describing the path of object in the object hierarchy. More...
Glib::PropertyProxy< Glib::ustring > | property_name ()
| The name of the object. More...
Glib::PropertyProxy_ReadOnly< Glib::ustring > | property_name () const
| The name of the object. More...
Glib::PropertyProxy< Glib::RefPtr< Gst::Object > > | property_parent ()
| The parent of the object. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gst::Object > > | property_parent () const
| The parent of the object. More...
Glib::SignalProxy< void, const Glib::RefPtr< Gst::Object >&, GParamSpec*> | signal_deep_notify ()
int | get_refcount () const

## Static Public Member Functions

static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static Glib::RefPtr< Bus > | create ()
| Creates a new Gst::Bus instance. More...
Static Public Member Functions inherited from Gst::Object
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static bool | check_uniqueness (const Glib::ListHandle< const Gst::Object >& list, const Glib::ustring& name)
| Checks to see if there is any object named name in list. More...

## Protected Member Functions

| Bus ()
virtual void | on_message (const Glib::RefPtr< Gst::Message >& message)
| This is a default handler for the signal signal_message(). More...
virtual void | on_sync_message (const Glib::RefPtr< Gst::Message >& message)
| This is a default handler for the signal signal_sync_message(). More...
Protected Member Functions inherited from Gst::Object
virtual void | on_deep_notify (const Glib::RefPtr< Gst::Object >& prop_object, GParamSpec* prop)
| This is a default handler for the signal signal_deep_notify(). More...

## 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. More...
Related Functions inherited from Gst::Object
Glib::RefPtr< Gst::Object > | wrap (GstObject* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## 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.

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 2016-05-16 (1.8.0)

## Member Typedef Documentation

## SlotMessage

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.

## SlotMessageSync

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

## Bus() [1/2]

Gst::Bus::Bus | ( | Bus&& | src | ) |

noexcept

## ~Bus()

Gst::Bus::~Bus | ( |  | ) |

override noexcept

## Bus() [2/2]

Gst::Bus::Bus | ( |  | ) |

protected

## Member Function Documentation

## add_signal_watch()

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).

It is also possible to use a non-default main context set up using Glib::main_context_push_thread_default() (before one had to create a bus watch source and attach it to the desired main context 'manually').

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 must remove any signal watch before you can set another type of watch.

MT safe.

Parameters

  priority | The priority of the watch.

## add_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.

## create()

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

static

Creates a new Gst::Bus instance.

Returns
  The new Gst::Bus instance.

## disable_sync_message_emission()

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.

## enable_sync_message_emission()

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 synchronous emission of signals when messages arrive; add_signal_watch() adds an idle callback to pop messages off the bus asynchronously. 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.

## get_type()

static GType Gst::Bus::get_type | ( |  | ) |

static

Get the GType for this class, for use with the underlying GObject type system.

## gobj() [1/2]

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

inline

Provides access to the underlying C GObject.

## gobj() [2/2]

const GstBus* Gst::Bus::gobj | ( |  | ) | const

inline

Provides access to the underlying C GObject.

## gobj_copy()

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.

## have_pending()

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.

## on_message()

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

protected virtual

This is a default handler for the signal signal_message().

## on_sync_message()

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

protected virtual

This is a default handler for the signal signal_sync_message().

## operator=()

Bus& Gst::Bus::operator= | ( | Bus&& | src | ) |

noexcept

## peek() [1/2]

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 `nullptr` if the bus is empty.

MT safe.

## peek() [2/2]

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 `nullptr` if the bus is empty.

MT safe.

## poll()

Glib::RefPtr<Gst::Message> Gst::Bus::poll | ( | MessageType | message_type,
|  | ClockTime | 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 message_type will be popped off the bus and will be ignored. It is not possible to use message enums beyond Gst::MESSAGE_EXTENDED in the message_type mask

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

  message_type | A mask of Gst::MessageType, representing the set of message types to poll for (note special handling of extended message types below).
  timeout | The poll timeout, as a Gst::ClockTime, or Gst::CLOCK_TIME_NONE to poll indefinitely.

Returns
  The message that was received, or `nullptr` if the poll timed out. The message is taken from the bus.

## pop() [1/4]

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

Get a message from the bus.

Returns
  The Gst::Message that is on the bus, or `nullptr` if the bus is empty. The message is taken from the bus.

MT safe.

## pop() [2/4]

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. It is not possible to use message enums beyond Gst::MESSAGE_EXTENDED in the events mask.

Parameters

  message_type | Message types to take into account.

Returns
  The next Gst::Message matching type that is on the bus, or `nullptr` if the bus is empty or there is no message matching type. The message is taken from the bus.

MT safe.

## pop() [3/4]

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.

Parameters

  timeout | A timeout.

Returns
  The Gst::Message that is on the bus after the specified timeout or `nullptr` if the bus is empty after the timeout expired. The message is taken from the bus.

MT safe.

## pop() [4/4]

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 message_type, 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.

Parameters

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

Returns
  A Gst::Message matching the filter in message_type, or `nullptr` if no matching message was found on the bus until the timeout expired. The message is taken from the bus.

MT safe.

## post()

bool Gst::Bus::post | ( | 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.

## remove_signal_watch()

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

Removes a signal watch previously added with add_signal_watch().

MT safe.

## remove_watch()

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

Removes bus watch with event source id from main context.

Parameters

  watch_id | The event source id.

Returns
  true if removal was succesful, false otherwise.

## set_flushing()

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.

## set_sync_handler()

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.

## signal_message()

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

Slot Prototype:
  `void on_my_message(const Glib::RefPtr<Gst::Message>& 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.

Parameters

  message | The message that has been posted asynchronously.

## signal_sync_message()

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

Slot Prototype:
  `void on_my_sync_message(const Glib::RefPtr<Gst::Message>& 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 call Gst::Bus::enable_sync_message_emission() before.

Parameters

  message | The message that has been posted synchronously.

## Friends And Related Function Documentation

## wrap()

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.