Next: , Previous: GstIterator, Up: Top


21 GstMessage

Lightweight objects to signal the application of pipeline events

21.1 Overview

Messages are implemented as a subclass of <gst-mini-object> with a generic <gst-structure> as the content. This allows for writing custom messages without requiring an API change while allowing a wide range of different types of messages.

Messages are posted by objects in the pipeline and are passed to the application using the <gst-bus>.

The basic use pattern of posting a message on a <gst-bus> is as follows:

     
        gst_bus_post (bus, gst_message_new_eos());
     

A <gst-element> usually posts messages on the bus provided by the parent container using gst-element-post-message.

Last reviewed on 2005-11-09 (0.9.4)

21.2 Usage

— Class: <gst-message>
— Function: gst-message-type-to-quark (self <gst-message-type*>)   (ret unsigned-int)

Get the unique quark for the given message type.

type
the message type
ret
the quark associated with the message type
— Function: gst-message-type-get-name (self <gst-message-type*>)   (ret mchars)

Get a printable name for the given message type. Do not modify or free.

type
the message type
ret
a reference to the static name of the message.
— Function: gst-message-get-structure (self <gst-message>)   (ret <gst-structure>)
— Method: get-structure

Access the structure of the message.

message
The <gst-message>.
ret
The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. MT safe.
— Function: gst-message-new-application (src <gst-object>) (structure <gst-structure>)   (ret <gst-message>)

Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy.

src
The object originating the message.
structure
The structure for the message. The message will take ownership of the structure.
ret
The new application message. MT safe.
— Function: gst-message-new-clock-provide (src <gst-object>) (clock <gst-clock>) (ready bool)   (ret <gst-message>)

Create a clock provide message. This message is posted whenever an element is ready to provide a clock or lost its ability to provide a clock (maybe because it paused or became EOS).

This message is mainly used internally to manage the clock selection.

src
The object originating the message.
clock
The clock it provides
ready
TRUE if the sender can provide a clock
ret
The new provide clock message. MT safe.
— Function: gst-message-new-clock-lost (src <gst-object>) (clock <gst-clock>)   (ret <gst-message>)

Create a clock lost message. This message is posted whenever the clock is not valid anymore.

If this message is posted by the pipeline, the pipeline will select a new clock again when it goes to PLAYING. It might therefore be needed to set the pipeline to PAUSED and PLAYING again.

src
The object originating the message.
clock
the clock that was lost
ret
The new clock lost message. MT safe.
— Function: gst-message-new-custom (type <gst-message-type>) (src <gst-object>) (structure <gst-structure>)   (ret <gst-message>)

Create a new custom-typed message. This can be used for anything not handled by other message-specific functions to pass a message to the app. The structure field can be NULL.

type
The <gst-message-type> to distinguish messages
src
The object originating the message.
structure
The structure for the message. The message will take ownership of the structure.
ret
The new message. MT safe.
— Function: gst-message-new-element (src <gst-object>) (structure <gst-structure>)   (ret <gst-message>)

Create a new element-specific message. This is meant as a generic way of allowing one-way communication from an element to an application, for example "the firewire cable was unplugged". The format of the message should be documented in the element's documentation. The structure field can be NULL.

src
The object originating the message.
structure
The structure for the message. The message will take ownership of the structure.
ret
The new element message. MT safe.
— Function: gst-message-new-error (src <gst-object>) (error <g-error*>) (debug mchars)   (ret <gst-message>)

Create a new error message. The message will copy error and debug. This message is posted by element when a fatal event occured. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline.

src
The object originating the message.
error
The GError for this message.
debug
A debugging string for something or other.
ret
The new error message. MT safe.
— Function: gst-message-new-new-clock (src <gst-object>) (clock <gst-clock>)   (ret <gst-message>)

Create a new clock message. This message is posted whenever the pipeline selectes a new clock for the pipeline.

src
The object originating the message.
clock
the new selected clock
ret
The new new clock message. MT safe.
— Function: gst-message-new-segment-done (src <gst-object>) (format <gst-format>) (position int64)   (ret <gst-message>)

Create a new segment done message. This message is posted by elements that finish playback of a segment as a result of a segment seek. This message is received by the application after all elements that posted a segment_start have posted the segment_done.

src
The object originating the message.
format
The format of the position being done
position
The position of the segment being done
ret
The new segment done message. MT safe.
— Function: gst-message-new-segment-start (src <gst-object>) (format <gst-format>) (position int64)   (ret <gst-message>)

Create a new segment message. This message is posted by elements that start playback of a segment as a result of a segment seek. This message is not received by the application but is used for maintenance reasons in container elements.

src
The object originating the message.
format
The format of the position being played
position
The position of the segment being played
ret
The new segment start message. MT safe.
— Function: gst-message-new-state-changed (src <gst-object>) (oldstate <gst-state>) (newstate <gst-state>) (pending <gst-state>)   (ret <gst-message>)

Create a state change message. This message is posted whenever an element changed its state.

src
the object originating the message
oldstate
the previous state
newstate
the new (current) state
pending
the pending (target) state
ret
The new state change message. MT safe.
— Function: gst-message-new-tag (src <gst-object>) (tag_list <gst-tag-list*>)   (ret <gst-message>)

Create a new tag message. The message will take ownership of the tag list. The message is posted by elements that discovered a new taglist.

src
The object originating the message.
tag-list
The tag list for the message.
ret
The new tag message. MT safe.
— Function: gst-message-new-warning (src <gst-object>) (error <g-error*>) (debug mchars)   (ret <gst-message>)

Create a new warning message. The message will make copies of error and debug.

src
The object originating the message.
error
The GError for this message.
debug
A debugging string for something or other.
ret
The new warning message. MT safe.
— Function: gst-message-new-duration (src <gst-object>) (format <gst-format>) (duration int64)   (ret <gst-message>)

Create a new duration message. This message is posted by elements that know the duration of a stream in a specific format. This message is received by bins and is used to calculate the total duration of a pipeline. Elements may post a duration message with a duration of GST_CLOCK_TIME_NONE to indicate that the duration has changed and the cached duration should be discarded. The new duration can then be retrieved via a query.

src
The object originating the message.
format
The format of the duration
duration
The new duration
ret
The new duration message. MT safe.
— Function: gst-message-new-state-dirty (src <gst-object>)   (ret <gst-message>)

Create a state dirty message. This message is posted whenever an element changed its state asynchronously and is used internally to update the states of container objects.

src
the object originating the message
ret
The new state dirty message. MT safe.