gstreamermm  1.10.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gst::Bus Class Reference

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

#include <gstreamermm/bus.h>

Inheritance diagram for Gst::Bus:
Inheritance graph
[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
 
Busoperator= (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::Messagepeek ()
 Peek the message on the top of the bus' queue. More...
 
Glib::RefPtr< const Gst::Messagepeek () const
 Peek the message on the top of the bus' queue. More...
 
Glib::RefPtr< Gst::Messagepop ()
 Get a message from the bus. More...
 
Glib::RefPtr< Gst::Messagepop (MessageType message_type)
 Get a message matching type from the bus. More...
 
Glib::RefPtr< Gst::Messagepop (ClockTime timeout)
 Get a message from the bus, waiting up to the specified timeout. More...
 
Glib::RefPtr< Gst::Messagepop (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::Messagepoll (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
 
Objectoperator= (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::Objectget_parent ()
 Returns the parent of object. More...
 
Glib::RefPtr< const Gst::Objectget_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< Buscreate ()
 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::Buswrap (GstBus* 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
priorityThe 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
slotThe slot to call when a message is received.
priorityThe 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_typeA mask of Gst::MessageType, representing the set of message types to poll for (note special handling of extended message types below).
timeoutThe 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_typeMessage 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
timeoutA 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
timeoutA timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever.
message_typeMessage 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
messageThe 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_idThe 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
flushingWhether 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
slotThe 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
messageThe 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
messageThe 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
objectThe C instance.
take_copyFalse 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.