GstMessage

GstMessage — Lightweight objects to signal the application of pipeline events

Synopsis


#include <gst/gst.h>

                    GstMessage;
enum                GstMessageType;
#define             GST_MESSAGE_SRC                     (message)
#define             GST_MESSAGE_SRC_NAME                (message)
#define             GST_MESSAGE_TIMESTAMP               (message)
#define             GST_MESSAGE_TYPE                    (message)
#define             GST_MESSAGE_TYPE_NAME               (message)
#define             GST_MESSAGE_TRACE_NAME
GQuark              gst_message_type_to_quark           (GstMessageType type);
const gchar*        gst_message_type_get_name           (GstMessageType type);
GstMessage*         gst_message_ref                     (GstMessage *msg);
void                gst_message_unref                   (GstMessage *msg);
GstMessage*         gst_message_copy                    (const GstMessage *msg);
const GstStructure* gst_message_get_structure           (GstMessage *message);
#define             gst_message_make_writable           (msg)
guint32             gst_message_get_seqnum              (GstMessage *message);
void                gst_message_set_seqnum              (GstMessage *message,
                                                         guint32 seqnum);
GstMessage*         gst_message_new_eos                 (GstObject *src);
GstMessage*         gst_message_new_error               (GstObject *src,
                                                         GError *error,
                                                         const gchar *debug);
void                gst_message_parse_error             (GstMessage *message,
                                                         GError **gerror,
                                                         gchar **debug);
GstMessage*         gst_message_new_warning             (GstObject *src,
                                                         GError *error,
                                                         const gchar *debug);
void                gst_message_parse_warning           (GstMessage *message,
                                                         GError **gerror,
                                                         gchar **debug);
GstMessage*         gst_message_new_info                (GstObject *src,
                                                         GError *error,
                                                         const gchar *debug);
void                gst_message_parse_info              (GstMessage *message,
                                                         GError **gerror,
                                                         gchar **debug);
GstMessage*         gst_message_new_tag                 (GstObject *src,
                                                         GstTagList *tag_list);
GstMessage*         gst_message_new_tag_full            (GstObject *src,
                                                         GstPad *pad,
                                                         GstTagList *tag_list);
void                gst_message_parse_tag               (GstMessage *message,
                                                         GstTagList **tag_list);
void                gst_message_parse_tag_full          (GstMessage *message,
                                                         GstPad **pad,
                                                         GstTagList **tag_list);
GstMessage*         gst_message_new_buffering           (GstObject *src,
                                                         gint percent);
void                gst_message_parse_buffering         (GstMessage *message,
                                                         gint *percent);
void                gst_message_set_buffering_stats     (GstMessage *message,
                                                         GstBufferingMode mode,
                                                         gint avg_in,
                                                         gint avg_out,
                                                         gint64 buffering_left);
void                gst_message_parse_buffering_stats   (GstMessage *message,
                                                         GstBufferingMode *mode,
                                                         gint *avg_in,
                                                         gint *avg_out,
                                                         gint64 *buffering_left);
GstMessage*         gst_message_new_state_changed       (GstObject *src,
                                                         GstState oldstate,
                                                         GstState newstate,
                                                         GstState pending);
void                gst_message_parse_state_changed     (GstMessage *message,
                                                         GstState *oldstate,
                                                         GstState *newstate,
                                                         GstState *pending);
GstMessage*         gst_message_new_state_dirty         (GstObject *src);
GstMessage*         gst_message_new_step_done           (GstObject *src,
                                                         GstFormat format,
                                                         guint64 amount,
                                                         gdouble rate,
                                                         gboolean flush,
                                                         gboolean intermediate,
                                                         guint64 duration,
                                                         gboolean eos);
void                gst_message_parse_step_done         (GstMessage *message,
                                                         GstFormat *format,
                                                         guint64 *amount,
                                                         gdouble *rate,
                                                         gboolean *flush,
                                                         gboolean *intermediate,
                                                         guint64 *duration,
                                                         gboolean *eos);
GstMessage*         gst_message_new_clock_provide       (GstObject *src,
                                                         GstClock *clock,
                                                         gboolean ready);
void                gst_message_parse_clock_provide     (GstMessage *message,
                                                         GstClock **clock,
                                                         gboolean *ready);
GstMessage*         gst_message_new_clock_lost          (GstObject *src,
                                                         GstClock *clock);
void                gst_message_parse_clock_lost        (GstMessage *message,
                                                         GstClock **clock);
GstMessage*         gst_message_new_new_clock           (GstObject *src,
                                                         GstClock *clock);
void                gst_message_parse_new_clock         (GstMessage *message,
                                                         GstClock **clock);
GstMessage*         gst_message_new_application         (GstObject *src,
                                                         GstStructure *structure);
GstMessage*         gst_message_new_element             (GstObject *src,
                                                         GstStructure *structure);
GstMessage*         gst_message_new_custom              (GstMessageType type,
                                                         GstObject *src,
                                                         GstStructure *structure);
GstMessage*         gst_message_new_segment_start       (GstObject *src,
                                                         GstFormat format,
                                                         gint64 position);
void                gst_message_parse_segment_start     (GstMessage *message,
                                                         GstFormat *format,
                                                         gint64 *position);
GstMessage*         gst_message_new_segment_done        (GstObject *src,
                                                         GstFormat format,
                                                         gint64 position);
void                gst_message_parse_segment_done      (GstMessage *message,
                                                         GstFormat *format,
                                                         gint64 *position);
GstMessage*         gst_message_new_duration            (GstObject *src,
                                                         GstFormat format,
                                                         gint64 duration);
void                gst_message_parse_duration          (GstMessage *message,
                                                         GstFormat *format,
                                                         gint64 *duration);
GstMessage*         gst_message_new_latency             (GstObject *src);
GstMessage*         gst_message_new_async_start         (GstObject *src,
                                                         gboolean new_base_time);
void                gst_message_parse_async_start       (GstMessage *message,
                                                         gboolean *new_base_time);
GstMessage*         gst_message_new_async_done          (GstObject *src);
GstMessage*         gst_message_new_step_start          (GstObject *src,
                                                         gboolean active,
                                                         GstFormat format,
                                                         guint64 amount,
                                                         gdouble rate,
                                                         gboolean flush,
                                                         gboolean intermediate);
void                gst_message_parse_step_start        (GstMessage *message,
                                                         gboolean *active,
                                                         GstFormat *format,
                                                         guint64 *amount,
                                                         gdouble *rate,
                                                         gboolean *flush,
                                                         gboolean *intermediate);
enum                GstStructureChangeType;
GstMessage*         gst_message_new_structure_change    (GstObject *src,
                                                         GstStructureChangeType type,
                                                         GstElement *owner,
                                                         gboolean busy);
void                gst_message_parse_structure_change  (GstMessage *message,
                                                         GstStructureChangeType *type,
                                                         GstElement **owner,
                                                         gboolean *busy);
GstMessage*         gst_message_new_request_state       (GstObject *src,
                                                         GstState state);
void                gst_message_parse_request_state     (GstMessage *message,
                                                         GstState *state);
enum                GstStreamStatusType;
GstMessage*         gst_message_new_stream_status       (GstObject *src,
                                                         GstStreamStatusType type,
                                                         GstElement *owner);
void                gst_message_parse_stream_status     (GstMessage *message,
                                                         GstStreamStatusType *type,
                                                         GstElement **owner);
void                gst_message_set_stream_status_object
                                                        (GstMessage *message,
                                                         const GValue *object);
const GValue*       gst_message_get_stream_status_object
                                                        (GstMessage *message);

Description

Messages are implemented as a subclass of GstMiniObject with a generic GstStructure 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 GstBus.

The basic use pattern of posting a message on a GstBus is as follows:

Example 14. Posting a GstMessage

   gst_bus_post (bus, gst_message_new_eos());
  


A GstElement 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)

Details

GstMessage

typedef struct {
  GstMiniObject mini_object;

  GstMessageType type;
  guint64 timestamp;
  GstObject *src;

  GstStructure *structure;
} GstMessage;

A GstMessage.

GstMiniObject mini_object; the parent structure
GstMessageType type; the GstMessageType of the message
guint64 timestamp; the timestamp of the message
GstObject *src; the src of the message
GstStructure *structure; the GstStructure containing the message info.

enum GstMessageType

typedef enum
{
  GST_MESSAGE_UNKNOWN           = 0,
  GST_MESSAGE_EOS               = (1 << 0),
  GST_MESSAGE_ERROR             = (1 << 1),
  GST_MESSAGE_WARNING           = (1 << 2),
  GST_MESSAGE_INFO              = (1 << 3),
  GST_MESSAGE_TAG               = (1 << 4),
  GST_MESSAGE_BUFFERING         = (1 << 5),
  GST_MESSAGE_STATE_CHANGED     = (1 << 6),
  GST_MESSAGE_STATE_DIRTY       = (1 << 7),
  GST_MESSAGE_STEP_DONE         = (1 << 8),
  GST_MESSAGE_CLOCK_PROVIDE     = (1 << 9),
  GST_MESSAGE_CLOCK_LOST        = (1 << 10),
  GST_MESSAGE_NEW_CLOCK         = (1 << 11),
  GST_MESSAGE_STRUCTURE_CHANGE  = (1 << 12),
  GST_MESSAGE_STREAM_STATUS     = (1 << 13),
  GST_MESSAGE_APPLICATION       = (1 << 14),
  GST_MESSAGE_ELEMENT           = (1 << 15),
  GST_MESSAGE_SEGMENT_START     = (1 << 16),
  GST_MESSAGE_SEGMENT_DONE      = (1 << 17),
  GST_MESSAGE_DURATION          = (1 << 18),
  GST_MESSAGE_LATENCY           = (1 << 19),
  GST_MESSAGE_ASYNC_START       = (1 << 20),
  GST_MESSAGE_ASYNC_DONE        = (1 << 21),
  GST_MESSAGE_REQUEST_STATE     = (1 << 22),
  GST_MESSAGE_STEP_START        = (1 << 23),
  GST_MESSAGE_ANY               = ~0
} GstMessageType;

The different message types that are available.

GST_MESSAGE_UNKNOWN an undefined message
GST_MESSAGE_EOS end-of-stream reached in a pipeline. The application will only receive this message in the PLAYING state and every time it sets a pipeline to PLAYING that is in the EOS state. The application can perform a flushing seek in the pipeline, which will undo the EOS state again.
GST_MESSAGE_ERROR an error occured. Whe the application receives an error message it should stop playback of the pipeline and not assume that more data will be played.
GST_MESSAGE_WARNING a warning occured.
GST_MESSAGE_INFO an info message occured
GST_MESSAGE_TAG a tag was found.
GST_MESSAGE_BUFFERING the pipeline is buffering. When the application receives a buffering message in the PLAYING state for a non-live pipeline it must PAUSE the pipeline until the buffering completes, when the percentage field in the message is 100%. For live pipelines, no action must be performed and the buffering percentage can be used to inform the user about the progress.
GST_MESSAGE_STATE_CHANGED a state change happened
GST_MESSAGE_STATE_DIRTY an element changed state in a streaming thread. This message is deprecated.
GST_MESSAGE_STEP_DONE a framestep finished. This message is not yet implemented.
GST_MESSAGE_CLOCK_PROVIDE an element notifies its capability of providing a clock. This message is used internally and never forwarded to the application.
GST_MESSAGE_CLOCK_LOST The current clock as selected by the pipeline became unusable. The pipeline will select a new clock on the next PLAYING state change.
GST_MESSAGE_NEW_CLOCK a new clock was selected in the pipeline.
GST_MESSAGE_STRUCTURE_CHANGE the structure of the pipeline changed. This message is used internally and never forwarded to the application.
GST_MESSAGE_STREAM_STATUS status about a stream, emitted when it starts, stops, errors, etc..
GST_MESSAGE_APPLICATION message posted by the application, possibly via an application-specific element.
GST_MESSAGE_ELEMENT element-specific message, see the specific element's documentation
GST_MESSAGE_SEGMENT_START pipeline started playback of a segment. This message is used internally and never forwarded to the application.
GST_MESSAGE_SEGMENT_DONE pipeline completed playback of a segment. This message is forwarded to the application after all elements that posted GST_MESSAGE_SEGMENT_START posted a GST_MESSAGE_SEGMENT_DONE message.
GST_MESSAGE_DURATION The duration of a pipeline changed. The application can get the new duration with a duration query.
GST_MESSAGE_LATENCY Posted by elements when their latency changes. The pipeline will calculate and distribute a new latency. Since: 0.10.12
GST_MESSAGE_ASYNC_START Posted by elements when they start an ASYNC state change. This message is not forwarded to the application but is used internally. Since: 0.10.13.
GST_MESSAGE_ASYNC_DONE Posted by elements when they complete an ASYNC state change. The application will only receive this message from the toplevel pipeline. Since: 0.10.13
GST_MESSAGE_REQUEST_STATE Posted by elements when they want the pipeline to change state. This message is a suggestion to the application which can decide to perform the state change on (part of) the pipeline. Since: 0.10.23.
GST_MESSAGE_STEP_START A stepping operation was started.
GST_MESSAGE_ANY mask for all of the above messages.

GST_MESSAGE_SRC()

#define GST_MESSAGE_SRC(message)	(GST_MESSAGE(message)->src)

Get the object that posted message.

message : a GstMessage

GST_MESSAGE_SRC_NAME()

#define             GST_MESSAGE_SRC_NAME(message)

Get the name of the object that posted message. Returns "(NULL)" if the message has no source object set.

message : a GstMessage

Since 0.10.24


GST_MESSAGE_TIMESTAMP()

#define GST_MESSAGE_TIMESTAMP(message)	(GST_MESSAGE(message)->timestamp)

Get the timestamp of message. This is the timestamp when the message was created.

message : a GstMessage

GST_MESSAGE_TYPE()

#define GST_MESSAGE_TYPE(message)	(GST_MESSAGE(message)->type)

Get the GstMessageType of message.

message : a GstMessage

GST_MESSAGE_TYPE_NAME()

#define GST_MESSAGE_TYPE_NAME(message)	gst_message_type_get_name(GST_MESSAGE_TYPE(message))

Get a constant string representation of the GstMessageType of message.

message : a GstMessage

Since 0.10.4


GST_MESSAGE_TRACE_NAME

#define GST_MESSAGE_TRACE_NAME	"GstMessage"

The name used for memory allocation tracing


gst_message_type_to_quark ()

GQuark              gst_message_type_to_quark           (GstMessageType type);

Get the unique quark for the given message type.

type : the message type
Returns : the quark associated with the message type

gst_message_type_get_name ()

const gchar*        gst_message_type_get_name           (GstMessageType type);

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

type : the message type
Returns : a reference to the static name of the message.

gst_message_ref ()

GstMessage*         gst_message_ref                     (GstMessage *msg);

Convenience macro to increase the reference count of the message.

msg : the message to ref
Returns : msg (for convenience when doing assignments)

gst_message_unref ()

void                gst_message_unref                   (GstMessage *msg);

Convenience macro to decrease the reference count of the message, possibly freeing it.

msg : the message to unref

gst_message_copy ()

GstMessage*         gst_message_copy                    (const GstMessage *msg);

Creates a copy of the message. Returns a copy of the message.

msg : the message to copy
Returns : a new copy of msg. MT safe

gst_message_get_structure ()

const GstStructure* gst_message_get_structure           (GstMessage *message);

Access the structure of the message.

message : The GstMessage.
Returns : 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.

gst_message_make_writable()

#define         gst_message_make_writable(msg)	GST_MESSAGE (gst_mini_object_make_writable (GST_MINI_OBJECT (msg)))

Checks if a message is writable. If not, a writable copy is made and returned. Returns a message (possibly a duplicate) that is writable.

MT safe

msg : the message to make writable

gst_message_get_seqnum ()

guint32             gst_message_get_seqnum              (GstMessage *message);

Retrieve the sequence number of a message.

Messages have ever-incrementing sequence numbers, which may also be set explicitly via gst_message_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.

message : A GstMessage.
Returns : The message's sequence number. MT safe.

Since 0.10.22


gst_message_set_seqnum ()

void                gst_message_set_seqnum              (GstMessage *message,
                                                         guint32 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 gst_message_get_seqnum() for more information.

MT safe.

message : A GstMessage.
seqnum : A sequence number.

Since 0.10.22


gst_message_new_eos ()

GstMessage*         gst_message_new_eos                 (GstObject *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.

src : The object originating the message.
Returns : The new eos message. MT safe.

gst_message_new_error ()

GstMessage*         gst_message_new_error               (GstObject *src,
                                                         GError *error,
                                                         const gchar *debug);

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.
Returns : The new error message. MT safe.

gst_message_parse_error ()

void                gst_message_parse_error             (GstMessage *message,
                                                         GError **gerror,
                                                         gchar **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.

message : A valid GstMessage of type GST_MESSAGE_ERROR.
gerror : Location for the GError
debug : Location for the debug message, or NULL

gst_message_new_warning ()

GstMessage*         gst_message_new_warning             (GstObject *src,
                                                         GError *error,
                                                         const gchar *debug);

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.
Returns : The new warning message. MT safe.

gst_message_parse_warning ()

void                gst_message_parse_warning           (GstMessage *message,
                                                         GError **gerror,
                                                         gchar **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.

message : A valid GstMessage of type GST_MESSAGE_WARNING.
gerror : Location for the GError
debug : Location for the debug message, or NULL

gst_message_new_info ()

GstMessage*         gst_message_new_info                (GstObject *src,
                                                         GError *error,
                                                         const gchar *debug);

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

MT safe.

src : The object originating the message.
error : The GError for this message.
debug : A debugging string.
Returns : The new info message.

Since 0.10.12


gst_message_parse_info ()

void                gst_message_parse_info              (GstMessage *message,
                                                         GError **gerror,
                                                         gchar **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.

message : A valid GstMessage of type GST_MESSAGE_INFO.
gerror : Location for the GError
debug : Location for the debug message, or NULL

Since 0.10.12


gst_message_new_tag ()

GstMessage*         gst_message_new_tag                 (GstObject *src,
                                                         GstTagList *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.

src : The object originating the message.
tag_list : The tag list for the message.
Returns : The new tag message. MT safe.

gst_message_new_tag_full ()

GstMessage*         gst_message_new_tag_full            (GstObject *src,
                                                         GstPad *pad,
                                                         GstTagList *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.

src : The object originating the message.
pad : The originating pad for the tag.
tag_list : The tag list for the message.
Returns : The new tag message.

Since 0.10.24


gst_message_parse_tag ()

void                gst_message_parse_tag               (GstMessage *message,
                                                         GstTagList **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.

message : A valid GstMessage of type GST_MESSAGE_TAG.
tag_list : Return location for the tag-list.

gst_message_parse_tag_full ()

void                gst_message_parse_tag_full          (GstMessage *message,
                                                         GstPad **pad,
                                                         GstTagList **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.

message : A valid GstMessage of type GST_MESSAGE_TAG.
pad : Location where the originating pad is stored, unref after usage
tag_list : Return location for the tag-list.

Since 0.10.24


gst_message_new_buffering ()

GstMessage*         gst_message_new_buffering           (GstObject *src,
                                                         gint 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 percent is 100, the application can set the pipeline (back) to PLAYING. 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.

src : The object originating the message.
percent : The buffering percent
Returns : The new buffering message.

Since 0.10.11


gst_message_parse_buffering ()

void                gst_message_parse_buffering         (GstMessage *message,
                                                         gint *percent);

Extracts the buffering percent from the GstMessage. see also gst_message_new_buffering().

MT safe.

message : A valid GstMessage of type GST_MESSAGE_BUFFERING.
percent : Return location for the percent.

Since 0.10.11


gst_message_set_buffering_stats ()

void                gst_message_set_buffering_stats     (GstMessage *message,
                                                         GstBufferingMode mode,
                                                         gint avg_in,
                                                         gint avg_out,
                                                         gint64 buffering_left);

Configures the buffering stats values in message.

message : A valid GstMessage of type GST_MESSAGE_BUFFERING.
mode : a buffering mode
avg_in : the average input rate
avg_out : the average output rate
buffering_left : amount of buffering time left in milliseconds

Since 0.10.20


gst_message_parse_buffering_stats ()

void                gst_message_parse_buffering_stats   (GstMessage *message,
                                                         GstBufferingMode *mode,
                                                         gint *avg_in,
                                                         gint *avg_out,
                                                         gint64 *buffering_left);

Extracts the buffering stats values from message.

message : A valid GstMessage of type GST_MESSAGE_BUFFERING.
mode : a buffering mode
avg_in : the average input rate
avg_out : the average output rate
buffering_left : amount of buffering time left in milliseconds.

Since 0.10.20


gst_message_new_state_changed ()

GstMessage*         gst_message_new_state_changed       (GstObject *src,
                                                         GstState oldstate,
                                                         GstState newstate,
                                                         GstState pending);

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
Returns : The new state change message. MT safe.

gst_message_parse_state_changed ()

void                gst_message_parse_state_changed     (GstMessage *message,
                                                         GstState *oldstate,
                                                         GstState *newstate,
                                                         GstState *pending);

Extracts the old and new states from the GstMessage.

MT safe.

message : a valid GstMessage of type GST_MESSAGE_STATE_CHANGED
oldstate : the previous state, or NULL
newstate : the new (current) state, or NULL
pending : the pending (target) state, or NULL

gst_message_new_state_dirty ()

GstMessage*         gst_message_new_state_dirty         (GstObject *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.

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

gst_message_new_step_done ()

GstMessage*         gst_message_new_step_done           (GstObject *src,
                                                         GstFormat format,
                                                         guint64 amount,
                                                         gdouble rate,
                                                         gboolean flush,
                                                         gboolean intermediate,
                                                         guint64 duration,
                                                         gboolean eos);

This message is posted by elements when they complete a part, when intermediate set to TRUE, or a complete step operation.

duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped amount of media in format format.

src : The object originating the message.
format : the format of amount
amount : the amount of stepped data
rate : the rate of the stepped amount
flush : is this an flushing step
intermediate : is this an intermediate step
duration : the duration of the data
eos : the step caused EOS
Returns : The new step_done message. MT safe.

Since 0.10.24


gst_message_parse_step_done ()

void                gst_message_parse_step_done         (GstMessage *message,
                                                         GstFormat *format,
                                                         guint64 *amount,
                                                         gdouble *rate,
                                                         gboolean *flush,
                                                         gboolean *intermediate,
                                                         guint64 *duration,
                                                         gboolean *eos);

Extract the values the step_done message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_STEP_DONE.
format : result location for the format
amount : result location for the amount
rate : result location for the rate
flush : result location for the flush flag
intermediate : result location for the intermediate flag
duration : result location for the duration
eos : result location for the EOS flag

Since 0.10.24


gst_message_new_clock_provide ()

GstMessage*         gst_message_new_clock_provide       (GstObject *src,
                                                         GstClock *clock,
                                                         gboolean 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.

src : The object originating the message.
clock : The clock it provides
ready : TRUE if the sender can provide a clock
Returns : The new provide clock message. MT safe.

gst_message_parse_clock_provide ()

void                gst_message_parse_clock_provide     (GstMessage *message,
                                                         GstClock **clock,
                                                         gboolean *ready);

Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.
clock : A pointer to hold a clock object.
ready : A pointer to hold the ready flag.

gst_message_new_clock_lost ()

GstMessage*         gst_message_new_clock_lost          (GstObject *src,
                                                         GstClock *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.

src : The object originating the message.
clock : the clock that was lost
Returns : The new clock lost message. MT safe.

gst_message_parse_clock_lost ()

void                gst_message_parse_clock_lost        (GstMessage *message,
                                                         GstClock **clock);

Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_CLOCK_LOST.
clock : A pointer to hold the lost clock

gst_message_new_new_clock ()

GstMessage*         gst_message_new_new_clock           (GstObject *src,
                                                         GstClock *clock);

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
Returns : The new new clock message. MT safe.

gst_message_parse_new_clock ()

void                gst_message_parse_new_clock         (GstMessage *message,
                                                         GstClock **clock);

Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_NEW_CLOCK.
clock : A pointer to hold the selected new clock

gst_message_new_application ()

GstMessage*         gst_message_new_application         (GstObject *src,
                                                         GstStructure *structure);

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.
Returns : The new application message. MT safe.

gst_message_new_element ()

GstMessage*         gst_message_new_element             (GstObject *src,
                                                         GstStructure *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.

src : The object originating the message.
structure : The structure for the message. The message will take ownership of the structure.
Returns : The new element message. MT safe.

gst_message_new_custom ()

GstMessage*         gst_message_new_custom              (GstMessageType type,
                                                         GstObject *src,
                                                         GstStructure *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.

type : The GstMessageType to distinguish messages
src : The object originating the message.
structure : The structure for the message. The message will take ownership of the structure.
Returns : The new message. MT safe.

gst_message_new_segment_start ()

GstMessage*         gst_message_new_segment_start       (GstObject *src,
                                                         GstFormat format,
                                                         gint64 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.

src : The object originating the message.
format : The format of the position being played
position : The position of the segment being played
Returns : The new segment start message. MT safe.

gst_message_parse_segment_start ()

void                gst_message_parse_segment_start     (GstMessage *message,
                                                         GstFormat *format,
                                                         gint64 *position);

Extracts the position and format from the segment start message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_SEGMENT_START.
format : Result location for the format, or NULL
position : Result location for the position, or NULL

gst_message_new_segment_done ()

GstMessage*         gst_message_new_segment_done        (GstObject *src,
                                                         GstFormat format,
                                                         gint64 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.

src : The object originating the message.
format : The format of the position being done
position : The position of the segment being done
Returns : The new segment done message. MT safe.

gst_message_parse_segment_done ()

void                gst_message_parse_segment_done      (GstMessage *message,
                                                         GstFormat *format,
                                                         gint64 *position);

Extracts the position and format from the segment start message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_SEGMENT_DONE.
format : Result location for the format, or NULL
position : Result location for the position, or NULL

gst_message_new_duration ()

GstMessage*         gst_message_new_duration            (GstObject *src,
                                                         GstFormat format,
                                                         gint64 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.

src : The object originating the message.
format : The format of the duration
duration : The new duration
Returns : The new duration message. MT safe.

gst_message_parse_duration ()

void                gst_message_parse_duration          (GstMessage *message,
                                                         GstFormat *format,
                                                         gint64 *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.

message : A valid GstMessage of type GST_MESSAGE_DURATION.
format : Result location for the format, or NULL
duration : Result location for the duration, or NULL

gst_message_new_latency ()

GstMessage*         gst_message_new_latency             (GstObject *src);

This message can be posted by elements when their latency requirements have changed.

src : The object originating the message.
Returns : The new latency message. MT safe.

Since 0.10.12


gst_message_new_async_start ()

GstMessage*         gst_message_new_async_start         (GstObject *src,
                                                         gboolean new_base_time);

This message is posted by elements when they start an ASYNC state change. new_base_time is set to TRUE when the element lost its state when it was PLAYING.

src : The object originating the message.
new_base_time : if a new base_time should be set on the element
Returns : The new async_start message. MT safe.

Since 0.10.13


gst_message_parse_async_start ()

void                gst_message_parse_async_start       (GstMessage *message,
                                                         gboolean *new_base_time);

Extract the new_base_time from the async_start message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_ASYNC_DONE.
new_base_time : Result location for the new_base_time or NULL

Since 0.10.13


gst_message_new_async_done ()

GstMessage*         gst_message_new_async_done          (GstObject *src);

The message is posted when elements completed an ASYNC state change.

src : The object originating the message.
Returns : The new async_done message. MT safe.

Since 0.10.13


gst_message_new_step_start ()

GstMessage*         gst_message_new_step_start          (GstObject *src,
                                                         gboolean active,
                                                         GstFormat format,
                                                         guint64 amount,
                                                         gdouble rate,
                                                         gboolean flush,
                                                         gboolean intermediate);

This message is posted by elements when they accept or activate a new step event for amount in format.

active is set to FALSE when the element accepted the new step event and has queued it for execution in the streaming threads.

active is set to TRUE when the element has activated the step operation and 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.

src : The object originating the message.
active : if the step is active or queued
format : the format of amount
amount : the amount of stepped data
rate : the rate of the stepped amount
flush : is this an flushing step
intermediate : is this an intermediate step
Returns : The new step_start message. MT safe.

Since 0.10.24


gst_message_parse_step_start ()

void                gst_message_parse_step_start        (GstMessage *message,
                                                         gboolean *active,
                                                         GstFormat *format,
                                                         guint64 *amount,
                                                         gdouble *rate,
                                                         gboolean *flush,
                                                         gboolean *intermediate);

Extract the values from step_start message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_STEP_DONE.
active : result location for the active flag
format : result location for the format
amount : result location for the amount
rate : result location for the rate
flush : result location for the flush flag
intermediate : result location for the intermediate flag

Since 0.10.24


enum GstStructureChangeType

typedef enum {
  GST_STRUCTURE_CHANGE_TYPE_PAD_LINK   = 0,
  GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK = 1
} GstStructureChangeType;

The type of a GstMessageStructureChange.

GST_STRUCTURE_CHANGE_TYPE_PAD_LINK Pad linking is starting or done.
GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK Pad unlinking is starting or done.

Since 0.10.22


gst_message_new_structure_change ()

GstMessage*         gst_message_new_structure_change    (GstObject *src,
                                                         GstStructureChangeType type,
                                                         GstElement *owner,
                                                         gboolean 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.

src should be the sinkpad that unlinked or linked.

src : The object originating the message.
type : The change type.
owner : The owner element of src.
busy : Whether the structure change is busy.
Returns : The new structure change message. MT safe.

Since 0.10.22.


gst_message_parse_structure_change ()

void                gst_message_parse_structure_change  (GstMessage *message,
                                                         GstStructureChangeType *type,
                                                         GstElement **owner,
                                                         gboolean *busy);

Extracts the change type and completion status from the GstMessage.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.
type : A pointer to hold the change type
owner : The owner element of the message source
busy : A pointer to hold whether the change is in progress or has been completed

Since 0.10.22


gst_message_new_request_state ()

GstMessage*         gst_message_new_request_state       (GstObject *src,
                                                         GstState 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.

src : The object originating the message.
state : The new requested state
Returns : The new requst state message. MT safe.

Since 0.10.23


gst_message_parse_request_state ()

void                gst_message_parse_request_state     (GstMessage *message,
                                                         GstState *state);

Extract the requested state from the request_state message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_REQUEST_STATE.
state : Result location for the requested state or NULL

Since 0.10.23


enum GstStreamStatusType

typedef enum {
  GST_STREAM_STATUS_TYPE_CREATE   = 0,
  GST_STREAM_STATUS_TYPE_ENTER    = 1,
  GST_STREAM_STATUS_TYPE_LEAVE    = 2,
  GST_STREAM_STATUS_TYPE_DESTROY  = 3,

  GST_STREAM_STATUS_TYPE_START    = 8,
  GST_STREAM_STATUS_TYPE_PAUSE    = 9,
  GST_STREAM_STATUS_TYPE_STOP     = 10
} GstStreamStatusType;

The type of a GstMessageStreamStatus. The stream status messages inform the application of new streaming threads and their status.

GST_STREAM_STATUS_TYPE_CREATE A new thread need to be created.
GST_STREAM_STATUS_TYPE_ENTER a thread entered its loop function
GST_STREAM_STATUS_TYPE_LEAVE a thread left its loop function
GST_STREAM_STATUS_TYPE_DESTROY a thread is destroyed
GST_STREAM_STATUS_TYPE_START a thread is started
GST_STREAM_STATUS_TYPE_PAUSE a thread is paused
GST_STREAM_STATUS_TYPE_STOP a thread is stopped

Since 0.10.24


gst_message_new_stream_status ()

GstMessage*         gst_message_new_stream_status       (GstObject *src,
                                                         GstStreamStatusType type,
                                                         GstElement *owner);

Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed.

src : The object originating the message.
type : The stream status type.
owner : The owner element of src.
Returns : The new stream status message. MT safe.

Since 0.10.24.


gst_message_parse_stream_status ()

void                gst_message_parse_stream_status     (GstMessage *message,
                                                         GstStreamStatusType *type,
                                                         GstElement **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.

message : A valid GstMessage of type GST_MESSAGE_STREAM_STATUS.
type : A pointer to hold the status type
owner : The owner element of the message source

Since 0.10.24.


gst_message_set_stream_status_object ()

void                gst_message_set_stream_status_object
                                                        (GstMessage *message,
                                                         const GValue *object);

Configures the object handling the streaming thread. This is usually a GstTask object but other objects might be added in the future.

message : A valid GstMessage of type GST_MESSAGE_STREAM_STATUS.
object : the object controlling the streaming

Since 0.10.24


gst_message_get_stream_status_object ()

const GValue*       gst_message_get_stream_status_object
                                                        (GstMessage *message);

Extracts the object managing the streaming thread from message.

message : A valid GstMessage of type GST_MESSAGE_STREAM_STATUS.
Returns : a GValue containing the object that manages the streaming thread. 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.

Since 0.10.24

See Also

GstBus, GstMiniObject, GstElement