1 /* GStreamer 2 * Copyright (C) 2004 Wim Taymans <wim@fluendo.com> 3 * 4 * gstbus.h: Header for GstBus 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., 51 Franklin St, Fifth Floor, 19 * Boston, MA 02110-1301, USA. 20 */ 21 22 #ifndef __GST_BUS_H__ 23 #define __GST_BUS_H__ 24 25 typedef struct _GstBus GstBus; 26 typedef struct _GstBusPrivate GstBusPrivate; 27 typedef struct _GstBusClass GstBusClass; 28 29 #include <gst/gstmessage.h> 30 #include <gst/gstclock.h> 31 32 G_BEGIN_DECLS 33 34 /* --- standard type macros --- */ 35 #define GST_TYPE_BUS (gst_bus_get_type ()) 36 #define GST_BUS(bus) (G_TYPE_CHECK_INSTANCE_CAST ((bus), GST_TYPE_BUS, GstBus)) 37 #define GST_IS_BUS(bus) (G_TYPE_CHECK_INSTANCE_TYPE ((bus), GST_TYPE_BUS)) 38 #define GST_BUS_CLASS(bclass) (G_TYPE_CHECK_CLASS_CAST ((bclass), GST_TYPE_BUS, GstBusClass)) 39 #define GST_IS_BUS_CLASS(bclass) (G_TYPE_CHECK_CLASS_TYPE ((bclass), GST_TYPE_BUS)) 40 #define GST_BUS_GET_CLASS(bus) (G_TYPE_INSTANCE_GET_CLASS ((bus), GST_TYPE_BUS, GstBusClass)) 41 #define GST_BUS_CAST(bus) ((GstBus*)(bus)) 42 43 /** 44 * GstBusFlags: 45 * @GST_BUS_FLUSHING: The bus is currently dropping all messages 46 * @GST_BUS_FLAG_LAST: offset to define more flags 47 * 48 * The standard flags that a bus may have. 49 */ 50 typedef enum { 51 GST_BUS_FLUSHING = (GST_OBJECT_FLAG_LAST << 0), 52 /* padding */ 53 GST_BUS_FLAG_LAST = (GST_OBJECT_FLAG_LAST << 1) 54 } GstBusFlags; 55 56 /** 57 * GstBusSyncReply: 58 * @GST_BUS_DROP: drop the message 59 * @GST_BUS_PASS: pass the message to the async queue 60 * @GST_BUS_ASYNC: pass message to async queue, continue if message is handled 61 * 62 * The result values for a GstBusSyncHandler. 63 */ 64 typedef enum 65 { 66 GST_BUS_DROP = 0, 67 GST_BUS_PASS = 1, 68 GST_BUS_ASYNC = 2 69 } GstBusSyncReply; 70 71 /** 72 * GstBusSyncHandler: 73 * @bus: the #GstBus that sent the message 74 * @message: the #GstMessage 75 * @user_data: user data that has been given, when registering the handler 76 * 77 * Handler will be invoked synchronously, when a new message has been injected 78 * into the bus. This function is mostly used internally. Only one sync handler 79 * can be attached to a given bus. 80 * 81 * If the handler returns %GST_BUS_DROP, it should unref the message, else the 82 * message should not be unreffed by the sync handler. 83 * 84 * Returns: #GstBusSyncReply stating what to do with the message 85 */ 86 typedef GstBusSyncReply (*GstBusSyncHandler) (GstBus * bus, GstMessage * message, gpointer user_data); 87 88 /** 89 * GstBusFunc: 90 * @bus: the #GstBus that sent the message 91 * @message: the #GstMessage 92 * @user_data: user data that has been given, when registering the handler 93 * 94 * Specifies the type of function passed to gst_bus_add_watch() or 95 * gst_bus_add_watch_full(), which is called from the mainloop when a message 96 * is available on the bus. 97 * 98 * The message passed to the function will be unreffed after execution of this 99 * function so it should not be freed in the function. 100 * 101 * Note that this function is used as a #GSourceFunc which means that returning 102 * %FALSE will remove the #GSource from the mainloop. 103 * 104 * Returns: %FALSE if the event source should be removed. 105 */ 106 typedef gboolean (*GstBusFunc) (GstBus * bus, GstMessage * message, gpointer user_data); 107 108 /** 109 * GstBus: 110 * @object: the parent structure 111 * 112 * The opaque #GstBus data structure. 113 */ 114 struct _GstBus 115 { 116 GstObject object; 117 118 /*< private >*/ 119 GstBusPrivate *priv; 120 121 gpointer _gst_reserved[GST_PADDING]; 122 }; 123 124 /** 125 * GstBusClass: 126 * @parent_class: the parent class structure 127 * 128 * GStreamer bus class. 129 */ 130 struct _GstBusClass 131 { 132 GstObjectClass parent_class; 133 134 /* signals */ 135 136 /** 137 * GstBusClass::message: 138 * @bus: the #GstBus 139 * @message: the message that has been posted asynchronously 140 * 141 * A message has been posted on the bus. 142 */ 143 void (*message) (GstBus *bus, GstMessage *message); 144 145 /** 146 * GstBusClass::sync_message: 147 * @bus: the #GstBus 148 * @message: the message that has been posted synchronously 149 * 150 * A message has been posted on the bus. 151 */ 152 void (*sync_message) (GstBus *bus, GstMessage *message); 153 154 /*< private >*/ 155 gpointer _gst_reserved[GST_PADDING]; 156 }; 157 158 GST_API 159 GType gst_bus_get_type (void); 160 161 GST_API 162 GstBus* gst_bus_new (void); 163 164 GST_API 165 gboolean gst_bus_post (GstBus * bus, GstMessage * message); 166 167 GST_API 168 gboolean gst_bus_have_pending (GstBus * bus); 169 170 GST_API 171 GstMessage * gst_bus_peek (GstBus * bus); 172 173 GST_API 174 GstMessage * gst_bus_pop (GstBus * bus); 175 176 GST_API 177 GstMessage * gst_bus_pop_filtered (GstBus * bus, GstMessageType types); 178 179 GST_API 180 GstMessage * gst_bus_timed_pop (GstBus * bus, GstClockTime timeout); 181 182 GST_API 183 GstMessage * gst_bus_timed_pop_filtered (GstBus * bus, GstClockTime timeout, GstMessageType types); 184 185 GST_API 186 void gst_bus_set_flushing (GstBus * bus, gboolean flushing); 187 188 /* synchronous dispatching */ 189 190 GST_API 191 void gst_bus_set_sync_handler (GstBus * bus, GstBusSyncHandler func, 192 gpointer user_data, GDestroyNotify notify); 193 194 /* asynchronous message notifications */ 195 196 GST_API 197 void gst_bus_get_pollfd (GstBus * bus, GPollFD *fd); 198 199 /* GSource based dispatching */ 200 201 GST_API 202 GSource * gst_bus_create_watch (GstBus * bus); 203 204 GST_API 205 guint gst_bus_add_watch_full (GstBus * bus, 206 gint priority, 207 GstBusFunc func, 208 gpointer user_data, 209 GDestroyNotify notify); 210 GST_API 211 guint gst_bus_add_watch (GstBus * bus, 212 GstBusFunc func, 213 gpointer user_data); 214 GST_API 215 gboolean gst_bus_remove_watch (GstBus * bus); 216 217 /* polling the bus */ 218 219 GST_API 220 GstMessage* gst_bus_poll (GstBus *bus, GstMessageType events, 221 GstClockTime timeout); 222 223 /* signal based dispatching helper functions. */ 224 225 GST_API 226 gboolean gst_bus_async_signal_func (GstBus *bus, GstMessage *message, 227 gpointer data); 228 GST_API 229 GstBusSyncReply gst_bus_sync_signal_handler (GstBus *bus, GstMessage *message, 230 gpointer data); 231 232 /* convenience api to add/remove a gsource that emits the async signals */ 233 234 GST_API 235 void gst_bus_add_signal_watch (GstBus * bus); 236 237 GST_API 238 void gst_bus_add_signal_watch_full (GstBus * bus, gint priority); 239 240 GST_API 241 void gst_bus_remove_signal_watch (GstBus * bus); 242 243 GST_API 244 void gst_bus_enable_sync_message_emission (GstBus * bus); 245 246 GST_API 247 void gst_bus_disable_sync_message_emission (GstBus * bus); 248 249 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBus, gst_object_unref) 250 251 G_END_DECLS 252 253 #endif /* __GST_BUS_H__ */ 254