Message

Object Hierarchy:

Description:

public class Message : MiniObject

Messages are implemented as a subclass of MiniObject with a generic 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 Bus. The basic use pattern of posting a message on a Bus is as follows:

Posting a Message:


gst_bus_post (bus, gst_message_new_eos());

A Element usually posts messages on the bus provided by the parent container using post_message. Last reviewed on 2005-11-09 (0.9.4)

Namespace: Gst

Package: gstreamer-0.10

Content:

Static methods:

public static Quark type_to_quark (MessageType type)

Creation methods:

public Message.application (Object src, owned Structure? structure)
Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy. MT safe.
public Message.async_done (Object src)
The message is posted when elements completed an ASYNC state change. MT safe.
public Message.async_start (Object src, bool new_base_time)
This message is posted by elements when they start an ASYNC state change. PLAYING. MT safe.
public Message.buffering (Object src, int percent)
Create a new buffering message. This message can be posted by an element that needs to buffer data before it can continue processing. percent should be a value between 0 and 100. A value of 100 means that the buffering completed. When percent is < 100 the application should PAUSE a PLAYING pipeline. When The application must be prepared to receive BUFFERING messages in the PREROLLING state and may only set the pipeline to PLAYING after receiving a message with percent set to 100, which can happen after the pipeline completed prerolling. MT safe.
public Message.clock_lost (Object src, Clock clock)
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. MT safe.
public Message.clock_provide (Object src, Clock clock, bool ready)
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. MT safe.
public Message.custom (MessageType type, Object src, owned Structure? structure)
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. MT safe.
public Message.duration (Object src, Format format, int64 duration)
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. MT safe.
public Message.element (Object src, owned Structure? structure)
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. MT safe.
public Message.eos (Object src)
Create a new eos message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the EOS message to the application if all sinks have posted an EOS message. MT safe.
public Message.error (Object src, Error error, string? debug)
Create a new error message. The message will copy error and occured. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline. MT safe.
public Message.info (Object src, Error error, string? debug)
Create a new info message. The message will make copies of error and MT safe.
public Message.latency (Object src)
This message can be posted by elements when their latency requirements have changed. MT safe.
public Message.new_clock (Object src, Clock clock)
Create a new clock message. This message is posted whenever the pipeline selectes a new clock for the pipeline. MT safe.
public Message.progress (Object src, ProgressType type, string code, string text)
Progress messages are posted by elements when they use an asynchronous task to perform actions triggered by a state change.
public Message.qos (Object src, bool live, uint64 running_time, uint64 stream_time, uint64 timestamp, uint64 duration)
A QOS message is posted on the bus whenever an element decides to drop a buffer because of QoS reasons or whenever it changes its processing strategy because of QoS reasons (quality adjustments such as processing at lower accuracy). This message can be posted by an element that performs synchronisation against the clock (live) or it could be dropped by an element that performs QoS because of QOS events received from a downstream element (!live). respective running-time, stream-time, timestamp and duration of the (dropped) buffer that generated the QoS event. Values can be left to GST_CLOCK_TIME_NONE when unknown. MT safe.
public Message.request_state (Object src, State state)
This message can be posted by elements when they want to have their state changed. A typical use case would be an audio server that wants to pause the pipeline because a higher priority stream is being played. MT safe.
public Message.segment_done (Object src, Format format, int64 position)
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. MT safe.
public Message.segment_start (Object src, Format format, int64 position)
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. MT safe.
public Message.state_changed (Object src, State oldstate, State newstate, State pending)
Create a state change message. This message is posted whenever an element changed its state. MT safe.
public Message.state_dirty (Object src)
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. MT safe.
public Message.step_done (Object src, Format format, uint64 amount, double rate, bool flush, bool intermediate, uint64 duration, bool eos)
This message is posted by elements when they complete a part, when intermediate set to TRUE, or a complete step operation. MT safe.
public Message.step_start (Object src, bool active, Format format, uint64 amount, double rate, bool flush, bool intermediate)
This message is posted by elements when they accept or activate a new step event for amount in format. queued it for execution in the streaming threads. is now ready to start executing the step in the streaming thread. After this message is emited, the application can queue a new step operation in the element. MT safe.
public Message.stream_status (Object src, StreamStatusType type, Element owner)
Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed. MT safe.
public Message.structure_change (Object src, StructureChangeType type, Element owner, bool busy)
Create a new structure change message. This message is posted when the structure of a pipeline is in the process of being changed, for example when pads are linked or unlinked. MT safe.
public Message.tag (Object src, TagList tag_list)
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. MT safe.
public Message.tag_full (Object src, Pad pad, TagList tag_list)
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. MT safe.
public Message.warning (Object src, Error error, string? debug)
Create a new warning message. The message will make copies of error and MT safe.

Methods:

public Message copy ()
public uint32 get_seqnum ()
Retrieve the sequence number of a message. Messages have ever-incrementing sequence numbers, which may also be set explicitly via set_seqnum. Sequence numbers are typically used to indicate that a message corresponds to some other set of messages or events, for example a SEGMENT_DONE message corresponding to a SEEK event. It is considered good practice to make this correspondence when possible, though it is not required. Note that events and messages share the same sequence number incrementor; two events or messages will never not have the same sequence number unless that correspondence was made explicitly. MT safe.
public unowned Value? get_stream_status_object ()
Extracts the object managing the streaming thread from message. This object is usually of type GstTask but other types can be added in the future. The object remains valid as long as message is valid.
public unowned Structure? get_structure ()
Access the structure of the message. 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.
public void make_writable ()
public void parse_async_start (out bool new_base_time)
Extract the new_base_time from the async_start message. MT safe.
public void parse_buffering (out int percent)
Extracts the buffering percent from the GstMessage. see also Message.buffering. MT safe.
public void parse_buffering_stats (out BufferingMode mode, out int avg_in, out int avg_out, out int64 buffering_left)
Extracts the buffering stats values from message.
public void parse_clock_lost (out Clock clock)
Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe.
public void parse_clock_provide (out Clock clock, out bool ready)
Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed. MT safe.
public void parse_duration (out Format format, out int64 duration)
Extracts the duration and format from the duration message. The duration might be GST_CLOCK_TIME_NONE, which indicates that the duration has changed. Applications should always use a query to retrieve the duration of a pipeline. MT safe.
public void parse_error (out Error gerror, out string? debug)
Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. Typical usage of this function might be:
public void parse_info (out Error gerror, out string? debug)
Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe.
public void parse_new_clock (out Clock clock)
Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe.
public void parse_progress (ProgressType type, string code, string text)
Parses the progress type, code and text.
public void parse_qos (out bool live, out uint64 running_time, out uint64 stream_time, out uint64 timestamp, out uint64 duration)
Extract the timestamps and live status from the QoS message. The returned values give the running_time, stream_time, timestamp and duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown values. MT safe.
public void parse_qos_stats (out Format format, out uint64 processed, out uint64 dropped)
Extract the QoS stats representing the history of the current continuous pipeline playback period. When format is GST_FORMAT_UNDEFINED both dropped and processed are invalid. Values of -1 for either processed or dropped mean unknown values. MT safe.
public void parse_qos_values (out int64 jitter, out double proportion, out int quality)
Extract the QoS values that have been calculated/analysed from the QoS data MT safe.
public void parse_request_state (out State state)
Extract the requested state from the request_state message. MT safe.
public void parse_segment_done (out Format format, out int64 position)
Extracts the position and format from the segment start message. MT safe.
public void parse_segment_start (out Format format, out int64 position)
Extracts the position and format from the segment start message. MT safe.
public void parse_state_changed (out State oldstate, out State newstate, out State pending)
Extracts the old and new states from the GstMessage. Typical usage of this function might be:
public void parse_step_done (out Format format, out uint64 amount, out double rate, out bool flush, out bool intermediate, out uint64 duration, out bool eos)
Extract the values the step_done message. MT safe.
public void parse_step_start (out bool active, out Format format, out uint64 amount, out double rate, out bool flush, out bool intermediate)
Extract the values from step_start message. MT safe.
public void parse_stream_status (out StreamStatusType type, out Element owner)
Extracts the stream status type and owner the GstMessage. The returned owner remains valid for as long as the reference to message is valid and should thus not be unreffed. MT safe.
public void parse_structure_change (out StructureChangeType type, out Element owner, out bool busy)
Extracts the change type and completion status from the GstMessage. MT safe.
public void parse_tag (out TagList tag_list)
Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done. Typical usage of this function might be:
public void parse_tag_full (out Pad pad, out TagList tag_list)
Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done. MT safe.
public void parse_warning (out Error gerror, out string? debug)
Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe.
public weak Message ref ()
public void set_buffering_stats (BufferingMode mode, int avg_in, int avg_out, int64 buffering_left)
Configures the buffering stats values in message.
public void set_qos_stats (Format format, uint64 processed, uint64 dropped)
Set the QoS stats representing the history of the current continuous pipeline playback period. When format is GST_FORMAT_UNDEFINED both dropped and processed are invalid. Values of -1 for either processed or dropped mean unknown values. MT safe.
public void set_qos_values (int64 jitter, double proportion, int quality)
Set the QoS values that have been calculated/analysed from the QoS data MT safe.
public void set_seqnum (uint32 seqnum)
Set the sequence number of a message. This function might be called by the creator of a message to indicate that the message relates to other messages or events. See get_seqnum for more information. MT safe.
public void set_stream_status_object (ref Value? object)
Configures the object handling the streaming thread. This is usually a GstTask object but other objects might be added in the future.
public void unref ()

Fields:

public weak Object src
public uint64 timestamp
public MessageType type