GstMessage

GstMessage — Lightweight objects to signal the application of pipeline events

Synopsis


#include <gst/gst.h>


            GstMessage;
enum        GstMessageType;
#define     GST_MESSAGE_COND                (message)
#define     GST_MESSAGE_GET_LOCK            (message)
#define     GST_MESSAGE_LOCK                (message)
#define     GST_MESSAGE_SIGNAL              (message)
#define     GST_MESSAGE_SRC                 (message)
#define     GST_MESSAGE_TIMESTAMP           (message)
#define     GST_MESSAGE_TRACE_NAME
#define     GST_MESSAGE_TYPE                (message)
#define     GST_MESSAGE_UNLOCK              (message)
#define     GST_MESSAGE_WAIT                (message)
#define     gst_message_copy                (msg)
const GstStructure* gst_message_get_structure
                                            (GstMessage *message);
#define     gst_message_make_writable       (msg)
#define     gst_message_new_application     (src, str)
GstMessage* gst_message_new_custom          (GstMessageType type,
                                             GstObject *src,
                                             GstStructure *structure);
GstMessage* gst_message_new_eos             (GstObject *src);
GstMessage* gst_message_new_error           (GstObject *src,
                                             GError *error,
                                             gchar *debug);
GstMessage* gst_message_new_segment_done    (GstObject *src,
                                             GstClockTime timestamp);
GstMessage* gst_message_new_segment_start   (GstObject *src,
                                             GstClockTime timestamp);
GstMessage* gst_message_new_state_changed   (GstObject *src,
                                             GstState old_state,
                                             GstState new_state);
GstMessage* gst_message_new_tag             (GstObject *src,
                                             GstTagList *tag_list);
GstMessage* gst_message_new_warning         (GstObject *src,
                                             GError *error,
                                             gchar *debug);
void        gst_message_parse_error         (GstMessage *message,
                                             GError **gerror,
                                             gchar **debug);
void        gst_message_parse_segment_done  (GstMessage *message,
                                             GstClockTime *timestamp);
void        gst_message_parse_segment_start (GstMessage *message,
                                             GstClockTime *timestamp);
void        gst_message_parse_state_changed (GstMessage *message,
                                             GstState *old_state,
                                             GstState *new_state);
void        gst_message_parse_tag           (GstMessage *message,
                                             GstTagList **tag_list);
void        gst_message_parse_warning       (GstMessage *message,
                                             GError **gerror,
                                             gchar **debug);
#define     gst_message_ref                 (msg)
GType       gst_message_type_get_type       (void);
#define     gst_message_unref               (msg)


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.

Details

GstMessage

typedef struct {
  GstMiniObject mini_object;

  GMutex *lock;                 /* lock and cond for async delivery */
  GCond *cond;

  GstMessageType type;
  guint64 timestamp;
  GstObject *src;

  GstStructure *structure;
} 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_STEP_DONE         = (1 << 7),
  GST_MESSAGE_NEW_CLOCK         = (1 << 8),
  GST_MESSAGE_STRUCTURE_CHANGE  = (1 << 9),
  GST_MESSAGE_STREAM_STATUS     = (1 << 10),
  GST_MESSAGE_APPLICATION       = (1 << 11),
  GST_MESSAGE_SEGMENT_START     = (1 << 12),
  GST_MESSAGE_SEGMENT_DONE      = (1 << 13),
  GST_MESSAGE_ANY               = 0xffffffff
} GstMessageType;

GST_MESSAGE_UNKNOWN an undefined message
GST_MESSAGE_EOS end-of-stream reached in a pipeline
GST_MESSAGE_ERROR an error occured
GST_MESSAGE_WARNING a warning occured.
GST_MESSAGE_INFO an info message occured
GST_MESSAGE_TAG a tag was found.
GST_MESSAGE_BUFFERING the pipeline is buffering
GST_MESSAGE_STATE_CHANGED a state change happened
GST_MESSAGE_STEP_DONE a framestep finished.
GST_MESSAGE_NEW_CLOCK a new clock was selected in the pipeline
GST_MESSAGE_STRUCTURE_CHANGE the structure of the pipeline changed.
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_SEGMENT_START pipeline started playback of a segment.
GST_MESSAGE_SEGMENT_DONE pipeline completed playback of a segment.
GST_MESSAGE_ANY mask for all of the above messages.

GST_MESSAGE_COND()

#define GST_MESSAGE_COND(message)	(GST_MESSAGE(message)->cond)

message :

GST_MESSAGE_GET_LOCK()

#define GST_MESSAGE_GET_LOCK(message)	(GST_MESSAGE(message)->lock)

message :

GST_MESSAGE_LOCK()

#define GST_MESSAGE_LOCK(message)	g_mutex_lock(GST_MESSAGE_GET_LOCK(message))

message :

GST_MESSAGE_SIGNAL()

#define GST_MESSAGE_SIGNAL(message)	g_cond_signal(GST_MESSAGE_COND(message))

message :

GST_MESSAGE_SRC()

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

message :

GST_MESSAGE_TIMESTAMP()

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

message :

GST_MESSAGE_TRACE_NAME

#define GST_MESSAGE_TRACE_NAME	"GstMessage"


GST_MESSAGE_TYPE()

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

message :

GST_MESSAGE_UNLOCK()

#define GST_MESSAGE_UNLOCK(message)	g_mutex_unlock(GST_MESSAGE_GET_LOCK(message))

message :

GST_MESSAGE_WAIT()

#define GST_MESSAGE_WAIT(message)	g_cond_wait(GST_MESSAGE_COND(message),GST_MESSAGE_GET_LOCK(message))

message :

gst_message_copy()

#define         gst_message_copy(msg)		GST_MESSAGE (gst_mini_object_copy (GST_MINI_OBJECT (msg)))

msg :

gst_message_get_structure ()

const GstStructure* gst_message_get_structure
                                            (GstMessage *message);

Access the structure of the message.

message : The GstMessage.
Returns : The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. MT safe.

gst_message_make_writable()

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

msg :

gst_message_new_application()

#define     gst_message_new_application(src, str)

Create a new application-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.

src : The object originating the message.
str : The structure for the message. The message will take ownership of the structure.

gst_message_new_custom ()

GstMessage* gst_message_new_custom          (GstMessageType type,
                                             GstObject *src,
                                             GstStructure *structure);

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

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

gst_message_new_eos ()

GstMessage* gst_message_new_eos             (GstObject *src);

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

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

gst_message_new_error ()

GstMessage* gst_message_new_error           (GstObject *src,
                                             GError *error,
                                             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.

src : The object originating the message.
error : The GError for this message.
debug : A debugging string for something or other.
Returns : The new error message. MT safe.

gst_message_new_segment_done ()

GstMessage* gst_message_new_segment_done    (GstObject *src,
                                             GstClockTime timestamp);

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

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

gst_message_new_segment_start ()

GstMessage* gst_message_new_segment_start   (GstObject *src,
                                             GstClockTime timestamp);

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

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

gst_message_new_state_changed ()

GstMessage* gst_message_new_state_changed   (GstObject *src,
                                             GstState old_state,
                                             GstState new_state);

src :
old_state :
new_state :
Returns :

gst_message_new_tag ()

GstMessage* gst_message_new_tag             (GstObject *src,
                                             GstTagList *tag_list);

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

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

gst_message_new_warning ()

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

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

src : The object originating the message.
error : The GError for this message.
debug : A debugging string for something or other.
Returns : The new warning message. MT safe.

gst_message_parse_error ()

void        gst_message_parse_error         (GstMessage *message,
                                             GError **gerror,
                                             gchar **debug);

Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_ERROR.
gerror :
debug :

gst_message_parse_segment_done ()

void        gst_message_parse_segment_done  (GstMessage *message,
                                             GstClockTime *timestamp);

Extracts the timestamp from the segment done message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_SEGMENT_DONE.
timestamp :

gst_message_parse_segment_start ()

void        gst_message_parse_segment_start (GstMessage *message,
                                             GstClockTime *timestamp);

Extracts the timestamp from the segment start message.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_SEGMENT_START.
timestamp :

gst_message_parse_state_changed ()

void        gst_message_parse_state_changed (GstMessage *message,
                                             GstState *old_state,
                                             GstState *new_state);

Extracts the old and new states from the GstMessage.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_STATE_CHANGED.
old_state :
new_state :

gst_message_parse_tag ()

void        gst_message_parse_tag           (GstMessage *message,
                                             GstTagList **tag_list);

Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_TAG.
tag_list :

gst_message_parse_warning ()

void        gst_message_parse_warning       (GstMessage *message,
                                             GError **gerror,
                                             gchar **debug);

Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.

MT safe.

message : A valid GstMessage of type GST_MESSAGE_WARNING.
gerror :
debug :

gst_message_ref()

#define         gst_message_ref(msg)		GST_MESSAGE (gst_mini_object_ref (GST_MINI_OBJECT (msg)))

msg :

gst_message_type_get_type ()

GType       gst_message_type_get_type       (void);

Returns :

gst_message_unref()

#define         gst_message_unref(msg)		gst_mini_object_unref (GST_MINI_OBJECT (msg))

msg :

See Also

GstBus,GstMiniObject