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)       (GST_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   GstIndexEntryType      type;
 197   gint                   id;
 198
 199   union {
 200     struct {
 201       gchar             *description;
 202     } id;
 203     struct {
 204       gint               nassocs;
 205       GstIndexAssociation
 206                         *assocs;
 207       GstAssocFlags      flags;
 208     } assoc;
 209     struct {
 210       gchar             *key;
 211       GType              type;
 212       gpointer           object;
 213     } object;
 214     struct {
 215       GstFormat          format;
 216       gchar             *key;
 217     } format;
 218   } data;
 219 };
 220
 221 /**
 222  * GstIndexGroup:
 223  *
 224  * A group of related entries in an index.
 225  */
 226
 227 struct _GstIndexGroup {
 228   /* unique ID of group in index */
 229   gint groupnum;
 230
 231   /* list of entries */
 232   GList *entries;
 233
 234   /* the certainty level of the group */
 235   GstIndexCertainty certainty;
 236
 237   /* peer group that contains more certain entries */
 238   gint peergroup;
 239 };
 240
 241 /**
 242  * GstIndexFilter:
 243  * @index: The index being queried
 244  * @entry: The entry to be added.
 245  *
 246  * Function to filter out entries in the index.
 247  *
 248  * Returns: This function should return %TRUE if the entry is to be added
 249  * to the index, %FALSE otherwise.
 250  *
 251  */
 252 typedef gboolean        (*GstIndexFilter)               (GstIndex *index,
 253                                                          GstIndexEntry *entry);
 254 /**
 255  * GstIndexResolverMethod:
 256  * @GST_INDEX_RESOLVER_CUSTOM: Use a custom resolver
 257  * @GST_INDEX_RESOLVER_GTYPE: Resolve based on the GType of the object
 258  * @GST_INDEX_RESOLVER_PATH: Resolve on the path in graph
 259  *
 260  * The method used to resolve index writers
 261  */
 262 typedef enum {
 263   GST_INDEX_RESOLVER_CUSTOM,
 264   GST_INDEX_RESOLVER_GTYPE,
 265   GST_INDEX_RESOLVER_PATH
 266 } GstIndexResolverMethod;
 267
 268 /**
 269  * GstIndexResolver:
 270  * @index: the index being queried.
 271  * @writer: The object that wants to write
 272  * @writer_string: A description of the writer.
 273  * @user_data: user_data as registered
 274  *
 275  * Function to resolve ids to writer descriptions.
 276  *
 277  * Returns: %TRUE if an id could be assigned to the writer.
 278  */
 279 typedef gboolean        (*GstIndexResolver)             (GstIndex *index,
 280                                                          GstObject *writer,
 281                                                          gchar **writer_string,
 282                                                          gpointer user_data);
 283
 284 /**
 285  * GstIndexFlags:
 286  * @GST_INDEX_WRITABLE: The index is writable
 287  * @GST_INDEX_READABLE: The index is readable
 288  * @GST_INDEX_FLAG_LAST: First flag that can be used by subclasses
 289  *
 290  * Flags for this index
 291  */
 292 typedef enum {
 293   GST_INDEX_WRITABLE            = GST_OBJECT_FLAG_LAST,
 294   GST_INDEX_READABLE,
 295
 296   GST_INDEX_FLAG_LAST           = GST_OBJECT_FLAG_LAST + 8
 297 } GstIndexFlags;
 298
 299 /**
 300  * GST_INDEX_IS_READABLE:
 301  * @obj: The index to check
 302  *
 303  * Check if the index can be read from
 304  */
 305 #define GST_INDEX_IS_READABLE(obj)    (GST_FLAG_IS_SET (obj, GST_INDEX_READABLE))
 306
 307 /**
 308  * GST_INDEX_IS_WRITABLE:
 309  * @obj: The index to check
 310  *
 311  * Check if the index can be written to
 312  */
 313 #define GST_INDEX_IS_WRITABLE(obj)    (GST_FLAG_IS_SET (obj, GST_INDEX_WRITABLE))
 314
 315 struct _GstIndex {
 316   GstObject              object;
 317
 318   GList                 *groups;
 319   GstIndexGroup         *curgroup;
 320   gint                   maxgroup;
 321
 322   GstIndexResolverMethod method;
 323   GstIndexResolver       resolver;
 324   gpointer               resolver_user_data;
 325
 326   GstIndexFilter         filter;
 327   gpointer               filter_user_data;
 328
 329   GHashTable            *writers;
 330   gint                   last_id;
 331
 332   gpointer _gst_reserved[GST_PADDING];
 333 };
 334
 335 struct _GstIndexClass {
 336   GstObjectClass parent_class;
 337
 338   gboolean      (*get_writer_id)        (GstIndex *index, gint *writer_id, gchar *writer_string);
 339
 340   void          (*commit)               (GstIndex *index, gint id);
 341
 342   /* abstract methods */
 343   void          (*add_entry)            (GstIndex *index, GstIndexEntry *entry);
 344
 345   GstIndexEntry* (*get_assoc_entry)     (GstIndex *index, gint id,
 346                                          GstIndexLookupMethod method, GstAssocFlags flags,
 347                                          GstFormat format, gint64 value,
 348                                          GCompareDataFunc func,
 349                                          gpointer user_data);
 350   /* signals */
 351   void          (*entry_added)          (GstIndex *index, GstIndexEntry *entry);
 352
 353   gpointer _gst_reserved[GST_PADDING];
 354 };
 355
 356 GType                   gst_index_get_type              (void);
 357 GstIndex*               gst_index_new                   (void);
 358 void                    gst_index_commit                (GstIndex *index, gint id);
 359
 360 gint                    gst_index_get_group             (GstIndex *index);
 361 gint                    gst_index_new_group             (GstIndex *index);
 362 gboolean                gst_index_set_group             (GstIndex *index, gint groupnum);
 363
 364 void                    gst_index_set_certainty         (GstIndex *index,
 365                                                          GstIndexCertainty certainty);
 366 GstIndexCertainty       gst_index_get_certainty         (GstIndex *index);
 367
 368 void                    gst_index_set_filter            (GstIndex *index,
 369                                                          GstIndexFilter filter, gpointer user_data);
 370 void                    gst_index_set_resolver          (GstIndex *index,
 371                                                          GstIndexResolver resolver, gpointer user_data);
 372
 373 gboolean                gst_index_get_writer_id         (GstIndex *index, GstObject *writer, gint *id);
 374
 375 GstIndexEntry*          gst_index_add_format            (GstIndex *index, gint id, GstFormat format);
 376 GstIndexEntry*          gst_index_add_association       (GstIndex *index, gint id, GstAssocFlags flags,
 377                                                          GstFormat format, gint64 value, ...);
 378 GstIndexEntry*          gst_index_add_object            (GstIndex *index, gint id, gchar *key,
 379                                                          GType type, gpointer object);
 380 GstIndexEntry*          gst_index_add_id                (GstIndex *index, gint id,
 381                                                          gchar *description);
 382
 383 GstIndexEntry*          gst_index_get_assoc_entry       (GstIndex *index, gint id,
 384                                                          GstIndexLookupMethod method, GstAssocFlags flags,
 385                                                          GstFormat format, gint64 value);
 386 GstIndexEntry*          gst_index_get_assoc_entry_full  (GstIndex *index, gint id,
 387                                                          GstIndexLookupMethod method, GstAssocFlags flags,
 388                                                          GstFormat format, gint64 value,
 389                                                          GCompareDataFunc func,
 390                                                          gpointer user_data);
 391
 392 /* working with index entries */
 393 GType gst_index_entry_get_type (void);
 394 GstIndexEntry *         gst_index_entry_copy            (GstIndexEntry *entry);
 395 void                    gst_index_entry_free            (GstIndexEntry *entry);
 396 gboolean                gst_index_entry_assoc_map       (GstIndexEntry *entry,
 397                                                          GstFormat format, gint64 *value);
 398
 399 G_END_DECLS
 400
 401 #endif /* __GST_INDEX_H__ */