gst/gstindex.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wim.taymans@chello.be>
   4  *
   5  * gstindex.h: Header for GstIndex, base class to handle efficient
   6  *             storage or caching of seeking information.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #ifndef __GST_INDEX_H__
  25 #define __GST_INDEX_H__
  26
  27 #include <gst/gstobject.h>
  28 #include <gst/gstformat.h>
  29 #include <gst/gstpluginfeature.h>
  30
  31 G_BEGIN_DECLS
  32
  33 #define GST_TYPE_INDEX                  (gst_index_get_type ())
  34 #define GST_INDEX(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_INDEX, GstIndex))
  35 #define GST_IS_INDEX(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_INDEX))
  36 #define GST_INDEX_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_INDEX, GstIndexClass))
  37 #define GST_IS_INDEX_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_INDEX))
  38 #define GST_INDEX_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_INDEX, GstIndexClass))
  39
  40 #define GST_TYPE_INDEX_ENTRY            (gst_index_entry_get_type())
  41
  42 typedef struct _GstIndexEntry GstIndexEntry;
  43 typedef struct _GstIndexGroup GstIndexGroup;
  44 typedef struct _GstIndex GstIndex;
  45 typedef struct _GstIndexClass GstIndexClass;
  46
  47 /**
  48  * GstIndexCertainty:
  49  * @GST_INDEX_UNKNOWN: accuracy is not known
  50  * @GST_INDEX_CERTAIN: accuracy is perfect
  51  * @GST_INDEX_FUZZY: accuracy is fuzzy
  52  *
  53  * The certainty of a group in the index.
  54  */
  55 typedef enum {
  56   GST_INDEX_UNKNOWN,
  57   GST_INDEX_CERTAIN,
  58   GST_INDEX_FUZZY
  59 } GstIndexCertainty;
  60
  61 /**
  62  * GstIndexEntryType:
  63  * @GST_INDEX_ENTRY_ID: This entry is an id that maps an index id to its owner object
  64  * @GST_INDEX_ENTRY_ASSOCIATION: This entry is an association between formats
  65  * @GST_INDEX_ENTRY_OBJECT: An object
  66  * @GST_INDEX_ENTRY_FORMAT: A format definition
  67  *
  68  * The different types of entries in the index.
  69  */
  70 typedef enum {
  71   GST_INDEX_ENTRY_ID,
  72   GST_INDEX_ENTRY_ASSOCIATION,
  73   GST_INDEX_ENTRY_OBJECT,
  74   GST_INDEX_ENTRY_FORMAT
  75 } GstIndexEntryType;
  76
  77 /**
  78  * GstIndexLookupMethod:
  79  * @GST_INDEX_LOOKUP_EXACT: There has to be an exact indexentry with the given format/value
  80  * @GST_INDEX_LOOKUP_BEFORE: The exact entry or the one before it
  81  * @GST_INDEX_LOOKUP_AFTER: The exact entry or the one after it
  82  *
  83  * Specify the method to find an index entry in the index.
  84  */
  85 typedef enum {
  86   GST_INDEX_LOOKUP_EXACT,
  87   GST_INDEX_LOOKUP_BEFORE,
  88   GST_INDEX_LOOKUP_AFTER
  89 } GstIndexLookupMethod;
  90
  91 /**
  92  * GST_INDEX_NASSOCS:
  93  * @entry: The entry to query
  94  *
  95  * Get the number of associations in the entry.
  96  */
  97 #define GST_INDEX_NASSOCS(entry)                ((entry)->data.assoc.nassocs)
  98
  99 /**
 100  * GST_INDEX_ASSOC_FLAGS:
 101  * @entry: The entry to query
 102  *
 103  *  Get the flags for this entry.
 104  */
 105 #define GST_INDEX_ASSOC_FLAGS(entry)            ((entry)->data.assoc.flags)
 106
 107 /**
 108  * GST_INDEX_ASSOC_FORMAT:
 109  * @entry: The entry to query
 110  * @i: The format index
 111  *
 112  * Get the i-th format of the entry.
 113  */
 114 #define GST_INDEX_ASSOC_FORMAT(entry,i)         ((entry)->data.assoc.assocs[(i)].format)
 115
 116 /**
 117  * GST_INDEX_ASSOC_VALUE:
 118  * @entry: The entry to query
 119  * @i: The value index
 120  *
 121  * Get the i-th value of the entry.
 122  */
 123 #define GST_INDEX_ASSOC_VALUE(entry,i)          ((entry)->data.assoc.assocs[(i)].value)
 124
 125 typedef struct _GstIndexAssociation GstIndexAssociation;
 126
 127 /**
 128  * GstIndexAssociation:
 129  * @format: the format of the association
 130  * @value: the value of the association
 131  *
 132  * An association in an entry.
 133  */
 134 struct _GstIndexAssociation {
 135   GstFormat     format;
 136   gint64        value;
 137 };
 138
 139 /**
 140  * GstAssocFlags:
 141  * @GST_ASSOCIATION_FLAG_NONE: no extra flags
 142  * @GST_ASSOCIATION_FLAG_KEY_UNIT: the entry marks a key unit, a key unit is one
 143  *  that marks a place where one can randomly seek to.
 144  * @GST_ASSOCIATION_FLAG_DELTA_UNIT: the entry marks a delta unit, a delta unit
 145  *  is one that marks a place where one can relatively seek to.
 146  * @GST_ASSOCIATION_FLAG_LAST: extra user defined flags should start here.
 147  *
 148  * Flags for an association entry.
 149  */
 150 typedef enum {
 151   GST_ASSOCIATION_FLAG_NONE       = 0,
 152   GST_ASSOCIATION_FLAG_KEY_UNIT   = (1 << 0),
 153   GST_ASSOCIATION_FLAG_DELTA_UNIT = (1 << 1),
 154
 155   /* new flags should start here */
 156   GST_ASSOCIATION_FLAG_LAST     = (1 << 8)
 157 } GstAssocFlags;
 158
 159 /**
 160  * GST_INDEX_FORMAT_FORMAT:
 161  * @entry: The entry to query
 162  *
 163  * Get the format of the format entry
 164  */
 165 #define GST_INDEX_FORMAT_FORMAT(entry)          ((entry)->data.format.format)
 166
 167 /**
 168  * GST_INDEX_FORMAT_KEY:
 169  * @entry: The entry to query
 170  *
 171  * Get the key of the format entry
 172  */
 173 #define GST_INDEX_FORMAT_KEY(entry)             ((entry)->data.format.key)
 174
 175 /**
 176  * GST_INDEX_ID_INVALID:
 177  *
 178  * Constant for an invalid index id
 179  */
 180 #define GST_INDEX_ID_INVALID                    (-1)
 181
 182 /**
 183  * GST_INDEX_ID_DESCRIPTION:
 184  * @entry: The entry to query
 185  *
 186  * Get the description of the id entry
 187  */
 188 #define GST_INDEX_ID_DESCRIPTION(entry)         ((entry)->data.id.description)
 189
 190 /**
 191  * GstIndexEntry:
 192  *
 193  * The basic element of an index.
 194  */
 195 struct _GstIndexEntry {
 196   /*< private >*/
 197   GstIndexEntryType      type;
 198   gint                   id;
 199
 200   union {
 201     struct {
 202       gchar             *description;
 203     } id;
 204     struct {
 205       gint               nassocs;
 206       GstIndexAssociation
 207                         *assocs;
 208       GstAssocFlags      flags;
 209     } assoc;
 210     struct {
 211       gchar             *key;
 212       GType              type;
 213       gpointer           object;
 214     } object;
 215     struct {
 216       GstFormat          format;
 217       const gchar       *key;
 218     } format;
 219   } data;
 220 };
 221
 222 /**
 223  * GstIndexGroup:
 224  *
 225  * A group of related entries in an index.
 226  */
 227
 228 struct _GstIndexGroup {
 229   /*< private >*/
 230   /* unique ID of group in index */
 231   gint groupnum;
 232
 233   /* list of entries */
 234   GList *entries;
 235
 236   /* the certainty level of the group */
 237   GstIndexCertainty certainty;
 238
 239   /* peer group that contains more certain entries */
 240   gint peergroup;
 241 };
 242
 243 /**
 244  * GstIndexFilter:
 245  * @index: The index being queried
 246  * @entry: The entry to be added.
 247  * @user_data: User data passed to the function.
 248  *
 249  * Function to filter out entries in the index.
 250  *
 251  * Returns: This function should return %TRUE if the entry is to be added
 252  * to the index, %FALSE otherwise.
 253  *
 254  */
 255 typedef gboolean        (*GstIndexFilter)               (GstIndex *index,
 256                                                          GstIndexEntry *entry,
 257                                                          gpointer user_data);
 258 /**
 259  * GstIndexResolverMethod:
 260  * @GST_INDEX_RESOLVER_CUSTOM: Use a custom resolver
 261  * @GST_INDEX_RESOLVER_GTYPE: Resolve based on the GType of the object
 262  * @GST_INDEX_RESOLVER_PATH: Resolve on the path in graph
 263  *
 264  * The method used to resolve index writers
 265  */
 266 typedef enum {
 267   GST_INDEX_RESOLVER_CUSTOM,
 268   GST_INDEX_RESOLVER_GTYPE,
 269   GST_INDEX_RESOLVER_PATH
 270 } GstIndexResolverMethod;
 271
 272 /**
 273  * GstIndexResolver:
 274  * @index: the index being queried.
 275  * @writer: The object that wants to write
 276  * @writer_string: A description of the writer.
 277  * @user_data: user_data as registered
 278  *
 279  * Function to resolve ids to writer descriptions.
 280  *
 281  * Returns: %TRUE if an id could be assigned to the writer.
 282  */
 283 typedef gboolean        (*GstIndexResolver)             (GstIndex *index,
 284                                                          GstObject *writer,
 285                                                          gchar **writer_string,
 286                                                          gpointer user_data);
 287
 288 /**
 289  * GstIndexFlags:
 290  * @GST_INDEX_WRITABLE: The index is writable
 291  * @GST_INDEX_READABLE: The index is readable
 292  * @GST_INDEX_FLAG_LAST: First flag that can be used by subclasses
 293  *
 294  * Flags for this index
 295  */
 296 typedef enum {
 297   GST_INDEX_WRITABLE    = (GST_OBJECT_FLAG_LAST << 0),
 298   GST_INDEX_READABLE    = (GST_OBJECT_FLAG_LAST << 1),
 299
 300   GST_INDEX_FLAG_LAST   = (GST_OBJECT_FLAG_LAST << 8)
 301 } GstIndexFlags;
 302
 303 /**
 304  * GST_INDEX_IS_READABLE:
 305  * @obj: The index to check
 306  *
 307  * Check if the index can be read from
 308  */
 309 #define GST_INDEX_IS_READABLE(obj)    (GST_OBJECT_FLAG_IS_SET (obj, GST_INDEX_READABLE))
 310
 311 /**
 312  * GST_INDEX_IS_WRITABLE:
 313  * @obj: The index to check
 314  *
 315  * Check if the index can be written to
 316  */
 317 #define GST_INDEX_IS_WRITABLE(obj)    (GST_OBJECT_FLAG_IS_SET (obj, GST_INDEX_WRITABLE))
 318
 319 /**
 320  * GstIndex:
 321  *
 322  * Opaque #GstIndex structure.
 323  */
 324 struct _GstIndex {
 325   GstObject              object;
 326
 327   /*< private >*/
 328   GList                 *groups;
 329   GstIndexGroup         *curgroup;
 330   gint                   maxgroup;
 331
 332   GstIndexResolverMethod method;
 333   GstIndexResolver       resolver;
 334   gpointer               resolver_user_data;
 335
 336   GstIndexFilter         filter;
 337   gpointer               filter_user_data;
 338   GDestroyNotify         filter_user_data_destroy;
 339
 340   GHashTable            *writers;
 341   gint                   last_id;
 342
 343   /* ABI added since 0.10.18 */
 344   GDestroyNotify         resolver_user_data_destroy;
 345
 346   /*< private >*/
 347   gpointer _gst_reserved[GST_PADDING - 1];
 348 };
 349
 350 struct _GstIndexClass {
 351   GstObjectClass parent_class;
 352
 353   /*< protected >*/
 354   gboolean      (*get_writer_id)        (GstIndex *index, gint *writer_id, gchar *writer_string);
 355
 356   void          (*commit)               (GstIndex *index, gint id);
 357
 358   /* abstract methods */
 359   void          (*add_entry)            (GstIndex *index, GstIndexEntry *entry);
 360
 361   GstIndexEntry* (*get_assoc_entry)     (GstIndex *index, gint id,
 362                                          GstIndexLookupMethod method, GstAssocFlags flags,
 363                                          GstFormat format, gint64 value,
 364                                          GCompareDataFunc func,
 365                                          gpointer user_data);
 366   /* signals */
 367   void          (*entry_added)          (GstIndex *index, GstIndexEntry *entry);
 368
 369   /*< private >*/
 370   gpointer _gst_reserved[GST_PADDING];
 371 };
 372
 373 GType                   gst_index_get_type              (void);
 374 GstIndex*               gst_index_new                   (void);
 375 void                    gst_index_commit                (GstIndex *index, gint id);
 376
 377 gint                    gst_index_get_group             (GstIndex *index);
 378 gint                    gst_index_new_group             (GstIndex *index);
 379 gboolean                gst_index_set_group             (GstIndex *index, gint groupnum);
 380
 381 void                    gst_index_set_certainty         (GstIndex *index,
 382                                                          GstIndexCertainty certainty);
 383 GstIndexCertainty       gst_index_get_certainty         (GstIndex *index);
 384
 385 void                    gst_index_set_filter            (GstIndex *index,
 386                                                          GstIndexFilter filter, gpointer user_data);
 387 void                    gst_index_set_filter_full       (GstIndex *index,
 388                                                          GstIndexFilter filter, gpointer user_data,
 389                                                          GDestroyNotify user_data_destroy);
 390 void                    gst_index_set_resolver          (GstIndex *index,
 391                                                          GstIndexResolver resolver, gpointer user_data);
 392 void                    gst_index_set_resolver_full     (GstIndex *index, GstIndexResolver resolver,
 393                                                          gpointer user_data,
 394                                                          GDestroyNotify user_data_destroy);
 395
 396 gboolean                gst_index_get_writer_id         (GstIndex *index, GstObject *writer, gint *id);
 397
 398 GstIndexEntry*          gst_index_add_format            (GstIndex *index, gint id, GstFormat format);
 399 GstIndexEntry*          gst_index_add_associationv      (GstIndex * index, gint id, GstAssocFlags flags,
 400                                                          gint n, const GstIndexAssociation * list);
 401 GstIndexEntry*          gst_index_add_association       (GstIndex *index, gint id, GstAssocFlags flags,
 402                                                          GstFormat format, gint64 value, ...);
 403 GstIndexEntry*          gst_index_add_object            (GstIndex *index, gint id, gchar *key,
 404                                                          GType type, gpointer object);
 405 GstIndexEntry*          gst_index_add_id                (GstIndex *index, gint id,
 406                                                          gchar *description);
 407
 408 GstIndexEntry*          gst_index_get_assoc_entry       (GstIndex *index, gint id,
 409                                                          GstIndexLookupMethod method, GstAssocFlags flags,
 410                                                          GstFormat format, gint64 value);
 411 GstIndexEntry*          gst_index_get_assoc_entry_full  (GstIndex *index, gint id,
 412                                                          GstIndexLookupMethod method, GstAssocFlags flags,
 413                                                          GstFormat format, gint64 value,
 414                                                          GCompareDataFunc func,
 415                                                          gpointer user_data);
 416
 417 /* working with index entries */
 418 GType gst_index_entry_get_type (void);
 419 GstIndexEntry *         gst_index_entry_copy            (GstIndexEntry *entry);
 420 void                    gst_index_entry_free            (GstIndexEntry *entry);
 421 gboolean                gst_index_entry_assoc_map       (GstIndexEntry *entry,
 422                                                          GstFormat format, gint64 *value);
 423
 424 G_END_DECLS
 425
 426 #endif /* __GST_INDEX_H__ */