manpagez: man pages & more
html files: gstreamer-1.0
Home | html | info | man

GstMessage

GstMessage — Lightweight objects to signal the application of pipeline events

Functions

#define GST_MESSAGE_SRC()
#define GST_MESSAGE_SRC_NAME()
#define GST_MESSAGE_TIMESTAMP()
#define GST_MESSAGE_SEQNUM()
#define GST_MESSAGE_TYPE()
#define GST_MESSAGE_TYPE_IS_EXTENDED()
#define GST_MESSAGE_TYPE_NAME()
GQuark gst_message_type_to_quark ()
const gchar * gst_message_type_get_name ()
GstMessage * gst_message_ref ()
void gst_message_unref ()
GstMessage * gst_message_copy ()
const GstStructure * gst_message_get_structure ()
#define gst_message_make_writable()
guint32 gst_message_get_seqnum ()
void gst_message_set_seqnum ()
gboolean gst_message_has_name ()
#define gst_message_is_writable()
gboolean gst_message_replace ()
GstMessage * gst_message_new_eos ()
GstMessage * gst_message_new_error ()
GstMessage * gst_message_new_error_with_details ()
void gst_message_parse_error ()
void gst_message_parse_error_details ()
GstMessage * gst_message_new_warning ()
GstMessage * gst_message_new_warning_with_details ()
void gst_message_parse_warning ()
void gst_message_parse_warning_details ()
GstMessage * gst_message_new_info ()
GstMessage * gst_message_new_info_with_details ()
void gst_message_parse_info ()
void gst_message_parse_info_details ()
GstMessage * gst_message_new_tag ()
void gst_message_parse_tag ()
GstMessage * gst_message_new_buffering ()
void gst_message_parse_buffering ()
void gst_message_set_buffering_stats ()
void gst_message_parse_buffering_stats ()
GstMessage * gst_message_new_state_changed ()
void gst_message_parse_state_changed ()
GstMessage * gst_message_new_state_dirty ()
GstMessage * gst_message_new_step_done ()
void gst_message_parse_step_done ()
GstMessage * gst_message_new_clock_provide ()
void gst_message_parse_clock_provide ()
GstMessage * gst_message_new_clock_lost ()
void gst_message_parse_clock_lost ()
GstMessage * gst_message_new_new_clock ()
void gst_message_parse_new_clock ()
GstMessage * gst_message_new_application ()
GstMessage * gst_message_new_element ()
GstMessage * gst_message_new_custom ()
GstMessage * gst_message_new_segment_start ()
void gst_message_parse_segment_start ()
GstMessage * gst_message_new_segment_done ()
void gst_message_parse_segment_done ()
GstMessage * gst_message_new_duration_changed ()
GstMessage * gst_message_new_latency ()
GstMessage * gst_message_new_async_start ()
GstMessage * gst_message_new_async_done ()
void gst_message_parse_async_done ()
GstMessage * gst_message_new_step_start ()
void gst_message_parse_step_start ()
GstMessage * gst_message_new_qos ()
void gst_message_set_qos_values ()
void gst_message_set_qos_stats ()
void gst_message_parse_qos ()
void gst_message_parse_qos_values ()
void gst_message_parse_qos_stats ()
GstMessage * gst_message_new_toc ()
void gst_message_parse_toc ()
GstMessage * gst_message_new_reset_time ()
void gst_message_parse_reset_time ()
GstMessage * gst_message_new_stream_start ()
void gst_message_set_group_id ()
gboolean gst_message_parse_group_id ()
GstMessage * gst_message_new_stream_collection ()
void gst_message_parse_stream_collection ()
GstMessage * gst_message_new_structure_change ()
void gst_message_parse_structure_change ()
GstMessage * gst_message_new_request_state ()
void gst_message_parse_request_state ()
GstMessage * gst_message_new_stream_status ()
void gst_message_parse_stream_status ()
void gst_message_set_stream_status_object ()
const GValue * gst_message_get_stream_status_object ()
GstMessage * gst_message_new_progress ()
void gst_message_parse_progress ()
GstMessage * gst_message_new_need_context ()
gboolean gst_message_parse_context_type ()
GstMessage * gst_message_new_have_context ()
void gst_message_parse_have_context ()
GstMessage * gst_message_new_device_added ()
GstMessage * gst_message_new_device_removed ()
void gst_message_parse_device_added ()
void gst_message_parse_device_removed ()
GstMessage * gst_message_new_property_notify ()
void gst_message_parse_property_notify ()
GstMessage * gst_message_new_streams_selected ()
void gst_message_parse_streams_selected ()
void gst_message_streams_selected_add ()
guint gst_message_streams_selected_get_size ()
GstStream * gst_message_streams_selected_get_stream ()
GstMessage * gst_message_new_redirect ()
void gst_message_add_redirect_entry ()
void gst_message_parse_redirect_entry ()
gsize gst_message_get_num_redirect_entries ()

Object Hierarchy

    GBoxed
    ╰── GstMessage

Includes

#include <gst/gst.h>

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:

A GstElement usually posts messages on the bus provided by the parent container using gst_element_post_message().

Functions

GST_MESSAGE_SRC()

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

Get the object that posted message .

Parameters

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.

Parameters

message

a GstMessage

 

GST_MESSAGE_TIMESTAMP()

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

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

Parameters

message

a GstMessage

 

GST_MESSAGE_SEQNUM()

#define GST_MESSAGE_SEQNUM(message)     (GST_MESSAGE_CAST(message)->seqnum)

Get the sequence number of message .

Parameters

message

a GstMessage

 

GST_MESSAGE_TYPE()

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

Get the GstMessageType of message .

Parameters

message

a GstMessage

 

GST_MESSAGE_TYPE_IS_EXTENDED()

#define GST_MESSAGE_TYPE_IS_EXTENDED(message)       (!!(GST_MESSAGE_CAST(message)->type & GST_MESSAGE_EXTENDED))

Check if the message is in the extended message group

Parameters

message

a GstMessage

 

Since: 1.4


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 .

Parameters

message

a GstMessage

 

gst_message_type_to_quark ()

GQuark
gst_message_type_to_quark (GstMessageType type);

Get the unique quark for the given message type.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

msg

the message to copy

 

Returns

a new copy of msg .

MT safe.

[transfer full]


gst_message_get_structure ()

const GstStructure *
gst_message_get_structure (GstMessage *message);

Access the structure of the message.

Parameters

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.

[transfer none]


gst_message_make_writable()

#define         gst_message_make_writable(msg)  GST_MESSAGE_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (msg)))

Checks if a message is writable. If not, a writable copy is made and returned.

Parameters

msg

the message to make writable.

[transfer full]

Returns

a message (possibly a duplicate) that is writable.

MT safe.

[transfer full]


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 have the same sequence number unless that correspondence was made explicitly.

Parameters

message

A GstMessage.

 

Returns

The message's sequence number.

MT safe.


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.

Parameters

message

A GstMessage.

 

seqnum

A sequence number.

 

gst_message_has_name ()

gboolean
gst_message_has_name (GstMessage *message,
                      const gchar *name);

Checks if message has the given name . This function is usually used to check the name of a custom message.

Parameters

message

The GstMessage.

 

name

name to check

 

Returns

TRUE if name matches the name of the message structure.


gst_message_is_writable()

#define         gst_message_is_writable(msg)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (msg))

Tests if you can safely write into a message's structure or validly modify the seqnum and timestamp fields.

Parameters

msg

a GstMessage

 

gst_message_replace ()

gboolean
gst_message_replace (GstMessage **old_message,
                     GstMessage *new_message);

Modifies a pointer to a GstMessage to point to a different GstMessage. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old message is unreffed, the new one is reffed).

Either new_message or the GstMessage pointed to by old_message may be NULL.

Parameters

old_message

pointer to a pointer to a GstMessage to be replaced.

[inout][transfer full][nullable]

new_message

pointer to a GstMessage that will replace the message pointed to by old_message .

[allow-none][transfer none]

Returns

TRUE if new_message was different from old_message


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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

Returns

The new eos message.

MT safe.

[transfer full]


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 occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline.

Parameters

src

The object originating the message.

[transfer none][allow-none]

error

The GError for this message.

[transfer none]

debug

A debugging string.

 

Returns

the new error message.

MT safe.

[transfer full]


gst_message_new_error_with_details ()

GstMessage *
gst_message_new_error_with_details (GstObject *src,
                                    GError *error,
                                    const gchar *debug,
                                    GstStructure *details);

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

Parameters

src

The object originating the message.

[transfer none][allow-none]

error

The GError for this message.

[transfer none]

debug

A debugging string.

 

details

(allow-none): A GstStructure with details.

[transfer full]

Returns

the new error message.

[transfer full]

Since: 1.10


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.

Typical usage of this function might be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
...
switch (GST_MESSAGE_TYPE (msg)) {
  case GST_MESSAGE_ERROR: {
    GError *err = NULL;
    gchar *dbg_info = NULL;
    
    gst_message_parse_error (msg, &err, &dbg_info);
    g_printerr ("ERROR from element %s: %s\n",
        GST_OBJECT_NAME (msg->src), err->message);
    g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none");
    g_error_free (err);
    g_free (dbg_info);
    break;
  }
  ...
}
...

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_ERROR.

 

gerror

location for the GError.

[out][allow-none][transfer full]

debug

location for the debug message, or NULL.

[out][allow-none][transfer full]

gst_message_parse_error_details ()

void
gst_message_parse_error_details (GstMessage *message,
                                 const GstStructure **structure);

Returns the optional details structure, may be NULL if none. The returned structure must not be freed.

Parameters

message

The message object

 

structure

A pointer to the returned details.

[out]

Since: 1.10


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 .

Parameters

src

The object originating the message.

[transfer none][allow-none]

error

The GError for this message.

[transfer none]

debug

A debugging string.

 

Returns

the new warning message.

MT safe.

[transfer full]


gst_message_new_warning_with_details ()

GstMessage *
gst_message_new_warning_with_details (GstObject *src,
                                      GError *error,
                                      const gchar *debug,
                                      GstStructure *details);

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

Parameters

src

The object originating the message.

[transfer none][allow-none]

error

The GError for this message.

[transfer none]

debug

A debugging string.

 

details

(allow-none): A GstStructure with details.

[transfer full]

Returns

the new warning message.

[transfer full]

Since: 1.10


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_WARNING.

 

gerror

location for the GError.

[out][allow-none][transfer full]

debug

location for the debug message, or NULL.

[out][allow-none][transfer full]

gst_message_parse_warning_details ()

void
gst_message_parse_warning_details (GstMessage *message,
                                   const GstStructure **structure);

Returns the optional details structure, may be NULL if none The returned structure must not be freed.

Parameters

message

The message object

 

structure

A pointer to the returned details structure.

[out]

Since: 1.10


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 .

Parameters

src

The object originating the message.

[transfer none][allow-none]

error

The GError for this message.

[transfer none]

debug

A debugging string.

 

Returns

the new info message.

MT safe.

[transfer full]


gst_message_new_info_with_details ()

GstMessage *
gst_message_new_info_with_details (GstObject *src,
                                   GError *error,
                                   const gchar *debug,
                                   GstStructure *details);

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

Parameters

src

The object originating the message.

[transfer none][allow-none]

error

The GError for this message.

[transfer none]

debug

A debugging string.

 

details

(allow-none): A GstStructure with details.

[transfer full]

Returns

the new warning message.

[transfer full]

Since: 1.10


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_INFO.

 

gerror

location for the GError.

[out][allow-none][transfer full]

debug

location for the debug message, or NULL.

[out][allow-none][transfer full]

gst_message_parse_info_details ()

void
gst_message_parse_info_details (GstMessage *message,
                                const GstStructure **structure);

Returns the optional details structure, may be NULL if none The returned structure must not be freed.

Parameters

message

The message object

 

structure

A pointer to the returned details structure.

[out]

Since: 1.10


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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

tag_list

the tag list for the message.

[transfer full]

Returns

the new tag message.

MT safe.

[transfer full]


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.

Typical usage of this function might be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
...
switch (GST_MESSAGE_TYPE (msg)) {
  case GST_MESSAGE_TAG: {
    GstTagList *tags = NULL;
    
    gst_message_parse_tag (msg, &tags);
    g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
    handle_tags (tags);
    gst_tag_list_unref (tags);
    break;
  }
  ...
}
...

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_TAG.

 

tag_list

return location for the tag-list.

[out callee-allocates]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

percent

The buffering percent

 

Returns

The new buffering message.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_BUFFERING.

 

percent

Return location for the percent.

[out][allow-none]

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 .

Parameters

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

 

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 .

Parameters

message

A valid GstMessage of type GST_MESSAGE_BUFFERING.

 

mode

a buffering mode, or NULL.

[out][allow-none]

avg_in

the average input rate, or NULL.

[out][allow-none]

avg_out

the average output rate, or NULL.

[out][allow-none]

buffering_left

amount of buffering time left in milliseconds, or NULL.

[out][allow-none]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

oldstate

the previous state

 

newstate

the new (current) state

 

pending

the pending (target) state

 

Returns

the new state change message.

MT safe.

[transfer full]


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.

Typical usage of this function might be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
...
switch (GST_MESSAGE_TYPE (msg)) {
  case GST_MESSAGE_STATE_CHANGED: {
    GstState old_state, new_state;
    
    gst_message_parse_state_changed (msg, &old_state, &new_state, NULL);
    g_print ("Element %s changed state from %s to %s.\n",
        GST_OBJECT_NAME (msg->src),
        gst_element_state_get_name (old_state),
        gst_element_state_get_name (new_state));
    break;
  }
  ...
}
...

MT safe.

Parameters

message

a valid GstMessage of type GST_MESSAGE_STATE_CHANGED

 

oldstate

the previous state, or NULL.

[out][allow-none]

newstate

the new (current) state, or NULL.

[out][allow-none]

pending

the pending (target) state, or NULL.

[out][allow-none]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

Returns

the new state dirty message.

MT safe.

[transfer full]


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 .

Parameters

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.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_STEP_DONE.

 

format

result location for the format.

[out][allow-none]

amount

result location for the amount.

[out][allow-none]

rate

result location for the rate.

[out][allow-none]

flush

result location for the flush flag.

[out][allow-none]

intermediate

result location for the intermediate flag.

[out][allow-none]

duration

result location for the duration.

[out][allow-none]

eos

result location for the EOS flag.

[out][allow-none]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

clock

the clock it provides.

[transfer none]

ready

TRUE if the sender can provide a clock

 

Returns

the new provide clock message.

MT safe.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.

 

clock

a pointer to hold a clock object, or NULL.

[out][allow-none][transfer none]

ready

a pointer to hold the ready flag, or NULL.

[out][allow-none]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

clock

the clock that was lost.

[transfer none]

Returns

The new clock lost message.

MT safe.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_CLOCK_LOST.

 

clock

a pointer to hold the lost clock.

[out][allow-none][transfer none]

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 selects a new clock for the pipeline.

Parameters

src

The object originating the message.

[transfer none][allow-none]

clock

the new selected clock.

[transfer none]

Returns

The new new clock message.

MT safe.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_NEW_CLOCK.

 

clock

a pointer to hold the selected new clock.

[out][allow-none][transfer none]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

structure

the structure for the message. The message will take ownership of the structure.

[transfer full]

Returns

The new application message.

MT safe.

[transfer full]


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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

structure

The structure for the message. The message will take ownership of the structure.

[transfer full]

Returns

The new element message.

MT safe.

[transfer full]


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.

Parameters

type

The GstMessageType to distinguish messages

 

src

The object originating the message.

[transfer none][allow-none]

structure

the structure for the message. The message will take ownership of the structure.

[transfer full][allow-none]

Returns

The new message.

MT safe.

[transfer full]


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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

format

The format of the position being played

 

position

The position of the segment being played

 

Returns

the new segment start message.

MT safe.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_SEGMENT_START.

 

format

Result location for the format, or NULL.

[out][allow-none]

position

Result location for the position, or NULL.

[out][allow-none]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

format

The format of the position being done

 

position

The position of the segment being done

 

Returns

the new segment done message.

MT safe.

[transfer full]


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 done message.

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_SEGMENT_DONE.

 

format

Result location for the format, or NULL.

[out][allow-none]

position

Result location for the position, or NULL.

[out][allow-none]

gst_message_new_duration_changed ()

GstMessage *
gst_message_new_duration_changed (GstObject *src);

Create a new duration changed message. This message is posted by elements that know the duration of a stream when the duration changes. This message is received by bins and is used to calculate the total duration of a pipeline.

Parameters

src

The object originating the message.

[transfer none][allow-none]

Returns

The new duration-changed message.

MT safe.

[transfer full]


gst_message_new_latency ()

GstMessage *
gst_message_new_latency (GstObject *src);

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

Parameters

src

The object originating the message.

[transfer none][allow-none]

Returns

The new latency message.

MT safe.

[transfer full]


gst_message_new_async_start ()

GstMessage *
gst_message_new_async_start (GstObject *src);

This message is posted by elements when they start an ASYNC state change.

Parameters

src

The object originating the message.

[transfer none][allow-none]

Returns

The new async_start message.

MT safe.

[transfer full]


gst_message_new_async_done ()

GstMessage *
gst_message_new_async_done (GstObject *src,
                            GstClockTime running_time);

The message is posted when elements completed an ASYNC state change. running_time contains the time of the desired running_time when this elements goes to PLAYING. A value of GST_CLOCK_TIME_NONE for running_time means that the element has no clock interaction and thus doesn't care about the running_time of the pipeline.

Parameters

src

The object originating the message.

[transfer none][allow-none]

running_time

the desired running_time

 

Returns

The new async_done message.

MT safe.

[transfer full]


gst_message_parse_async_done ()

void
gst_message_parse_async_done (GstMessage *message,
                              GstClockTime *running_time);

Extract the running_time from the async_done message.

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_ASYNC_DONE.

 

running_time

Result location for the running_time or NULL.

[out][allow-none]

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 emitted, the application can queue a new step operation in the element.

Parameters

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.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_STEP_DONE.

 

active

result location for the active flag.

[out][allow-none]

format

result location for the format.

[out][allow-none]

amount

result location for the amount.

[out][allow-none]

rate

result location for the rate.

[out][allow-none]

flush

result location for the flush flag.

[out][allow-none]

intermediate

result location for the intermediate flag.

[out][allow-none]

gst_message_new_qos ()

GstMessage *
gst_message_new_qos (GstObject *src,
                     gboolean live,
                     guint64 running_time,
                     guint64 stream_time,
                     guint64 timestamp,
                     guint64 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).

running_time , stream_time , timestamp , duration should be set to the 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.

Parameters

src

The object originating the message.

 

live

if the message was generated by a live element

 

running_time

the running time of the buffer that generated the message

 

stream_time

the stream time of the buffer that generated the message

 

timestamp

the timestamps of the buffer that generated the message

 

duration

the duration of the buffer that generated the message

 

Returns

The new qos message.

MT safe.

[transfer full]


gst_message_set_qos_values ()

void
gst_message_set_qos_values (GstMessage *message,
                            gint64 jitter,
                            gdouble proportion,
                            gint quality);

Set the QoS values that have been calculated/analysed from the QoS data

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_QOS.

 

jitter

The difference of the running-time against the deadline.

 

proportion

Long term prediction of the ideal rate relative to normal rate to get optimal quality.

 

quality

An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000.

 

gst_message_set_qos_stats ()

void
gst_message_set_qos_stats (GstMessage *message,
                           GstFormat format,
                           guint64 processed,
                           guint64 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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_QOS.

 

format

Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples).

 

processed

Total number of units correctly processed since the last state change to READY or a flushing operation.

 

dropped

Total number of units dropped since the last state change to READY or a flushing operation.

 

gst_message_parse_qos ()

void
gst_message_parse_qos (GstMessage *message,
                       gboolean *live,
                       guint64 *running_time,
                       guint64 *stream_time,
                       guint64 *timestamp,
                       guint64 *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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_QOS.

 

live

if the message was generated by a live element.

[out][allow-none]

running_time

the running time of the buffer that generated the message.

[out][allow-none]

stream_time

the stream time of the buffer that generated the message.

[out][allow-none]

timestamp

the timestamps of the buffer that generated the message.

[out][allow-none]

duration

the duration of the buffer that generated the message.

[out][allow-none]

gst_message_parse_qos_values ()

void
gst_message_parse_qos_values (GstMessage *message,
                              gint64 *jitter,
                              gdouble *proportion,
                              gint *quality);

Extract the QoS values that have been calculated/analysed from the QoS data

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_QOS.

 

jitter

The difference of the running-time against the deadline.

[out][allow-none]

proportion

Long term prediction of the ideal rate relative to normal rate to get optimal quality.

[out][allow-none]

quality

An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000.

[out][allow-none]

gst_message_parse_qos_stats ()

void
gst_message_parse_qos_stats (GstMessage *message,
                             GstFormat *format,
                             guint64 *processed,
                             guint64 *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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_QOS.

 

format

Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples).

[out][allow-none]

processed

Total number of units correctly processed since the last state change to READY or a flushing operation.

[out][allow-none]

dropped

Total number of units dropped since the last state change to READY or a flushing operation.

[out][allow-none]

gst_message_new_toc ()

GstMessage *
gst_message_new_toc (GstObject *src,
                     GstToc *toc,
                     gboolean updated);

Create a new TOC message. The message is posted by elements that discovered or updated a TOC.

Parameters

src

the object originating the message.

 

toc

GstToc structure for the message.

[transfer none]

updated

whether TOC was updated or not.

 

Returns

a new TOC message.

MT safe.

[transfer full]


gst_message_parse_toc ()

void
gst_message_parse_toc (GstMessage *message,
                       GstToc **toc,
                       gboolean *updated);

Extract the TOC from the GstMessage. The TOC returned in the output argument is a copy; the caller must free it with gst_toc_unref() when done.

MT safe.

Parameters

message

a valid GstMessage of type GST_MESSAGE_TOC.

 

toc

return location for the TOC.

[out][transfer full]

updated

return location for the updated flag.

[out]

gst_message_new_reset_time ()

GstMessage *
gst_message_new_reset_time (GstObject *src,
                            GstClockTime running_time);

This message is posted when the pipeline running-time should be reset to running_time , like after a flushing seek.

Parameters

src

The object originating the message.

[transfer none][allow-none]

running_time

the requested running-time

 

Returns

The new reset_time message.

MT safe.

[transfer full]


gst_message_parse_reset_time ()

void
gst_message_parse_reset_time (GstMessage *message,
                              GstClockTime *running_time);

Extract the running-time from the RESET_TIME message.

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_RESET_TIME.

 

running_time

Result location for the running_time or NULL.

[out][allow-none]

gst_message_new_stream_start ()

GstMessage *
gst_message_new_stream_start (GstObject *src);

Create a new stream_start message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the STREAM_START message to the application if all sinks have posted an STREAM_START message.

Parameters

src

The object originating the message.

[transfer none][allow-none]

Returns

The new stream_start message.

MT safe.

[transfer full]


gst_message_set_group_id ()

void
gst_message_set_group_id (GstMessage *message,
                          guint group_id);

Sets the group id on the stream-start message.

All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example.

MT safe.

Parameters

message

the message

 

group_id

the group id

 

Since: 1.2


gst_message_parse_group_id ()

gboolean
gst_message_parse_group_id (GstMessage *message,
                            guint *group_id);

Extract the group from the STREAM_START message.

Parameters

message

A valid GstMessage of type GST_MESSAGE_STREAM_START.

 

group_id

Result location for the group id or NULL.

[out][allow-none]

Returns

TRUE if the message had a group id set, FALSE otherwise

MT safe.

Since: 1.2


gst_message_new_stream_collection ()

GstMessage *
gst_message_new_stream_collection (GstObject *src,
                                   GstStreamCollection *collection);

Creates a new stream-collection message. The message is used to announce new GstStreamCollection

Parameters

src

The GstObject that created the message

 

collection

The GstStreamCollection.

[transfer none]

Returns

a newly allocated GstMessage

Since: 1.10


gst_message_parse_stream_collection ()

void
gst_message_parse_stream_collection (GstMessage *message,
                                     GstStreamCollection **collection);

Parses a stream-collection message.

Parameters

message

a GstMessage of type GST_MESSAGE_STREAM_COLLECTION

 

collection

A location where to store a pointer to the GstStreamCollection, or NULL.

[out][allow-none][transfer full]

Since: 1.10


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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

type

The change type.

 

owner

The owner element of src .

[transfer none]

busy

Whether the structure change is busy.

 

Returns

the new structure change message.

MT safe.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.

 

type

A pointer to hold the change type.

[out]

owner

The owner element of the message source.

[out][allow-none][transfer none]

busy

a pointer to hold whether the change is in progress or has been completed.

[out][allow-none]

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.

Parameters

src

The object originating the message.

[transfer none][allow-none]

state

The new requested state

 

Returns

the new request state message.

MT safe.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_REQUEST_STATE.

 

state

Result location for the requested state or NULL.

[out][allow-none]

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.

Parameters

src

The object originating the message.

 

type

The stream status type.

 

owner

the owner element of src .

[transfer none]

Returns

the new stream status message.

MT safe.

[transfer full]


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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_STREAM_STATUS.

 

type

A pointer to hold the status type.

[out]

owner

The owner element of the message source.

[out][transfer none]

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.

Parameters

message

A valid GstMessage of type GST_MESSAGE_STREAM_STATUS.

 

object

the object controlling the streaming

 

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 .

Parameters

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.


gst_message_new_progress ()

GstMessage *
gst_message_new_progress (GstObject *src,
                          GstProgressType type,
                          const gchar *code,
                          const gchar *text);

Progress messages are posted by elements when they use an asynchronous task to perform actions triggered by a state change.

code contains a well defined string describing the action. text should contain a user visible string detailing the current action.

Parameters

src

The object originating the message.

 

type

a GstProgressType

 

code

a progress code

 

text

free, user visible text describing the progress

 

Returns

The new qos message.

[transfer full]


gst_message_parse_progress ()

void
gst_message_parse_progress (GstMessage *message,
                            GstProgressType *type,
                            gchar **code,
                            gchar **text);

Parses the progress type , code and text .

Parameters

message

A valid GstMessage of type GST_MESSAGE_PROGRESS.

 

type

location for the type.

[out][allow-none]

code

location for the code.

[out][allow-none][transfer full]

text

location for the text.

[out][allow-none][transfer full]

gst_message_new_need_context ()

GstMessage *
gst_message_new_need_context (GstObject *src,
                              const gchar *context_type);

This message is posted when an element needs a specific GstContext.

Parameters

src

The object originating the message.

[transfer none][allow-none]

context_type

The context type that is needed

 

Returns

The new need-context message.

MT safe.

[transfer full]

Since: 1.2


gst_message_parse_context_type ()

gboolean
gst_message_parse_context_type (GstMessage *message,
                                const gchar **context_type);

Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message.

Parameters

message

a GST_MESSAGE_NEED_CONTEXT type message

 

context_type

the context type, or NULL.

[out][allow-none]

Returns

a gboolean indicating if the parsing succeeded.

Since: 1.2


gst_message_new_have_context ()

GstMessage *
gst_message_new_have_context (GstObject *src,
                              GstContext *context);

This message is posted when an element has a new local GstContext.

Parameters

src

The object originating the message.

[transfer none][allow-none]

context

the context.

[transfer full]

Returns

The new have-context message.

MT safe.

[transfer full]

Since: 1.2


gst_message_parse_have_context ()

void
gst_message_parse_have_context (GstMessage *message,
                                GstContext **context);

Extract the context from the HAVE_CONTEXT message.

MT safe.

Parameters

message

A valid GstMessage of type GST_MESSAGE_HAVE_CONTEXT.

 

context

Result location for the context or NULL.

[out][transfer full][allow-none]

Since: 1.2


gst_message_new_device_added ()

GstMessage *
gst_message_new_device_added (GstObject *src,
                              GstDevice *device);

Creates a new device-added message. The device-added message is produced by GstDeviceProvider or a GstDeviceMonitor. They announce the appearance of monitored devices.

Parameters

src

The GstObject that created the message

 

device

The new GstDevice.

[transfer none]

Returns

a newly allocated GstMessage

Since: 1.4


gst_message_new_device_removed ()

GstMessage *
gst_message_new_device_removed (GstObject *src,
                                GstDevice *device);

Creates a new device-removed message. The device-removed message is produced by GstDeviceProvider or a GstDeviceMonitor. They announce the disappearance of monitored devices.

Parameters

src

The GstObject that created the message

 

device

The removed GstDevice.

[transfer none]

Returns

a newly allocated GstMessage

Since: 1.4


gst_message_parse_device_added ()

void
gst_message_parse_device_added (GstMessage *message,
                                GstDevice **device);

Parses a device-added message. The device-added message is produced by GstDeviceProvider or a GstDeviceMonitor. It announces the appearance of monitored devices.

Parameters

message

a GstMessage of type GST_MESSAGE_DEVICE_ADDED

 

device

A location where to store a pointer to the new GstDevice, or NULL.

[out][allow-none][transfer full]

Since: 1.4


gst_message_parse_device_removed ()

void
gst_message_parse_device_removed (GstMessage *message,
                                  GstDevice **device);

Parses a device-removed message. The device-removed message is produced by GstDeviceProvider or a GstDeviceMonitor. It announces the disappearance of monitored devices.

Parameters

message

a GstMessage of type GST_MESSAGE_DEVICE_REMOVED

 

device

A location where to store a pointer to the removed GstDevice, or NULL.

[out][allow-none][transfer full]

Since: 1.4


gst_message_new_property_notify ()

GstMessage *
gst_message_new_property_notify (GstObject *src,
                                 const gchar *property_name,
                                 GValue *val);

Parameters

src

The GstObject whose property changed (may or may not be a GstElement)

 

property_name

name of the property that changed

 

val

new property value, or NULL.

[allow-none][transfer full]

Returns

a newly allocated GstMessage

Since: 1.10


gst_message_parse_property_notify ()

void
gst_message_parse_property_notify (GstMessage *message,
                                   GstObject **object,
                                   const gchar **property_name,
                                   const GValue **property_value);

Parses a property-notify message. These will be posted on the bus only when set up with gst_element_add_property_notify_watch() or gst_element_add_property_deep_notify_watch().

Parameters

message

a GstMessage of type GST_MESSAGE_PROPERTY_NOTIFY

 

object

location where to store a pointer to the object whose property got changed, or NULL.

[out][allow-none][transfer none]

property_name

return location for the name of the property that got changed, or NULL.

[out][allow-none]

property_value

return location for the new value of the property that got changed, or NULL. This will only be set if the property notify watch was told to include the value when it was set up.

[out][allow-none]

Since: 1.10


gst_message_new_streams_selected ()

GstMessage *
gst_message_new_streams_selected (GstObject *src,
                                  GstStreamCollection *collection);

Creates a new steams-selected message. The message is used to announce that an array of streams has been selected. This is generally in response to a GST_EVENT_SELECT_STREAMS event, or when an element (such as decodebin3) makes an initial selection of streams.

The message also contains the GstStreamCollection to which the various streams belong to.

Users of gst_message_new_streams_selected() can add the selected streams with gst_message_streams_selected_add().

Parameters

src

The GstObject that created the message

 

collection

The GstStreamCollection.

[transfer none]

Returns

a newly allocated GstMessage

Since: 1.10


gst_message_parse_streams_selected ()

void
gst_message_parse_streams_selected (GstMessage *message,
                                    GstStreamCollection **collection);

Parses a streams-selected message.

Parameters

message

a GstMessage of type GST_MESSAGE_STREAMS_SELECTED

 

collection

A location where to store a pointer to the GstStreamCollection, or NULL.

[out][allow-none][transfer full]

Since: 1.10


gst_message_streams_selected_add ()

void
gst_message_streams_selected_add (GstMessage *message,
                                  GstStream *stream);

Adds the stream to the message .

Parameters

message

a GstMessage of type GST_MESSAGE_STREAMS_SELECTED

 

stream

a GstStream to add to message .

[transfer none]

Since: 1.10


gst_message_streams_selected_get_size ()

guint
gst_message_streams_selected_get_size (GstMessage *message);

Returns the number of streams contained in the message .

Parameters

Returns

The number of streams contained within.

Since: 1.10


gst_message_streams_selected_get_stream ()

GstStream *
gst_message_streams_selected_get_stream
                               (GstMessage *message,
                                guint idx);

Retrieves the GstStream with index index from the message .

Parameters

message

a GstMessage of type GST_MESSAGE_STREAMS_SELECTED

 

idx

Index of the stream to retrieve

 

Returns

A GstStream.

[transfer full]

Since: 1.10


gst_message_new_redirect ()

GstMessage *
gst_message_new_redirect (GstObject *src,
                          const gchar *location,
                          GstTagList *tag_list,
                          const GstStructure *entry_struct);

Creates a new redirect message and adds a new entry to it. Redirect messages are posted when an element detects that the actual data has to be retrieved from a different location. This is useful if such a redirection cannot be handled inside a source element, for example when HTTP 302/303 redirects return a non-HTTP URL.

The redirect message can hold multiple entries. The first one is added when the redirect message is created, with the given location, tag_list, entry_struct arguments. Use gst_message_add_redirect_entry() to add more entries.

Each entry has a location, a tag list, and a structure. All of these are optional. The tag list and structure are useful for additional metadata, such as bitrate statistics for the given location.

By default, message recipients should treat entries in the order they are stored. The recipient should therefore try entry #0 first, and if this entry is not acceptable or working, try entry #1 etc. Senders must make sure that they add entries in this order. However, recipients are free to ignore the order and pick an entry that is "best" for them. One example would be a recipient that scans the entries for the one with the highest bitrate tag.

The specified location string is copied. However, ownership over the tag list and structure are transferred to the message.

Parameters

src

The GstObject whose property changed (may or may not be a GstElement)

 

location

location string for the new entry.

[transfer none]

tag_list

tag list for the new entry.

[transfer full][allow-none]

entry_struct

structure for the new entry.

[transfer full][allow-none]

Returns

a newly allocated GstMessage

Since: 1.10


gst_message_add_redirect_entry ()

void
gst_message_add_redirect_entry (GstMessage *message,
                                const gchar *location,
                                GstTagList *tag_list,
                                const GstStructure *entry_struct);

Creates and appends a new entry.

The specified location string is copied. However, ownership over the tag list and structure are transferred to the message.

Parameters

message

a GstMessage of type GST_MESSAGE_REDIRECT

 

location

location string for the new entry.

[transfer none]

tag_list

tag list for the new entry.

[transfer full][allow-none]

entry_struct

structure for the new entry.

[transfer full][allow-none]

Since: 1.10


gst_message_parse_redirect_entry ()

void
gst_message_parse_redirect_entry (GstMessage *message,
                                  gsize entry_index,
                                  const gchar **location,
                                  GstTagList **tag_list,
                                  const GstStructure **entry_struct);

Parses the location and/or structure from the entry with the given index. The index must be between 0 and gst_message_get_num_redirect_entries() - 1. Returned pointers are valid for as long as this message exists.

Parameters

message

a GstMessage of type GST_MESSAGE_REDIRECT

 

entry_index

index of the entry to parse

 

location

return location for the pointer to the entry's location string, or NULL.

[out][transfer none][allow-none]

tag_list

return location for the pointer to the entry's tag list, or NULL.

[out][transfer none][allow-none]

entry_struct

return location for the pointer to the entry's structure, or NULL.

[out][transfer none][allow-none]

Since: 1.10


gst_message_get_num_redirect_entries ()

gsize
gst_message_get_num_redirect_entries (GstMessage *message);

Parameters

message

a GstMessage of type GST_MESSAGE_REDIRECT

 

Returns

the number of entries stored in the message

Since: 1.10

Types and Values

struct GstMessage

struct GstMessage {
  GstMiniObject   mini_object;

  GstMessageType  type;
  guint64         timestamp;
  GstObject      *src;
  guint32         seqnum;
};

A GstMessage.

Members

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

 

guint32 seqnum;

the sequence number of the message

 

enum GstMessageType

The different message types that are available.

Members

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 occurred. When 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 occurred.

 

GST_MESSAGE_INFO

an info message occurred

 

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 stepping operation finished.

 

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. The application should set the pipeline to PAUSED and back to PLAYING when this message is received.

 

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_CHANGED

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 application should recalculate and distribute a new latency.

 

GST_MESSAGE_ASYNC_START

Posted by elements when they start an ASYNC GstStateChange. This message is not forwarded to the application but is used internally.

 

GST_MESSAGE_ASYNC_DONE

Posted by elements when they complete an ASYNC GstStateChange. The application will only receive this message from the toplevel pipeline.

 

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.

 

GST_MESSAGE_STEP_START

A stepping operation was started.

 

GST_MESSAGE_QOS

A buffer was dropped or an element changed its processing strategy for Quality of Service reasons.

 

GST_MESSAGE_PROGRESS

A progress message.

 

GST_MESSAGE_TOC

A new table of contents (TOC) was found or previously found TOC was updated.

 

GST_MESSAGE_RESET_TIME

Message to request resetting the pipeline's running time from the pipeline. This is an internal message which applications will likely never receive.

 

GST_MESSAGE_STREAM_START

Message indicating start of a new stream. Useful e.g. when using playbin in gapless playback mode, to get notified when the next title actually starts playing (which will be some time after the URI for the next title has been set).

 

GST_MESSAGE_NEED_CONTEXT

Message indicating that an element wants a specific context (Since 1.2)

 

GST_MESSAGE_HAVE_CONTEXT

Message indicating that an element created a context (Since 1.2)

 

GST_MESSAGE_EXTENDED

Message is an extended message type (see below). These extended message IDs can't be used directly with mask-based API like gst_bus_poll() or gst_bus_timed_pop_filtered(), but you can still filter for GST_MESSAGE_EXTENDED and then check the result for the specific type. (Since 1.4)

 

GST_MESSAGE_DEVICE_ADDED

Message indicating a GstDevice was added to a GstDeviceProvider (Since 1.4)

 

GST_MESSAGE_DEVICE_REMOVED

Message indicating a GstDevice was removed from a GstDeviceProvider (Since 1.4)

 

GST_MESSAGE_PROPERTY_NOTIFY

Message indicating a GObject property has changed (Since 1.10)

 

GST_MESSAGE_STREAM_COLLECTION

Message indicating a new GstStreamCollection is available (Since 1.10)

 

GST_MESSAGE_STREAMS_SELECTED

Message indicating the active selection of GstStreams has changed (Since 1.10)

 

GST_MESSAGE_REDIRECT

Message indicating to request the application to try to play the given URL(s). Useful if for example a HTTP 302/303 response is received with a non-HTTP URL inside. (Since 1.10)

 

GST_MESSAGE_ANY

mask for all of the above messages.

 

enum GstStructureChangeType

The type of a GST_MESSAGE_STRUCTURE_CHANGE.

Members

GST_STRUCTURE_CHANGE_TYPE_PAD_LINK

Pad linking is starting or done.

 

GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK

Pad unlinking is starting or done.

 

enum GstStreamStatusType

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

Members

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

 

enum GstProgressType

The type of a GST_MESSAGE_PROGRESS. The progress messages inform the application of the status of asynchronous tasks.

Members

GST_PROGRESS_TYPE_START

A new task started.

 

GST_PROGRESS_TYPE_CONTINUE

A task completed and a new one continues.

 

GST_PROGRESS_TYPE_COMPLETE

A task completed.

 

GST_PROGRESS_TYPE_CANCELED

A task was canceled.

 

GST_PROGRESS_TYPE_ERROR

A task caused an error. An error message is also posted on the bus.

 
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.