GstMessage

typedef struct {
  GstMiniObject mini_object;

  GstMessageType type;
  guint64 timestamp;
  GstObject *src;

  GstStructure *structure;
} GstMessage;

A GstMessage.

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

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

Get the object that posted message.

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.

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.

GST_MESSAGE_TYPE()

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

Get the GstMessageType of message.

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.

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.

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.

gst_message_ref ()

GstMessage*         gst_message_ref                     (GstMessage *msg);

Convenience macro to increase the reference count of the message.

gst_message_unref ()

void                gst_message_unref                   (GstMessage *msg);

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

gst_message_copy ()

GstMessage*         gst_message_copy                    (const GstMessage *msg);

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

gst_message_get_structure ()

const GstStructure* gst_message_get_structure           (GstMessage *message);

Access the structure of the message.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

gst_message_new_latency ()

GstMessage*         gst_message_new_latency             (GstObject *src);

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Since 0.10.24