* SECTION:gstmessage
* @short_description: Lightweight objects to signal the application of
* pipeline events
- * @see_also: #GstBus,#GstMiniObject
+ * @see_also: #GstBus, #GstMiniObject, #GstElement
*
* Messages are implemented as a subclass of #GstMiniObject with a generic
* #GstStructure as the content. This allows for writing custom messages without
*
* Messages are posted by objects in the pipeline and are passed to the
* application using the #GstBus.
+
+ * The basic use pattern of posting a message on a #GstBus is as follows:
+ *
+ * <example>
+ * <title>Posting a #GstMessage</title>
+ * <programlisting>
+ * gst_bus_post (bus, gst_message_new_eos());
+ * </programlisting>
+ * </example>
+ *
+ * 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)
*/
#include <string.h> /* memcpy */
#include <gst/gsttaglist.h>
#include <gst/gststructure.h>
+/**
+ * GST_MESSAGE_TRACE_NAME:
+ *
+ * The name used for memory allocation tracing
+ */
#define GST_MESSAGE_TRACE_NAME "GstMessage"
#define GST_TYPE_MESSAGE (gst_message_get_type())
#define GST_MESSAGE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_MESSAGE, GstMessageClass))
#define GST_MESSAGE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_MESSAGE, GstMessage))
#define GST_MESSAGE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_MESSAGE, GstMessageClass))
+#define GST_MESSAGE_CAST(obj) ((GstMessage*)(obj))
/* the lock is used to handle the synchronous handling of messages,
* the emiting thread is block until the handling thread processed
#define GST_MESSAGE_WAIT(message) g_cond_wait(GST_MESSAGE_COND(message),GST_MESSAGE_GET_LOCK(message))
#define GST_MESSAGE_SIGNAL(message) g_cond_signal(GST_MESSAGE_COND(message))
+/**
+ * GST_MESSAGE_TYPE:
+ * @message: a #GstMessage
+ *
+ * Get the #GstMessageType of @message.
+ */
#define GST_MESSAGE_TYPE(message) (GST_MESSAGE(message)->type)
+/**
+ * GST_MESSAGE_TIMESTAMP:
+ * @message: a #GstMessage
+ *
+ * Get the timestamp of @message. This is the timestamp when the message
+ * was created.
+ */
#define GST_MESSAGE_TIMESTAMP(message) (GST_MESSAGE(message)->timestamp)
+/**
+ * GST_MESSAGE_SRC:
+ * @message: a #GstMessage
+ *
+ * Get the object that posted @message.
+ */
#define GST_MESSAGE_SRC(message) (GST_MESSAGE(message)->src)
+/**
+ * GstMessage:
+ * @mini_object: the parent structure
+ * @type: the #GstMessageType of the message
+ * @timestamp: the timestamp of the message
+ * @src: the src of the message
+ * @structure: the #GstStructure containing the message info.
+ *
+ * A #GstMessage.
+ */
struct _GstMessage
{
GstMiniObject mini_object;
- /*< public > *//* with MESSAGE_LOCK */
+ /*< private > *//* with MESSAGE_LOCK */
GMutex *lock; /* lock and cond for async delivery */
GCond *cond;