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