![]() |
![]() |
![]() |
GStreamer 0.10 Core Reference Manual | ![]() |
---|
GstMessageGstMessage — Lightweight objects to signal the application of pipeline events |
#include <gst/gst.h> GstMessage; enum GstMessageType; #define GST_MESSAGE_SRC (message) #define GST_MESSAGE_TIMESTAMP (message) #define GST_MESSAGE_TYPE (message) #define GST_MESSAGE_TRACE_NAME GQuark gst_message_type_to_quark (GstMessageType type); const gchar* gst_message_type_get_name (GstMessageType type); #define gst_message_copy (msg) const GstStructure* gst_message_get_structure (GstMessage *message); #define gst_message_make_writable (msg) GstMessage* gst_message_new_application (GstObject *src, GstStructure *structure); GstMessage* gst_message_new_clock_provide (GstObject *src, GstClock *clock, gboolean ready); GstMessage* gst_message_new_clock_lost (GstObject *src, GstClock *clock); GstMessage* gst_message_new_custom (GstMessageType type, GstObject *src, GstStructure *structure); GstMessage* gst_message_new_element (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_new_clock (GstObject *src, GstClock *clock); GstMessage* gst_message_new_segment_done (GstObject *src, GstFormat format, gint64 position); GstMessage* gst_message_new_segment_start (GstObject *src, GstFormat format, gint64 position); GstMessage* gst_message_new_state_changed (GstObject *src, GstState oldstate, GstState newstate, GstState pending); GstMessage* gst_message_new_tag (GstObject *src, GstTagList *tag_list); GstMessage* gst_message_new_warning (GstObject *src, GError *error, gchar *debug); GstMessage* gst_message_new_duration (GstObject *src, GstFormat format, gint64 duration); GstMessage* gst_message_new_state_dirty (GstObject *src); void gst_message_parse_clock_lost (GstMessage *message, GstClock **clock); void gst_message_parse_clock_provide (GstMessage *message, GstClock **clock, gboolean *ready); void gst_message_parse_error (GstMessage *message, GError **gerror, gchar **debug); void gst_message_parse_new_clock (GstMessage *message, GstClock **clock); void gst_message_parse_segment_done (GstMessage *message, GstFormat *format, gint64 *position); void gst_message_parse_segment_start (GstMessage *message, GstFormat *format, gint64 *position); void gst_message_parse_state_changed (GstMessage *message, GstState *oldstate, GstState *newstate, GstState *pending); void gst_message_parse_tag (GstMessage *message, GstTagList **tag_list); void gst_message_parse_warning (GstMessage *message, GError **gerror, gchar **debug); void gst_message_parse_duration (GstMessage *message, GstFormat *format, gint64 *duration); #define gst_message_ref (msg) #define gst_message_unref (msg)
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()
.
Last reviewed on 2005-11-09 (0.9.4)
typedef struct { GstMiniObject mini_object; GstMessageType type; guint64 timestamp; GstObject *src; GstStructure *structure; } GstMessage;
A GstMessage.
GstMiniObject mini_object ; |
the parent structure |
GstMessageType type ; |
the GstMessageType of the message |
guint64 timestamp ; |
the timestamp of the message |
GstObject *src ; |
the src of the message |
GstStructure *structure ; |
the GstStructure containing the message info. |
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_ANY = 0xffffffff } GstMessageType;
The different message types that are available.
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_STATE_DIRTY |
an element changed state in a streaming thread |
GST_MESSAGE_STEP_DONE |
a framestep finished. |
GST_MESSAGE_CLOCK_PROVIDE |
an element notifies its capability of providing a clock. |
GST_MESSAGE_CLOCK_LOST |
The current clock as selected by the pipeline became unusable. The pipeline will select a new clock on the next PLAYING state change. |
GST_MESSAGE_NEW_CLOCK |
a new clock was selected in the pipeline |
GST_MESSAGE_STRUCTURE_CHANGE |
the structure of the pipeline changed. |
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. |
GST_MESSAGE_SEGMENT_DONE |
pipeline completed playback of a segment. |
GST_MESSAGE_DURATION |
The duration of a pipeline changed. |
GST_MESSAGE_ANY |
mask for all of the above messages. |
#define GST_MESSAGE_SRC(message) (GST_MESSAGE(message)->src)
Get the object that posted message
.
message : |
a GstMessage |
#define GST_MESSAGE_TIMESTAMP(message) (GST_MESSAGE(message)->timestamp)
Get the timestamp of message
. This is the timestamp when the message
was created.
message : |
a GstMessage |
#define GST_MESSAGE_TYPE(message) (GST_MESSAGE(message)->type)
Get the GstMessageType of message
.
message : |
a GstMessage |
#define GST_MESSAGE_TRACE_NAME "GstMessage"
The name used for memory allocation tracing
GQuark gst_message_type_to_quark (GstMessageType type);
Get the unique quark for the given message type.
type : |
the message type |
Returns : | the quark associated with the message type |
const gchar* gst_message_type_get_name (GstMessageType type);
Get a printable name for the given message type. Do not modify or free.
type : |
the message type |
Returns : | a reference to the static name of the message. |
#define gst_message_copy(msg) GST_MESSAGE (gst_mini_object_copy (GST_MINI_OBJECT (msg)))
Creates a copy of the message. Returns a copy of the message.
MT safe
msg : |
the message to copy |
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. |
#define gst_message_make_writable(msg) GST_MESSAGE (gst_mini_object_make_writable (GST_MINI_OBJECT (msg)))
Checks if a message is writable. If not, a writable copy is made and returned. Returns a message (possibly a duplicate) that is writable.
MT safe
msg : |
the message to make writable |
GstMessage* gst_message_new_application (GstObject *src, GstStructure *structure);
Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy.
src : |
The object originating the message. |
structure : |
The structure for the message. The message will take ownership of the structure. |
Returns : | The new application message. MT safe. |
GstMessage* gst_message_new_clock_provide (GstObject *src, GstClock *clock, gboolean ready);
Create a clock provide message. This message is posted whenever an element is ready to provide a clock or lost its ability to provide a clock (maybe because it paused or became EOS).
This message is mainly used internally to manage the clock selection.
src : |
The object originating the message. |
clock : |
The clock it provides |
ready : |
TRUE if the sender can provide a clock |
Returns : | The new provide clock message. MT safe. |
GstMessage* gst_message_new_clock_lost (GstObject *src, GstClock *clock);
Create a clock lost message. This message is posted whenever the clock is not valid anymore.
If this message is posted by the pipeline, the pipeline will select a new clock again when it goes to PLAYING. It might therefore be needed to set the pipeline to PAUSED and PLAYING again.
src : |
The object originating the message. |
clock : |
the clock that was lost |
Returns : | The new clock lost message. MT safe. |
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. |
GstMessage* gst_message_new_element (GstObject *src, GstStructure *structure);
Create a new element-specific message. This is meant as a generic way of allowing one-way communication from an element to an application, for example "the firewire cable was unplugged". The format of the message should be documented in the element's documentation. The structure field can be NULL.
src : |
The object originating the message. |
structure : |
The structure for the message. The message will take ownership of the structure. |
Returns : | The new element message. MT safe. |
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. |
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. |
GstMessage* gst_message_new_new_clock (GstObject *src, GstClock *clock);
Create a new clock message. This message is posted whenever the pipeline selectes a new clock for the pipeline.
src : |
The object originating the message. |
clock : |
the new selected clock |
Returns : | The new new clock message. MT safe. |
GstMessage* gst_message_new_segment_done (GstObject *src, GstFormat format, gint64 position);
Create a new segment done message. This message is posted by elements that finish playback of a segment as a result of a segment seek. This message is received by the application after all elements that posted a segment_start have posted the segment_done.
src : |
The object originating the message. |
format : |
The format of the position being done |
position : |
The position of the segment being done |
Returns : | The new segment done message. MT safe. |
GstMessage* gst_message_new_segment_start (GstObject *src, GstFormat format, gint64 position);
Create a new segment message. This message is posted by elements that start playback of a segment as a result of a segment seek. This message is not received by the application but is used for maintenance reasons in container elements.
src : |
The object originating the message. |
format : |
The format of the position being played |
position : |
The position of the segment being played |
Returns : | The new segment start message. MT safe. |
GstMessage* gst_message_new_state_changed (GstObject *src, GstState oldstate, GstState newstate, GstState pending);
Create a state change message. This message is posted whenever an element changed its state.
src : |
the object originating the message |
oldstate : |
the previous state |
newstate : |
the new (current) state |
pending : |
the pending (target) state |
Returns : | The new state change message. MT safe. |
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. |
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. |
GstMessage* gst_message_new_duration (GstObject *src, GstFormat format, gint64 duration);
Create a new duration message. This message is posted by elements that know the duration of a stream in a specific format. This message is received by bins and is used to calculate the total duration of a pipeline. Elements may post a duration message with a duration of GST_CLOCK_TIME_NONE to indicate that the duration has changed and the cached duration should be discarded. The new duration can then be retrieved via a query.
src : |
The object originating the message. |
format : |
The format of the duration |
duration : |
The new duration |
Returns : | The new duration message. MT safe. |
GstMessage* gst_message_new_state_dirty (GstObject *src);
Create a state dirty message. This message is posted whenever an element changed its state asynchronously and is used internally to update the states of container objects.
src : |
the object originating the message |
Returns : | The new state dirty message. MT safe. |
void gst_message_parse_clock_lost (GstMessage *message, GstClock **clock);
Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_CLOCK_LOST. |
clock : |
A pointer to hold the lost clock |
void gst_message_parse_clock_provide (GstMessage *message, GstClock **clock, gboolean *ready);
Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_CLOCK_PROVIDE. |
clock : |
A pointer to hold a clock object. |
ready : |
A pointer to hold the ready flag. |
void gst_message_parse_error (GstMessage *message, GError **gerror, gchar **debug);
Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_ERROR. |
gerror : |
Location for the GError |
debug : |
Location for the debug message, or NULL |
void gst_message_parse_new_clock (GstMessage *message, GstClock **clock);
Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_NEW_CLOCK. |
clock : |
A pointer to hold the selected new clock |
void gst_message_parse_segment_done (GstMessage *message, GstFormat *format, gint64 *position);
Extracts the position and format from the segment start message.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_SEGMENT_DONE. |
format : |
Result location for the format, or NULL |
position : |
Result location for the position, or NULL |
void gst_message_parse_segment_start (GstMessage *message, GstFormat *format, gint64 *position);
Extracts the position and format from the segment start message.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_SEGMENT_START. |
format : |
Result location for the format, or NULL |
position : |
Result location for the position, or NULL |
void gst_message_parse_state_changed (GstMessage *message, GstState *oldstate, GstState *newstate, GstState *pending);
Extracts the old and new states from the GstMessage.
MT safe.
message : |
a valid GstMessage of type GST_MESSAGE_STATE_CHANGED |
oldstate : |
the previous state, or NULL |
newstate : |
the new (current) state, or NULL |
pending : |
the pending (target) state, or NULL |
void gst_message_parse_tag (GstMessage *message, GstTagList **tag_list);
Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_TAG. |
tag_list : |
Return location for the tag-list. |
void gst_message_parse_warning (GstMessage *message, GError **gerror, gchar **debug);
Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_WARNING. |
gerror : |
Location for the GError |
debug : |
Location for the debug message, or NULL |
void gst_message_parse_duration (GstMessage *message, GstFormat *format, gint64 *duration);
Extracts the duration and format from the duration message. The duration might be GST_CLOCK_TIME_NONE, which indicates that the duration has changed. Applications should always use a query to retrieve the duration of a pipeline.
MT safe.
message : |
A valid GstMessage of type GST_MESSAGE_DURATION. |
format : |
Result location for the format, or NULL |
duration : |
Result location for the duration, or NULL |
#define gst_message_ref(msg) GST_MESSAGE (gst_mini_object_ref (GST_MINI_OBJECT (msg)))
Convenience macro to increase the reference count of the message. Returns the reffed message.
msg : |
the message to ref |
<< GstIterator | GstMiniObject >> |