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

#include <gstreamermm/bus.h>

Inheritance diagram for Gst::Bus:

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

overridenoexcept

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

protectedvirtual

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 )

protectedvirtual

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

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.

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Functions

Detailed Description

Member Typedef Documentation

◆ SlotMessage

◆ SlotMessageSync

Constructor & Destructor Documentation

◆ Bus() [1/2]

◆ ~Bus()

◆ Bus() [2/2]

Member Function Documentation

◆ add_signal_watch()

◆ add_watch()

◆ create()

◆ disable_sync_message_emission()

◆ enable_sync_message_emission()

◆ get_type()

◆ gobj() [1/2]

◆ gobj() [2/2]

◆ gobj_copy()

◆ have_pending()

◆ on_message()

◆ on_sync_message()

◆ operator=()

◆ peek() [1/2]

◆ peek() [2/2]

◆ poll()

◆ pop() [1/4]

◆ pop() [2/4]

◆ pop() [3/4]

◆ pop() [4/4]

◆ post()

◆ remove_signal_watch()

◆ remove_watch()

◆ set_flushing()

◆ set_sync_handler()

◆ signal_message()

◆ signal_sync_message()

Friends And Related Function Documentation

◆ wrap()