subprojects/gstreamer/gst/gstdeviceprovider.h

   1 /* GStreamer
   2  * Copyright (C) 2012 Olivier Crete <olivier.crete@collabora.com>
   3  *
   4  * gstdeviceprovider.h: Device probing and monitoring
   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_DEVICE_PROVIDER_H__
  23 #define __GST_DEVICE_PROVIDER_H__
  24
  25 #include <gst/gstelement.h>
  26
  27 /**
  28  * GST_DEVICE_PROVIDER_REGISTER_DEFINE_CUSTOM:
  29  * @d_p: The device provider name in lower case, with words separated by '_'.
  30  * Used to generate `gst_device_provider_register_*(GstPlugin* plugin)`.
  31  * @register_func: pointer to a method with the format: `gboolean register_func (GstPlugin* plugin);`
  32  *
  33  * A convenience macro to define the entry point of a
  34  * device provider `gst_device_provider_register_*(GstPlugin* plugin)` which uses
  35  * register_func as the main registration method for the device provider.
  36  * As an example, you may define the device provider named "device-provider"
  37  * with the namespace `my` as following using `device_provider_register_custom`:
  38  *
  39  * ```
  40  *
  41  * gboolean my_device_provider_register_custom (GstPlugin * plugin)
  42  * {
  43  *    gboolean ret = FALSE;
  44  *    ret |= gst_device_provider_register (plugin, "my-device-provider",
  45          GST_RANK_PRIMARY, GST_TYPE_MY_DEVICE_PROVIDER);
  46  *    return TRUE;
  47  * }
  48  *
  49  * GST_DEVICE_PROVIDER_REGISTER_DEFINE_CUSTOM (my_device_provider, my_device_provider_register_custom)
  50  * ```
  51  *
  52  * Since: 1.20
  53  */
  54 #define GST_DEVICE_PROVIDER_REGISTER_DEFINE_CUSTOM(d_p, register_func) \
  55 G_BEGIN_DECLS \
  56 gboolean G_PASTE (gst_device_provider_register_, d_p) (GstPlugin * plugin) \
  57 { \
  58   return register_func (plugin); \
  59 } \
  60 G_END_DECLS
  61
  62 /**
  63  * GST_DEVICE_PROVIDER_REGISTER_DEFINE:
  64  * @d_p: The device provider name in lower case, with words separated by '_'.
  65  * Used to generate `gst_device_provider_register_*(GstPlugin* plugin)`.
  66  * @d_p_n: The public name of the device provider
  67  * @r: The #GstRank of the device provider (higher rank means more importance when autoplugging, see #GstRank)
  68  * @t: The #GType of the device provider.
  69  *
  70  * A convenience macro to define the entry point of a
  71  * device provider `gst_device_provider_register_*(GstPlugin* plugin)`.
  72  *
  73  * Since: 1.20
  74  */
  75 #define GST_DEVICE_PROVIDER_REGISTER_DEFINE(d_p, d_p_n, r, t) \
  76 G_BEGIN_DECLS \
  77 gboolean G_PASTE (gst_device_provider_register_, d_p) (GstPlugin * plugin) \
  78 { \
  79   return gst_device_provider_register (plugin, d_p_n, r, t); \
  80 } \
  81 G_END_DECLS
  82
  83 /**
  84  * GST_DEVICE_PROVIDER_REGISTER_DECLARE:
  85  * @d_p: The device provider name in lower case, with words separated by '_'.
  86  *
  87  * This macro can be used to declare a new device provider.
  88  * It has to be used in combination with #GST_DEVICE_PROVIDER_REGISTER_DEFINE macro
  89  * and must be placed outside any block to declare the device provider registration
  90  * function.
  91  *
  92  * Since: 1.20
  93  */
  94 #define GST_DEVICE_PROVIDER_REGISTER_DECLARE(d_p) \
  95 G_BEGIN_DECLS \
  96 gboolean G_PASTE(gst_device_provider_register_, d_p) (GstPlugin * plugin); \
  97 G_END_DECLS
  98
  99 /**
 100  * GST_DEVICE_PROVIDER_REGISTER:
 101  * @d_p: The device provider name in lower case, with words separated by '_'.
 102  * @plugin: The #GstPlugin where to register the device provider.
 103  *
 104  * This macro can be used to register a device provider into a #GstPlugin.
 105  * This method will be usually called in the plugin init function
 106  * but can also be called with a NULL plugin.
 107  *
 108  * Since: 1.20
 109  */
 110 #define GST_DEVICE_PROVIDER_REGISTER(d_p, plugin) G_PASTE(gst_device_provider_register_, d_p) (plugin)
 111
 112 G_BEGIN_DECLS
 113
 114 typedef struct _GstDeviceProvider GstDeviceProvider;
 115 typedef struct _GstDeviceProviderClass GstDeviceProviderClass;
 116 typedef struct _GstDeviceProviderPrivate GstDeviceProviderPrivate;
 117
 118 #include <gst/gstdeviceproviderfactory.h>
 119
 120 #define GST_TYPE_DEVICE_PROVIDER                 (gst_device_provider_get_type())
 121 #define GST_IS_DEVICE_PROVIDER(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_DEVICE_PROVIDER))
 122 #define GST_IS_DEVICE_PROVIDER_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_DEVICE_PROVIDER))
 123 #define GST_DEVICE_PROVIDER_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_DEVICE_PROVIDER, GstDeviceProviderClass))
 124 #define GST_DEVICE_PROVIDER(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_DEVICE_PROVIDER, GstDeviceProvider))
 125 #define GST_DEVICE_PROVIDER_CLASS(klass)         (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_DEVICE_PROVIDER, GstDeviceProviderClass))
 126 #define GST_DEVICE_PROVIDER_CAST(obj)            ((GstDeviceProvider *)(obj))
 127
 128
 129 /**
 130  * GstDeviceProvider:
 131  * @parent: The parent #GstObject
 132  * @devices: a #GList of the #GstDevice objects
 133  *
 134  * The structure of the base #GstDeviceProvider
 135  *
 136  * Since: 1.4
 137  */
 138 struct _GstDeviceProvider {
 139   GstObject         parent;
 140
 141   /* Protected by the Object lock */
 142   GList *devices;
 143
 144   /*< private >*/
 145
 146   GstDeviceProviderPrivate *priv;
 147
 148   gpointer _gst_reserved[GST_PADDING];
 149 };
 150
 151 /**
 152  * GstDeviceProviderClass:
 153  * @parent_class: the parent #GstObjectClass structure
 154  * @factory: a pointer to the #GstDeviceProviderFactory that creates this
 155  *  provider
 156  * @probe: Returns a list of devices that are currently available.
 157  *  This should never block. The devices should not have a parent and should
 158  *  be floating.
 159  * @start: Starts monitoring for new devices. Only subclasses that can know
 160  *  that devices have been added or remove need to implement this method.
 161  * @stop: Stops monitoring for new devices. Only subclasses that implement
 162  *  the start() method need to implement this method.
 163  *
 164  * The structure of the base #GstDeviceProviderClass
 165  *
 166  * Since: 1.4
 167  */
 168
 169 struct _GstDeviceProviderClass {
 170   GstObjectClass    parent_class;
 171
 172   GstDeviceProviderFactory     *factory;
 173
 174   GList*      (*probe) (GstDeviceProvider * provider);
 175
 176   gboolean    (*start) (GstDeviceProvider * provider);
 177   void        (*stop)  (GstDeviceProvider * provider);
 178
 179   /*< private >*/
 180   gpointer metadata;
 181
 182   /*< private >*/
 183   gpointer _gst_reserved[GST_PADDING];
 184 };
 185
 186 GST_API
 187 GType       gst_device_provider_get_type (void);
 188
 189
 190 GST_API
 191 GList *     gst_device_provider_get_devices    (GstDeviceProvider * provider);
 192
 193 GST_API
 194 gboolean    gst_device_provider_start          (GstDeviceProvider * provider);
 195
 196 GST_API
 197 void        gst_device_provider_stop           (GstDeviceProvider * provider);
 198
 199 GST_API
 200 gboolean    gst_device_provider_can_monitor    (GstDeviceProvider * provider);
 201
 202 GST_API
 203 GstBus *    gst_device_provider_get_bus        (GstDeviceProvider * provider);
 204
 205 GST_API
 206 void        gst_device_provider_device_add     (GstDeviceProvider * provider,
 207                                                 GstDevice * device);
 208 GST_API
 209 void        gst_device_provider_device_remove  (GstDeviceProvider * provider,
 210                                                 GstDevice * device);
 211 GST_API
 212 gchar **    gst_device_provider_get_hidden_providers (GstDeviceProvider * provider);
 213
 214 GST_API
 215 void        gst_device_provider_hide_provider        (GstDeviceProvider * provider,
 216                                                       const gchar       * name);
 217 GST_API
 218 void        gst_device_provider_unhide_provider      (GstDeviceProvider * provider,
 219                                                       const gchar       * name);
 220
 221 GST_API
 222 const gchar * gst_device_provider_get_metadata       (GstDeviceProvider * provider,
 223                                                       const gchar * key);
 224
 225 GST_API
 226 gboolean    gst_device_provider_is_started     (GstDeviceProvider * provider);
 227
 228 /* device provider class meta data */
 229
 230 GST_API
 231 void        gst_device_provider_class_set_metadata         (GstDeviceProviderClass *klass,
 232                                                             const gchar     *longname,
 233                                                             const gchar     *classification,
 234                                                             const gchar     *description,
 235                                                             const gchar     *author);
 236 GST_API
 237 void        gst_device_provider_class_set_static_metadata  (GstDeviceProviderClass *klass,
 238                                                             const gchar     *longname,
 239                                                             const gchar     *classification,
 240                                                             const gchar     *description,
 241                                                             const gchar     *author);
 242 GST_API
 243 void        gst_device_provider_class_add_metadata         (GstDeviceProviderClass * klass,
 244                                                             const gchar * key, const gchar * value);
 245 GST_API
 246 void        gst_device_provider_class_add_static_metadata  (GstDeviceProviderClass * klass,
 247                                                             const gchar * key, const gchar * value);
 248 GST_API
 249 const gchar * gst_device_provider_class_get_metadata       (GstDeviceProviderClass * klass,
 250                                                             const gchar * key);
 251
 252 GST_API
 253 void gst_device_provider_device_changed                    (GstDeviceProvider * provider,
 254                                                             GstDevice *device,
 255                                                             GstDevice *changed_device);
 256
 257 /* factory management */
 258
 259 GST_API
 260 GstDeviceProviderFactory * gst_device_provider_get_factory (GstDeviceProvider * provider);
 261
 262 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDeviceProvider, gst_object_unref)
 263
 264 G_END_DECLS
 265
 266 #endif /* __GST_DEVICE_PROVIDER_H__ */