gst-libs/gst/interfaces/propertyprobe.c

   1 /* GStreamer PropertyProbe
   2  * Copyright (C) 2003 David Schleef <ds@schleef.org>
   3  *
   4  * property_probe.c: property_probe design virtual class function wrappers
   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  * SECTION:gstpropertyprobe
  23  * @short_description: Interface for probing possible property values
  24  *
  25  * The property probe is a way to autodetect allowed values for a GObject
  26  * property. It's primary use is to autodetect device-names in several elements.
  27  *
  28  * The interface is implemented by many hardware sources and sinks.
  29  */
  30 #ifdef HAVE_CONFIG_H
  31 #include "config.h"
  32 #endif
  33
  34 #include <string.h>
  35
  36 #include "propertyprobe.h"
  37
  38 enum
  39 {
  40   SIGNAL_PROBE_NEEDED,
  41   LAST_SIGNAL
  42 };
  43
  44 static void gst_property_probe_iface_init (GstPropertyProbeInterface * iface);
  45
  46 static guint gst_property_probe_signals[LAST_SIGNAL] = { 0 };
  47
  48 GType
  49 gst_property_probe_get_type (void)
  50 {
  51   static GType gst_property_probe_type = 0;
  52
  53   if (!gst_property_probe_type) {
  54     static const GTypeInfo gst_property_probe_info = {
  55       sizeof (GstPropertyProbeInterface),
  56       (GBaseInitFunc) gst_property_probe_iface_init,
  57       NULL,
  58       NULL,
  59       NULL,
  60       NULL,
  61       0,
  62       0,
  63       NULL,
  64     };
  65
  66     gst_property_probe_type =
  67         g_type_register_static (G_TYPE_INTERFACE,
  68         "GstPropertyProbe", &gst_property_probe_info, 0);
  69   }
  70
  71   return gst_property_probe_type;
  72 }
  73
  74 static void
  75 gst_property_probe_iface_init (GstPropertyProbeInterface * iface)
  76 {
  77   static gboolean initialized = FALSE;
  78
  79   if (!initialized) {
  80     /**
  81      * GstPropertyProbe::probe-needed
  82      * @pspec: #GParamSpec that needs a probe
  83      *
  84      */
  85     /* FIXME:
  86      * what is the purpose of this signal, I can't find any usage of it
  87      * according to proto n *.h, it should be g_cclosure_marshal_VOID__PARAM
  88      */
  89     gst_property_probe_signals[SIGNAL_PROBE_NEEDED] =
  90         g_signal_new ("probe-needed", G_TYPE_FROM_CLASS (iface),
  91         G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPropertyProbeInterface,
  92             probe_needed), NULL, NULL, g_cclosure_marshal_VOID__POINTER,
  93         G_TYPE_NONE, 1, G_TYPE_POINTER);
  94     initialized = TRUE;
  95   }
  96
  97   /* default virtual functions */
  98   iface->get_properties = NULL;
  99   iface->get_values = NULL;
 100 }
 101
 102 /**
 103  * gst_property_probe_get_properties:
 104  * @probe: the #GstPropertyProbe to get the properties for.
 105  *
 106  * Get a list of properties for which probing is supported.
 107  *
 108  * Returns: the list of #GParamSpec * pointers representing
 109  * properties for which probing is supported by this element.
 110  */
 111 const GList *
 112 gst_property_probe_get_properties (GstPropertyProbe * probe)
 113 {
 114   GstPropertyProbeInterface *iface;
 115
 116   g_return_val_if_fail (probe != NULL, NULL);
 117   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), NULL);
 118
 119   iface = GST_PROPERTY_PROBE_GET_IFACE (probe);
 120
 121   if (iface->get_properties)
 122     return iface->get_properties (probe);
 123
 124   return NULL;
 125 }
 126
 127 /**
 128  * gst_property_probe_get_property:
 129  * @probe: the #GstPropertyProbe to get the properties for.
 130  * @name: name of the property.
 131  *
 132  * Get #GParamSpec for a property for which probing is supported.
 133  *
 134  * Returns: the #GParamSpec of %NULL.
 135  */
 136 const GParamSpec *
 137 gst_property_probe_get_property (GstPropertyProbe * probe, const gchar * name)
 138 {
 139   const GList *pspecs;
 140
 141   g_return_val_if_fail (probe != NULL, NULL);
 142   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), NULL);
 143   g_return_val_if_fail (name != NULL, NULL);
 144
 145   pspecs = gst_property_probe_get_properties (probe);
 146
 147   while (pspecs) {
 148     const GParamSpec *pspec = pspecs->data;
 149
 150     if (pspec) {
 151       if (!strcmp (pspec->name, name))
 152         return pspec;
 153     } else {
 154       GST_WARNING_OBJECT (probe, "NULL paramspec in property probe list");
 155     }
 156
 157     pspecs = pspecs->next;
 158   }
 159
 160   return NULL;
 161 }
 162
 163 /**
 164  * gst_property_probe_probe_property:
 165  * @probe: the #GstPropertyProbe to check.
 166  * @pspec: #GParamSpec of the property.
 167  *
 168  * Runs a probe on the property specified by @pspec
 169  */
 170 void
 171 gst_property_probe_probe_property (GstPropertyProbe * probe,
 172     const GParamSpec * pspec)
 173 {
 174   GstPropertyProbeInterface *iface;
 175
 176   g_return_if_fail (probe != NULL);
 177   g_return_if_fail (GST_IS_PROPERTY_PROBE (probe));
 178   g_return_if_fail (pspec != NULL);
 179
 180   iface = GST_PROPERTY_PROBE_GET_IFACE (probe);
 181
 182   if (iface->probe_property)
 183     iface->probe_property (probe, pspec->param_id, pspec);
 184 }
 185
 186 /**
 187  * gst_property_probe_probe_property_name:
 188  * @probe: the #GstPropertyProbe to check.
 189  * @name: name of the property.
 190  *
 191  * Runs a probe on the property specified by @name.
 192  */
 193 void
 194 gst_property_probe_probe_property_name (GstPropertyProbe * probe,
 195     const gchar * name)
 196 {
 197   const GParamSpec *pspec;
 198
 199   g_return_if_fail (probe != NULL);
 200   g_return_if_fail (GST_IS_PROPERTY_PROBE (probe));
 201   g_return_if_fail (name != NULL);
 202
 203   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (probe), name);
 204   if (!pspec) {
 205     g_warning ("No such property %s", name);
 206     return;
 207   }
 208
 209   gst_property_probe_probe_property (probe, pspec);
 210 }
 211
 212 /**
 213  * gst_property_probe_needs_probe:
 214  * @probe: the #GstPropertyProbe object to which the given property belongs.
 215  * @pspec: a #GParamSpec that identifies the property to check.
 216  *
 217  * Checks whether a property needs a probe. This might be because
 218  * the property wasn't initialized before, or because host setup
 219  * changed. This might be, for example, because a new device was
 220  * added, and thus device probing needs to be refreshed to display
 221  * the new device.
 222  *
 223  * Returns: TRUE if the property needs a new probe, FALSE if not.
 224  */
 225 gboolean
 226 gst_property_probe_needs_probe (GstPropertyProbe * probe,
 227     const GParamSpec * pspec)
 228 {
 229   GstPropertyProbeInterface *iface;
 230
 231   g_return_val_if_fail (probe != NULL, FALSE);
 232   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), FALSE);
 233   g_return_val_if_fail (pspec != NULL, FALSE);
 234
 235   iface = GST_PROPERTY_PROBE_GET_IFACE (probe);
 236
 237   if (iface->needs_probe)
 238     return iface->needs_probe (probe, pspec->param_id, pspec);
 239
 240   return FALSE;
 241 }
 242
 243 /**
 244  * gst_property_probe_needs_probe_name:
 245  * @probe: the #GstPropertyProbe object to which the given property belongs.
 246  * @name: the name of the property to check.
 247  *
 248  * Same as gst_property_probe_needs_probe ().
 249  *
 250  * Returns: TRUE if the property needs a new probe, FALSE if not.
 251  */
 252 gboolean
 253 gst_property_probe_needs_probe_name (GstPropertyProbe * probe,
 254     const gchar * name)
 255 {
 256   const GParamSpec *pspec;
 257
 258   g_return_val_if_fail (probe != NULL, FALSE);
 259   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), FALSE);
 260   g_return_val_if_fail (name != NULL, FALSE);
 261
 262   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (probe), name);
 263   if (!pspec) {
 264     g_warning ("No such property %s", name);
 265     return FALSE;
 266   }
 267
 268   return gst_property_probe_needs_probe (probe, pspec);
 269 }
 270
 271 /**
 272  * gst_property_probe_get_values:
 273  * @probe: the #GstPropertyProbe object.
 274  * @pspec: the #GParamSpec property identifier.
 275  *
 276  * Gets the possible (probed) values for the given property,
 277  * requires the property to have been probed before.
 278  *
 279  * Returns: A list of valid values for the given property.
 280  */
 281 GValueArray *
 282 gst_property_probe_get_values (GstPropertyProbe * probe,
 283     const GParamSpec * pspec)
 284 {
 285   GstPropertyProbeInterface *iface;
 286
 287   g_return_val_if_fail (probe != NULL, NULL);
 288   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), NULL);
 289   g_return_val_if_fail (pspec != NULL, NULL);
 290
 291   iface = GST_PROPERTY_PROBE_GET_IFACE (probe);
 292
 293   if (iface->get_values)
 294     return iface->get_values (probe, pspec->param_id, pspec);
 295
 296   return NULL;
 297 }
 298
 299 /**
 300  * gst_property_probe_get_values_name:
 301  * @probe: the #GstPropertyProbe object.
 302  * @name: the name of the property to get values for.
 303  *
 304  * Same as gst_property_probe_get_values ().
 305  *
 306  * Returns: A list of valid values for the given property.
 307  */
 308 GValueArray *
 309 gst_property_probe_get_values_name (GstPropertyProbe * probe,
 310     const gchar * name)
 311 {
 312   const GParamSpec *pspec;
 313
 314   g_return_val_if_fail (probe != NULL, NULL);
 315   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), NULL);
 316   g_return_val_if_fail (name != NULL, NULL);
 317
 318   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (probe), name);
 319   if (!pspec) {
 320     g_warning ("No such property %s", name);
 321     return NULL;
 322   }
 323
 324   return gst_property_probe_get_values (probe, pspec);
 325 }
 326
 327 /**
 328  * gst_property_probe_probe_and_get_values:
 329  * @probe: the #GstPropertyProbe object.
 330  * @pspec: The #GParamSpec property identifier.
 331  *
 332  * Check whether the given property requires a new probe. If so,
 333  * fo the probe. After that, retrieve a value list. Meant as a
 334  * utility function that wraps the above functions.
 335  *
 336  * Returns: the list of valid values for this property.
 337  */
 338 GValueArray *
 339 gst_property_probe_probe_and_get_values (GstPropertyProbe * probe,
 340     const GParamSpec * pspec)
 341 {
 342   g_return_val_if_fail (probe != NULL, NULL);
 343   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), NULL);
 344   g_return_val_if_fail (pspec != NULL, NULL);
 345
 346   if (gst_property_probe_needs_probe (probe, pspec))
 347     gst_property_probe_probe_property (probe, pspec);
 348
 349   return gst_property_probe_get_values (probe, pspec);
 350 }
 351
 352 /**
 353  * gst_property_probe_probe_and_get_values_name:
 354  * @probe: the #GstPropertyProbe object.
 355  * @name: the name of the property to get values for.
 356  *
 357  * Same as gst_property_probe_probe_and_get_values ().
 358  *
 359  * Returns: the list of valid values for this property.
 360  */
 361 GValueArray *
 362 gst_property_probe_probe_and_get_values_name (GstPropertyProbe * probe,
 363     const gchar * name)
 364 {
 365   const GParamSpec *pspec;
 366
 367   g_return_val_if_fail (probe != NULL, NULL);
 368   g_return_val_if_fail (GST_IS_PROPERTY_PROBE (probe), NULL);
 369   g_return_val_if_fail (name != NULL, NULL);
 370
 371   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (probe), name);
 372   if (!pspec) {
 373     g_warning ("No such property %s", name);
 374     return NULL;
 375   }
 376
 377   return gst_property_probe_probe_and_get_values (probe, pspec);
 378 }