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 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 * GstIndexAssociationFlags: 141 * @GST_INDEX_ASSOCIATION_FLAG_NONE: no extra flags 142 * @GST_INDEX_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_INDEX_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_INDEX_ASSOCIATION_FLAG_LAST: extra user defined flags should start here. 147 * 148 * Flags for an association entry. 149 */ 150 typedef enum { 151 GST_INDEX_ASSOCIATION_FLAG_NONE = 0, 152 GST_INDEX_ASSOCIATION_FLAG_KEY_UNIT = (1 << 0), 153 GST_INDEX_ASSOCIATION_FLAG_DELTA_UNIT = (1 << 1), 154 155 /* new flags should start here */ 156 GST_INDEX_ASSOCIATION_FLAG_LAST = (1 << 8) 157 } GstIndexAssociationFlags; 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 GstIndexAssociationFlags 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 GDestroyNotify resolver_user_data_destroy; 336 337 GstIndexFilter filter; 338 gpointer filter_user_data; 339 GDestroyNotify filter_user_data_destroy; 340 341 GHashTable *writers; 342 gint last_id; 343 344 /*< private >*/ 345 gpointer _gst_reserved[GST_PADDING]; 346 }; 347 348 struct _GstIndexClass { 349 GstObjectClass parent_class; 350 351 /*< protected >*/ 352 gboolean (*get_writer_id) (GstIndex *index, gint *id, gchar *writer); 353 354 void (*commit) (GstIndex *index, gint id); 355 356 /* abstract methods */ 357 void (*add_entry) (GstIndex *index, GstIndexEntry *entry); 358 359 GstIndexEntry* (*get_assoc_entry) (GstIndex *index, gint id, 360 GstIndexLookupMethod method, GstIndexAssociationFlags flags, 361 GstFormat format, gint64 value, 362 GCompareDataFunc func, 363 gpointer user_data); 364 /* signals */ 365 void (*entry_added) (GstIndex *index, GstIndexEntry *entry); 366 367 /*< private >*/ 368 gpointer _gst_reserved[GST_PADDING]; 369 }; 370 371 static 372 GType gst_index_get_type (void); 373 374 #if 0 375 GstIndex* gst_index_new (void); 376 #endif 377 void gst_index_commit (GstIndex *index, gint id); 378 379 #if 0 380 gint gst_index_get_group (GstIndex *index); 381 gint gst_index_new_group (GstIndex *index); 382 gboolean gst_index_set_group (GstIndex *index, gint groupnum); 383 384 void gst_index_set_certainty (GstIndex *index, 385 GstIndexCertainty certainty); 386 GstIndexCertainty gst_index_get_certainty (GstIndex *index); 387 388 static 389 void gst_index_set_filter (GstIndex *index, 390 GstIndexFilter filter, gpointer user_data); 391 static 392 void gst_index_set_filter_full (GstIndex *index, 393 GstIndexFilter filter, gpointer user_data, 394 GDestroyNotify user_data_destroy); 395 396 void gst_index_set_resolver (GstIndex *index, 397 GstIndexResolver resolver, gpointer user_data); 398 void gst_index_set_resolver_full (GstIndex *index, GstIndexResolver resolver, 399 gpointer user_data, 400 GDestroyNotify user_data_destroy); 401 #endif 402 403 static 404 gboolean gst_index_get_writer_id (GstIndex *index, GstObject *writer, gint *id); 405 406 #if 0 407 GstIndexEntry* gst_index_add_format (GstIndex *index, gint id, GstFormat format); 408 #endif 409 410 static 411 GstIndexEntry* gst_index_add_associationv (GstIndex * index, gint id, GstIndexAssociationFlags flags, 412 gint n, const GstIndexAssociation * list); 413 #if 0 414 GstIndexEntry* gst_index_add_association (GstIndex *index, gint id, GstIndexAssociationFlags flags, 415 GstFormat format, gint64 value, ...) 416 GstIndexEntry* gst_index_add_object (GstIndex *index, gint id, gchar *key, 417 GType type, gpointer object); 418 #endif 419 420 static 421 GstIndexEntry* gst_index_add_id (GstIndex *index, gint id, 422 gchar *description); 423 424 static 425 GstIndexEntry* gst_index_get_assoc_entry (GstIndex *index, gint id, 426 GstIndexLookupMethod method, GstIndexAssociationFlags flags, 427 GstFormat format, gint64 value); 428 static 429 GstIndexEntry* gst_index_get_assoc_entry_full (GstIndex *index, gint id, 430 GstIndexLookupMethod method, GstIndexAssociationFlags flags, 431 GstFormat format, gint64 value, 432 GCompareDataFunc func, 433 gpointer user_data); 434 435 /* working with index entries */ 436 static 437 GType gst_index_entry_get_type (void); 438 static 439 GstIndexEntry * gst_index_entry_copy (GstIndexEntry *entry); 440 static 441 void gst_index_entry_free (GstIndexEntry *entry); 442 static 443 gboolean gst_index_entry_assoc_map (GstIndexEntry *entry, 444 GstFormat format, gint64 *value); 445 446 G_END_DECLS 447 448 #endif /* __GST_INDEX_H__ */ 449