gst/gstmessage.h

   1 /* GStreamer
   2  * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
   3  *
   4  * gstmessage.h: Header for GstMessage subsystem
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 #ifndef __GST_MESSAGE_H__
  23 #define __GST_MESSAGE_H__
  24
  25 G_BEGIN_DECLS
  26
  27 typedef struct _GstMessage GstMessage;
  28 typedef struct _GstMessageClass GstMessageClass;
  29
  30 /**
  31  * GstMessageType:
  32  * @GST_MESSAGE_UNKNOWN: an undefined message
  33  * @GST_MESSAGE_EOS: end-of-stream reached in a pipeline
  34  * @GST_MESSAGE_ERROR: an error occured
  35  * @GST_MESSAGE_WARNING: a warning occured.
  36  * @GST_MESSAGE_INFO: an info message occured
  37  * @GST_MESSAGE_TAG: a tag was found.
  38  * @GST_MESSAGE_BUFFERING: the pipeline is buffering
  39  * @GST_MESSAGE_STATE_CHANGED: a state change happened
  40  * @GST_MESSAGE_STATE_DIRTY: an element changed state in a streaming thread
  41  * @GST_MESSAGE_STEP_DONE: a framestep finished.
  42  * @GST_MESSAGE_CLOCK_PROVIDE: an element notifies its capability of providing
  43  *                             a clock.
  44  * @GST_MESSAGE_CLOCK_LOST: The current clock as selected by the pipeline became
  45  *                          unusable. The pipeline will select a new clock on
  46  *                          the next PLAYING state change.
  47  * @GST_MESSAGE_NEW_CLOCK: a new clock was selected in the pipeline
  48  * @GST_MESSAGE_STRUCTURE_CHANGE: the structure of the pipeline changed.
  49  * @GST_MESSAGE_STREAM_STATUS: status about a stream, emitted when it starts,
  50  *                             stops, errors, etc..
  51  * @GST_MESSAGE_APPLICATION: message posted by the application, possibly
  52  *                           via an application-specific element.
  53  * @GST_MESSAGE_ELEMENT: element-specific message, see the specific element's
  54  *                       documentation
  55  * @GST_MESSAGE_SEGMENT_START: pipeline started playback of a segment.
  56  * @GST_MESSAGE_SEGMENT_DONE: pipeline completed playback of a segment.
  57  * @GST_MESSAGE_DURATION: The duration of a pipeline changed.
  58  * @GST_MESSAGE_ANY: mask for all of the above messages.
  59  *
  60  * The different message types that are available.
  61  */
  62 /* NOTE: keep in sync with quark registration in gstmessage.c */
  63 typedef enum
  64 {
  65   GST_MESSAGE_UNKNOWN           = 0,
  66   GST_MESSAGE_EOS               = (1 << 0),
  67   GST_MESSAGE_ERROR             = (1 << 1),
  68   GST_MESSAGE_WARNING           = (1 << 2),
  69   GST_MESSAGE_INFO              = (1 << 3),
  70   GST_MESSAGE_TAG               = (1 << 4),
  71   GST_MESSAGE_BUFFERING         = (1 << 5),
  72   GST_MESSAGE_STATE_CHANGED     = (1 << 6),
  73   GST_MESSAGE_STATE_DIRTY       = (1 << 7),
  74   GST_MESSAGE_STEP_DONE         = (1 << 8),
  75   GST_MESSAGE_CLOCK_PROVIDE     = (1 << 9),
  76   GST_MESSAGE_CLOCK_LOST        = (1 << 10),
  77   GST_MESSAGE_NEW_CLOCK         = (1 << 11),
  78   GST_MESSAGE_STRUCTURE_CHANGE  = (1 << 12),
  79   GST_MESSAGE_STREAM_STATUS     = (1 << 13),
  80   GST_MESSAGE_APPLICATION       = (1 << 14),
  81   GST_MESSAGE_ELEMENT           = (1 << 15),
  82   GST_MESSAGE_SEGMENT_START     = (1 << 16),
  83   GST_MESSAGE_SEGMENT_DONE      = (1 << 17),
  84   GST_MESSAGE_DURATION          = (1 << 18),
  85   GST_MESSAGE_ANY               = 0xffffffff
  86 } GstMessageType;
  87
  88 #include <gst/gstminiobject.h>
  89 #include <gst/gstobject.h>
  90 #include <gst/gstelement.h>
  91 #include <gst/gsttaglist.h>
  92 #include <gst/gststructure.h>
  93
  94 /**
  95  * GST_MESSAGE_TRACE_NAME:
  96  *
  97  * The name used for memory allocation tracing
  98  */
  99 #define GST_MESSAGE_TRACE_NAME  "GstMessage"
 100
 101 #define GST_TYPE_MESSAGE                         (gst_message_get_type())
 102 #define GST_IS_MESSAGE(obj)                      (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_MESSAGE))
 103 #define GST_IS_MESSAGE_CLASS(klass)              (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_MESSAGE))
 104 #define GST_MESSAGE_GET_CLASS(obj)               (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_MESSAGE, GstMessageClass))
 105 #define GST_MESSAGE(obj)                         (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_MESSAGE, GstMessage))
 106 #define GST_MESSAGE_CLASS(klass)                 (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_MESSAGE, GstMessageClass))
 107 #define GST_MESSAGE_CAST(obj)                    ((GstMessage*)(obj))
 108
 109 /* the lock is used to handle the synchronous handling of messages,
 110  * the emiting thread is block until the handling thread processed
 111  * the message using this mutex/cond pair */
 112 #define GST_MESSAGE_GET_LOCK(message)   (GST_MESSAGE(message)->lock)
 113 #define GST_MESSAGE_LOCK(message)       g_mutex_lock(GST_MESSAGE_GET_LOCK(message))
 114 #define GST_MESSAGE_UNLOCK(message)     g_mutex_unlock(GST_MESSAGE_GET_LOCK(message))
 115 #define GST_MESSAGE_COND(message)       (GST_MESSAGE(message)->cond)
 116 #define GST_MESSAGE_WAIT(message)       g_cond_wait(GST_MESSAGE_COND(message),GST_MESSAGE_GET_LOCK(message))
 117 #define GST_MESSAGE_SIGNAL(message)     g_cond_signal(GST_MESSAGE_COND(message))
 118
 119 /**
 120  * GST_MESSAGE_TYPE:
 121  * @message: a #GstMessage
 122  *
 123  * Get the #GstMessageType of @message.
 124  */
 125 #define GST_MESSAGE_TYPE(message)       (GST_MESSAGE(message)->type)
 126 /**
 127  * GST_MESSAGE_TYPE_NAME:
 128  * @message: a #GstMessage
 129  *
 130  * Get a constant string representation of the #GstMessageType of @message.
 131  *
 132  * Since: 0.10.4
 133  */
 134 #define GST_MESSAGE_TYPE_NAME(message)  gst_message_type_get_name(GST_MESSAGE_TYPE(message))
 135 /**
 136  * GST_MESSAGE_TIMESTAMP:
 137  * @message: a #GstMessage
 138  *
 139  * Get the timestamp of @message. This is the timestamp when the message
 140  * was created.
 141  */
 142 #define GST_MESSAGE_TIMESTAMP(message)  (GST_MESSAGE(message)->timestamp)
 143 /**
 144  * GST_MESSAGE_SRC:
 145  * @message: a #GstMessage
 146  *
 147  * Get the object that posted @message.
 148  */
 149 #define GST_MESSAGE_SRC(message)        (GST_MESSAGE(message)->src)
 150
 151 /**
 152  * GstMessage:
 153  * @mini_object: the parent structure
 154  * @type: the #GstMessageType of the message
 155  * @timestamp: the timestamp of the message
 156  * @src: the src of the message
 157  * @structure: the #GstStructure containing the message info.
 158  *
 159  * A #GstMessage.
 160  */
 161 struct _GstMessage
 162 {
 163   GstMiniObject mini_object;
 164
 165   /*< private > *//* with MESSAGE_LOCK */
 166   GMutex *lock;                 /* lock and cond for async delivery */
 167   GCond *cond;
 168
 169   /*< public > *//* with COW */
 170   GstMessageType type;
 171   guint64 timestamp;
 172   GstObject *src;
 173
 174   GstStructure *structure;
 175
 176   /*< private > */
 177   gpointer _gst_reserved[GST_PADDING];
 178 };
 179
 180 struct _GstMessageClass {
 181   GstMiniObjectClass mini_object_class;
 182
 183   /*< private > */
 184   gpointer _gst_reserved[GST_PADDING];
 185 };
 186
 187 void            _gst_message_initialize         (void);
 188
 189 GType           gst_message_get_type            (void);
 190
 191 const gchar*    gst_message_type_get_name       (GstMessageType type);
 192 GQuark          gst_message_type_to_quark       (GstMessageType type);
 193
 194 /* refcounting */
 195 /**
 196  * gst_message_ref:
 197  * @msg: the message to ref
 198  *
 199  * Convenience macro to increase the reference count of the message. Returns the
 200  * reffed message.
 201  */
 202 static inline GstMessage *
 203 gst_message_ref (GstMessage * msg)
 204 {
 205   /* not using a macro here because gcc-4.1 will complain
 206    * if the return value isn't used (because of the cast) */
 207   return (GstMessage *) gst_mini_object_ref (GST_MINI_OBJECT (msg));
 208 }
 209
 210 /**
 211  * gst_message_unref:
 212  * @msg: the message to unref
 213  *
 214  * Convenience macro to decrease the reference count of the message, possibly freeing
 215  * the it.
 216  */
 217 #define         gst_message_unref(msg)          gst_mini_object_unref (GST_MINI_OBJECT (msg))
 218 /* copy message */
 219 /**
 220  * gst_message_copy:
 221  * @msg: the message to copy
 222  *
 223  * Creates a copy of the message. Returns a copy of the message.
 224  *
 225  * MT safe
 226  */
 227 #define         gst_message_copy(msg)           GST_MESSAGE (gst_mini_object_copy (GST_MINI_OBJECT (msg)))
 228 /**
 229  * gst_message_make_writable:
 230  * @msg: the message to make writable
 231  *
 232  * Checks if a message is writable. If not, a writable copy is made and
 233  * returned. Returns a message (possibly a duplicate) that is writable.
 234  *
 235  * MT safe
 236  */
 237 #define         gst_message_make_writable(msg)  GST_MESSAGE (gst_mini_object_make_writable (GST_MINI_OBJECT (msg)))
 238
 239 GstMessage *    gst_message_new_eos             (GstObject * src);
 240 GstMessage *    gst_message_new_error           (GstObject * src, GError * error, gchar * debug);
 241 GstMessage *    gst_message_new_warning         (GstObject * src, GError * error, gchar * debug);
 242 GstMessage *    gst_message_new_tag             (GstObject * src, GstTagList * tag_list);
 243 GstMessage *    gst_message_new_state_changed   (GstObject * src, GstState oldstate,
 244                                                  GstState newstate, GstState pending);
 245 GstMessage *    gst_message_new_state_dirty     (GstObject * src);
 246 GstMessage *    gst_message_new_clock_provide   (GstObject * src, GstClock *clock, gboolean ready);
 247 GstMessage *    gst_message_new_clock_lost      (GstObject * src, GstClock *clock);
 248 GstMessage *    gst_message_new_new_clock       (GstObject * src, GstClock *clock);
 249 GstMessage *    gst_message_new_application     (GstObject * src, GstStructure * structure);
 250 GstMessage *    gst_message_new_element         (GstObject * src, GstStructure * structure);
 251 GstMessage *    gst_message_new_segment_start   (GstObject * src, GstFormat format, gint64 position);
 252 GstMessage *    gst_message_new_segment_done    (GstObject * src, GstFormat format, gint64 position);
 253 GstMessage *    gst_message_new_duration        (GstObject * src, GstFormat format, gint64 duration);
 254 GstMessage *    gst_message_new_custom          (GstMessageType type,
 255                                                  GstObject    * src,
 256                                                  GstStructure * structure);
 257
 258 void            gst_message_parse_error         (GstMessage *message, GError **gerror, gchar **debug);
 259 void            gst_message_parse_warning       (GstMessage *message, GError **gerror, gchar **debug);
 260 void            gst_message_parse_tag           (GstMessage *message, GstTagList **tag_list);
 261 void            gst_message_parse_state_changed (GstMessage *message, GstState *oldstate,
 262                                                  GstState *newstate, GstState *pending);
 263 void            gst_message_parse_clock_provide (GstMessage *message, GstClock **clock, gboolean *ready);
 264 void            gst_message_parse_clock_lost    (GstMessage *message, GstClock **clock);
 265 void            gst_message_parse_new_clock     (GstMessage *message, GstClock **clock);
 266 void            gst_message_parse_segment_start (GstMessage *message, GstFormat *format, gint64 *position);
 267 void            gst_message_parse_segment_done  (GstMessage *message, GstFormat *format, gint64 *position);
 268 void            gst_message_parse_duration      (GstMessage *message, GstFormat *format, gint64 *duration);
 269
 270 const GstStructure *  gst_message_get_structure (GstMessage *message);
 271
 272 G_END_DECLS
 273
 274 #endif /* __GST_MESSAGE_H__ */