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 * 111 * The opaque #GstBus data structure. 112 */ 113 struct _GstBus 114 { 115 GstObject object; 116 117 /*< private >*/ 118 GstBusPrivate *priv; 119 120 gpointer _gst_reserved[GST_PADDING]; 121 }; 122 123 struct _GstBusClass 124 { 125 GstObjectClass parent_class; 126 127 /* signals */ 128 void (*message) (GstBus *bus, GstMessage *message); 129 void (*sync_message) (GstBus *bus, GstMessage *message); 130 131 /*< private >*/ 132 gpointer _gst_reserved[GST_PADDING]; 133 }; 134 135 GST_API 136 GType gst_bus_get_type (void); 137 138 GST_API 139 GstBus* gst_bus_new (void); 140 141 GST_API 142 gboolean gst_bus_post (GstBus * bus, GstMessage * message); 143 144 GST_API 145 gboolean gst_bus_have_pending (GstBus * bus); 146 147 GST_API 148 GstMessage * gst_bus_peek (GstBus * bus); 149 150 GST_API 151 GstMessage * gst_bus_pop (GstBus * bus); 152 153 GST_API 154 GstMessage * gst_bus_pop_filtered (GstBus * bus, GstMessageType types); 155 156 GST_API 157 GstMessage * gst_bus_timed_pop (GstBus * bus, GstClockTime timeout); 158 159 GST_API 160 GstMessage * gst_bus_timed_pop_filtered (GstBus * bus, GstClockTime timeout, GstMessageType types); 161 162 GST_API 163 void gst_bus_set_flushing (GstBus * bus, gboolean flushing); 164 165 /* synchronous dispatching */ 166 167 GST_API 168 void gst_bus_set_sync_handler (GstBus * bus, GstBusSyncHandler func, 169 gpointer user_data, GDestroyNotify notify); 170 171 /* asynchronous message notifications */ 172 173 GST_API 174 void gst_bus_get_pollfd (GstBus * bus, GPollFD *fd); 175 176 /* GSource based dispatching */ 177 178 GST_API 179 GSource * gst_bus_create_watch (GstBus * bus); 180 181 GST_API 182 guint gst_bus_add_watch_full (GstBus * bus, 183 gint priority, 184 GstBusFunc func, 185 gpointer user_data, 186 GDestroyNotify notify); 187 GST_API 188 guint gst_bus_add_watch (GstBus * bus, 189 GstBusFunc func, 190 gpointer user_data); 191 GST_API 192 gboolean gst_bus_remove_watch (GstBus * bus); 193 194 /* polling the bus */ 195 196 GST_API 197 GstMessage* gst_bus_poll (GstBus *bus, GstMessageType events, 198 GstClockTime timeout); 199 200 /* signal based dispatching helper functions. */ 201 202 GST_API 203 gboolean gst_bus_async_signal_func (GstBus *bus, GstMessage *message, 204 gpointer data); 205 GST_API 206 GstBusSyncReply gst_bus_sync_signal_handler (GstBus *bus, GstMessage *message, 207 gpointer data); 208 209 /* convenience api to add/remove a gsource that emits the async signals */ 210 211 GST_API 212 void gst_bus_add_signal_watch (GstBus * bus); 213 214 GST_API 215 void gst_bus_add_signal_watch_full (GstBus * bus, gint priority); 216 217 GST_API 218 void gst_bus_remove_signal_watch (GstBus * bus); 219 220 GST_API 221 void gst_bus_enable_sync_message_emission (GstBus * bus); 222 223 GST_API 224 void gst_bus_disable_sync_message_emission (GstBus * bus); 225 226 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 227 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBus, gst_object_unref) 228 #endif 229 230 G_END_DECLS 231 232 #endif /* __GST_BUS_H__ */ 233