gst/gstindex.c

   1 /* GStreamer
   2  * Copyright (C) 2001 RidgeRun (http://www.ridgerun.com/)
   3  * Written by Erik Walthinsen <omega@ridgerun.com>
   4  *
   5  * gstindex.c: Index for mappings and other data
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstindex
  25  * @short_description: Generate indexes on objects
  26  * @see_also: #GstIndexFactory
  27  *
  28  * GstIndex is used to generate a stream index of one or more elements
  29  * in a pipeline.
  30  */
  31
  32 #include "gst_private.h"
  33
  34 #include "gstinfo.h"
  35 #include "gstindex.h"
  36 #include "gstindexfactory.h"
  37 #include "gstmarshal.h"
  38 #include "gstregistry.h"
  39 /* for constructing an entry name */
  40 #include "gstelement.h"
  41 #include "gstpad.h"
  42 #include "gstinfo.h"
  43
  44 /* Index signals and args */
  45 enum
  46 {
  47   ENTRY_ADDED,
  48   LAST_SIGNAL
  49 };
  50
  51 enum
  52 {
  53   ARG_0,
  54   ARG_RESOLVER
  55       /* FILL ME */
  56 };
  57
  58 GST_DEBUG_CATEGORY_STATIC (index_debug);
  59 #define GST_CAT_DEFAULT index_debug
  60
  61 static void gst_index_finalize (GObject * object);
  62
  63 static void gst_index_set_property (GObject * object, guint prop_id,
  64     const GValue * value, GParamSpec * pspec);
  65 static void gst_index_get_property (GObject * object, guint prop_id,
  66     GValue * value, GParamSpec * pspec);
  67
  68 static GstIndexGroup *gst_index_group_new (guint groupnum);
  69
  70 static gboolean gst_index_path_resolver (GstIndex * index, GstObject * writer,
  71     gchar ** writer_string, gpointer data);
  72 static gboolean gst_index_gtype_resolver (GstIndex * index, GstObject * writer,
  73     gchar ** writer_string, gpointer data);
  74 static void gst_index_add_entry (GstIndex * index, GstIndexEntry * entry);
  75
  76 static GstObject *parent_class = NULL;
  77 static guint gst_index_signals[LAST_SIGNAL] = { 0 };
  78
  79 typedef struct
  80 {
  81   GstIndexResolverMethod method;
  82   GstIndexResolver resolver;
  83   gpointer user_data;
  84 }
  85 ResolverEntry;
  86
  87 static const ResolverEntry resolvers[] = {
  88   {GST_INDEX_RESOLVER_CUSTOM, NULL, NULL},
  89   {GST_INDEX_RESOLVER_GTYPE, gst_index_gtype_resolver, NULL},
  90   {GST_INDEX_RESOLVER_PATH, gst_index_path_resolver, NULL},
  91 };
  92
  93 #define GST_TYPE_INDEX_RESOLVER (gst_index_resolver_get_type())
  94 static GType
  95 gst_index_resolver_get_type (void)
  96 {
  97   static GType index_resolver_type = 0;
  98   static const GEnumValue index_resolver[] = {
  99     {GST_INDEX_RESOLVER_CUSTOM, "GST_INDEX_RESOLVER_CUSTOM", "custom"},
 100     {GST_INDEX_RESOLVER_GTYPE, "GST_INDEX_RESOLVER_GTYPE", "gtype"},
 101     {GST_INDEX_RESOLVER_PATH, "GST_INDEX_RESOLVER_PATH", "path"},
 102     {0, NULL, NULL},
 103   };
 104
 105   if (!index_resolver_type) {
 106     index_resolver_type =
 107         g_enum_register_static ("GstIndexResolver", index_resolver);
 108   }
 109   return index_resolver_type;
 110 }
 111
 112 GType
 113 gst_index_entry_get_type (void)
 114 {
 115   static GType index_entry_type = 0;
 116
 117   if (!index_entry_type) {
 118     index_entry_type = g_boxed_type_register_static ("GstIndexEntry",
 119         (GBoxedCopyFunc) gst_index_entry_copy,
 120         (GBoxedFreeFunc) gst_index_entry_free);
 121   }
 122   return index_entry_type;
 123 }
 124
 125 #define _do_init \
 126 { \
 127   GST_DEBUG_CATEGORY_INIT (index_debug, "GST_INDEX", GST_DEBUG_BOLD, \
 128       "Generic indexing support"); \
 129 }
 130
 131 G_DEFINE_TYPE_WITH_CODE (GstIndex, gst_index, GST_TYPE_OBJECT, _do_init);
 132
 133 static void
 134 gst_index_class_init (GstIndexClass * klass)
 135 {
 136   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 137
 138   parent_class = g_type_class_peek_parent (klass);
 139
 140   /**
 141    * GstIndex::entry-added
 142    * @gstindex: the object which received the signal.
 143    * @arg1: The entry added to the index.
 144    *
 145    * Is emitted when a new entry is added to the index.
 146    */
 147   gst_index_signals[ENTRY_ADDED] =
 148       g_signal_new ("entry-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 149       G_STRUCT_OFFSET (GstIndexClass, entry_added), NULL, NULL,
 150       gst_marshal_VOID__BOXED, G_TYPE_NONE, 1, GST_TYPE_INDEX_ENTRY);
 151
 152   gobject_class->set_property = gst_index_set_property;
 153   gobject_class->get_property = gst_index_get_property;
 154   gobject_class->finalize = gst_index_finalize;
 155
 156   g_object_class_install_property (gobject_class, ARG_RESOLVER,
 157       g_param_spec_enum ("resolver", "Resolver",
 158           "Select a predefined object to string mapper",
 159           GST_TYPE_INDEX_RESOLVER, GST_INDEX_RESOLVER_PATH,
 160           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 161 }
 162
 163 static void
 164 gst_index_init (GstIndex * index)
 165 {
 166   index->curgroup = gst_index_group_new (0);
 167   index->maxgroup = 0;
 168   index->groups = g_list_prepend (NULL, index->curgroup);
 169
 170   index->writers = g_hash_table_new (NULL, NULL);
 171   index->last_id = 0;
 172
 173   index->method = GST_INDEX_RESOLVER_PATH;
 174   index->resolver = resolvers[index->method].resolver;
 175   index->resolver_user_data = resolvers[index->method].user_data;
 176
 177   GST_OBJECT_FLAG_SET (index, GST_INDEX_WRITABLE);
 178   GST_OBJECT_FLAG_SET (index, GST_INDEX_READABLE);
 179
 180   GST_DEBUG ("created new index");
 181 }
 182
 183 static void
 184 gst_index_free_writer (gpointer key, gpointer value, gpointer user_data)
 185 {
 186   GstIndexEntry *entry = (GstIndexEntry *) value;
 187
 188   if (entry) {
 189     gst_index_entry_free (entry);
 190   }
 191 }
 192
 193 static void
 194 gst_index_finalize (GObject * object)
 195 {
 196   GstIndex *index = GST_INDEX (object);
 197
 198   if (index->groups) {
 199     g_list_foreach (index->groups, (GFunc) g_free, NULL);
 200     g_list_free (index->groups);
 201     index->groups = NULL;
 202   }
 203
 204   if (index->writers) {
 205     g_hash_table_foreach (index->writers, gst_index_free_writer, NULL);
 206     g_hash_table_destroy (index->writers);
 207     index->writers = NULL;
 208   }
 209
 210   if (index->filter_user_data && index->filter_user_data_destroy)
 211     index->filter_user_data_destroy (index->filter_user_data);
 212
 213   if (index->resolver_user_data && index->resolver_user_data_destroy)
 214     index->resolver_user_data_destroy (index->resolver_user_data);
 215
 216   G_OBJECT_CLASS (parent_class)->finalize (object);
 217 }
 218
 219 static void
 220 gst_index_set_property (GObject * object, guint prop_id,
 221     const GValue * value, GParamSpec * pspec)
 222 {
 223   GstIndex *index;
 224
 225   index = GST_INDEX (object);
 226
 227   switch (prop_id) {
 228     case ARG_RESOLVER:
 229       index->method = g_value_get_enum (value);
 230       index->resolver = resolvers[index->method].resolver;
 231       index->resolver_user_data = resolvers[index->method].user_data;
 232       break;
 233     default:
 234       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 235       break;
 236   }
 237 }
 238
 239 static void
 240 gst_index_get_property (GObject * object, guint prop_id,
 241     GValue * value, GParamSpec * pspec)
 242 {
 243   GstIndex *index;
 244
 245   index = GST_INDEX (object);
 246
 247   switch (prop_id) {
 248     case ARG_RESOLVER:
 249       g_value_set_enum (value, index->method);
 250       break;
 251     default:
 252       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 253       break;
 254   }
 255 }
 256
 257 static GstIndexGroup *
 258 gst_index_group_new (guint groupnum)
 259 {
 260   GstIndexGroup *indexgroup = g_new (GstIndexGroup, 1);
 261
 262   indexgroup->groupnum = groupnum;
 263   indexgroup->entries = NULL;
 264   indexgroup->certainty = GST_INDEX_UNKNOWN;
 265   indexgroup->peergroup = -1;
 266
 267   GST_DEBUG ("created new index group %d", groupnum);
 268
 269   return indexgroup;
 270 }
 271
 272 /**
 273  * gst_index_new:
 274  *
 275  * Create a new tileindex object
 276  *
 277  * Returns: a new index object
 278  */
 279 GstIndex *
 280 gst_index_new (void)
 281 {
 282   GstIndex *index;
 283
 284   index = g_object_newv (gst_index_get_type (), 0, NULL);
 285
 286   return index;
 287 }
 288
 289 /**
 290  * gst_index_commit:
 291  * @index: the index to commit
 292  * @id: the writer that commited the index
 293  *
 294  * Tell the index that the writer with the given id is done
 295  * with this index and is not going to write any more entries
 296  * to it.
 297  */
 298 void
 299 gst_index_commit (GstIndex * index, gint id)
 300 {
 301   GstIndexClass *iclass;
 302
 303   iclass = GST_INDEX_GET_CLASS (index);
 304
 305   if (iclass->commit)
 306     iclass->commit (index, id);
 307 }
 308
 309
 310 /**
 311  * gst_index_get_group:
 312  * @index: the index to get the current group from
 313  *
 314  * Get the id of the current group.
 315  *
 316  * Returns: the id of the current group.
 317  */
 318 gint
 319 gst_index_get_group (GstIndex * index)
 320 {
 321   return index->curgroup->groupnum;
 322 }
 323
 324 /**
 325  * gst_index_new_group:
 326  * @index: the index to create the new group in
 327  *
 328  * Create a new group for the given index. It will be
 329  * set as the current group.
 330  *
 331  * Returns: the id of the newly created group.
 332  */
 333 gint
 334 gst_index_new_group (GstIndex * index)
 335 {
 336   index->curgroup = gst_index_group_new (++index->maxgroup);
 337   index->groups = g_list_append (index->groups, index->curgroup);
 338   GST_DEBUG ("created new group %d in index", index->maxgroup);
 339   return index->maxgroup;
 340 }
 341
 342 /**
 343  * gst_index_set_group:
 344  * @index: the index to set the new group in
 345  * @groupnum: the groupnumber to set
 346  *
 347  * Set the current groupnumber to the given argument.
 348  *
 349  * Returns: TRUE if the operation succeeded, FALSE if the group
 350  * did not exist.
 351  */
 352 gboolean
 353 gst_index_set_group (GstIndex * index, gint groupnum)
 354 {
 355   GList *list;
 356   GstIndexGroup *indexgroup;
 357
 358   /* first check for null change */
 359   if (groupnum == index->curgroup->groupnum)
 360     return TRUE;
 361
 362   /* else search for the proper group */
 363   list = index->groups;
 364   while (list) {
 365     indexgroup = (GstIndexGroup *) (list->data);
 366     list = g_list_next (list);
 367     if (indexgroup->groupnum == groupnum) {
 368       index->curgroup = indexgroup;
 369       GST_DEBUG ("switched to index group %d", indexgroup->groupnum);
 370       return TRUE;
 371     }
 372   }
 373
 374   /* couldn't find the group in question */
 375   GST_DEBUG ("couldn't find index group %d", groupnum);
 376   return FALSE;
 377 }
 378
 379 /**
 380  * gst_index_set_certainty:
 381  * @index: the index to set the certainty on
 382  * @certainty: the certainty to set
 383  *
 384  * Set the certainty of the given index.
 385  */
 386 void
 387 gst_index_set_certainty (GstIndex * index, GstIndexCertainty certainty)
 388 {
 389   index->curgroup->certainty = certainty;
 390 }
 391
 392 /**
 393  * gst_index_get_certainty:
 394  * @index: the index to get the certainty of
 395  *
 396  * Get the certainty of the given index.
 397  *
 398  * Returns: the certainty of the index.
 399  */
 400 GstIndexCertainty
 401 gst_index_get_certainty (GstIndex * index)
 402 {
 403   return index->curgroup->certainty;
 404 }
 405
 406 /**
 407  * gst_index_set_filter:
 408  * @index: the index to register the filter on
 409  * @filter: the filter to register
 410  * @user_data: data passed to the filter function
 411  *
 412  * Lets the app register a custom filter function so that
 413  * it can select what entries should be stored in the index.
 414  */
 415 void
 416 gst_index_set_filter (GstIndex * index,
 417     GstIndexFilter filter, gpointer user_data)
 418 {
 419   g_return_if_fail (GST_IS_INDEX (index));
 420
 421   gst_index_set_filter_full (index, filter, user_data, NULL);
 422 }
 423
 424 /**
 425  * gst_index_set_filter_full:
 426  * @index: the index to register the filter on
 427  * @filter: the filter to register
 428  * @user_data: data passed to the filter function
 429  * @user_data_destroy: function to call when @user_data is unset
 430  *
 431  * Lets the app register a custom filter function so that
 432  * it can select what entries should be stored in the index.
 433  */
 434 void
 435 gst_index_set_filter_full (GstIndex * index,
 436     GstIndexFilter filter, gpointer user_data, GDestroyNotify user_data_destroy)
 437 {
 438   g_return_if_fail (GST_IS_INDEX (index));
 439
 440   if (index->filter_user_data && index->filter_user_data_destroy)
 441     index->filter_user_data_destroy (index->filter_user_data);
 442
 443   index->filter = filter;
 444   index->filter_user_data = user_data;
 445   index->filter_user_data_destroy = user_data_destroy;
 446 }
 447
 448 /**
 449  * gst_index_set_resolver:
 450  * @index: the index to register the resolver on
 451  * @resolver: the resolver to register
 452  * @user_data: data passed to the resolver function
 453  *
 454  * Lets the app register a custom function to map index
 455  * ids to writer descriptions.
 456  */
 457 void
 458 gst_index_set_resolver (GstIndex * index,
 459     GstIndexResolver resolver, gpointer user_data)
 460 {
 461   gst_index_set_resolver_full (index, resolver, user_data, NULL);
 462 }
 463
 464 /**
 465  * gst_index_set_resolver_full:
 466  * @index: the index to register the resolver on
 467  * @resolver: the resolver to register
 468  * @user_data: data passed to the resolver function
 469  * @user_data_destroy: destroy function for @user_data
 470  *
 471  * Lets the app register a custom function to map index
 472  * ids to writer descriptions.
 473  *
 474  * Since: 0.10.18
 475  */
 476 void
 477 gst_index_set_resolver_full (GstIndex * index, GstIndexResolver resolver,
 478     gpointer user_data, GDestroyNotify user_data_destroy)
 479 {
 480   g_return_if_fail (GST_IS_INDEX (index));
 481
 482   if (index->resolver_user_data && index->resolver_user_data_destroy)
 483     index->resolver_user_data_destroy (index->resolver_user_data);
 484
 485   index->resolver = resolver;
 486   index->resolver_user_data = user_data;
 487   index->resolver_user_data_destroy = user_data_destroy;
 488   index->method = GST_INDEX_RESOLVER_CUSTOM;
 489 }
 490
 491 /**
 492  * gst_index_entry_copy:
 493  * @entry: the entry to copy
 494  *
 495  * Copies an entry and returns the result.
 496  *
 497  * Returns: a newly allocated #GstIndexEntry.
 498  */
 499 GstIndexEntry *
 500 gst_index_entry_copy (GstIndexEntry * entry)
 501 {
 502   return g_memdup (entry, sizeof (*entry));
 503 }
 504
 505 /**
 506  * gst_index_entry_free:
 507  * @entry: the entry to free
 508  *
 509  * Free the memory used by the given entry.
 510  */
 511 void
 512 gst_index_entry_free (GstIndexEntry * entry)
 513 {
 514   switch (entry->type) {
 515     case GST_INDEX_ENTRY_ID:
 516       if (entry->data.id.description) {
 517         g_free (entry->data.id.description);
 518         entry->data.id.description = NULL;
 519       }
 520       break;
 521     case GST_INDEX_ENTRY_ASSOCIATION:
 522       if (entry->data.assoc.assocs) {
 523         g_free (entry->data.assoc.assocs);
 524         entry->data.assoc.assocs = NULL;
 525       }
 526       break;
 527     case GST_INDEX_ENTRY_OBJECT:
 528       break;
 529     case GST_INDEX_ENTRY_FORMAT:
 530       break;
 531   }
 532
 533   g_free (entry);
 534 }
 535
 536 /**
 537  * gst_index_add_format:
 538  * @index: the index to add the entry to
 539  * @id: the id of the index writer
 540  * @format: the format to add to the index
 541  *
 542  * Adds a format entry into the index. This function is
 543  * used to map dynamic GstFormat ids to their original
 544  * format key.
 545  *
 546  * Returns: a pointer to the newly added entry in the index.
 547  */
 548 GstIndexEntry *
 549 gst_index_add_format (GstIndex * index, gint id, GstFormat format)
 550 {
 551   GstIndexEntry *entry;
 552   const GstFormatDefinition *def;
 553
 554   g_return_val_if_fail (GST_IS_INDEX (index), NULL);
 555   g_return_val_if_fail (format != 0, NULL);
 556
 557   if (!GST_INDEX_IS_WRITABLE (index) || id == -1)
 558     return NULL;
 559
 560   entry = g_new0 (GstIndexEntry, 1);
 561   entry->type = GST_INDEX_ENTRY_FORMAT;
 562   entry->id = id;
 563   entry->data.format.format = format;
 564
 565   def = gst_format_get_details (format);
 566   entry->data.format.key = def->nick;
 567
 568   gst_index_add_entry (index, entry);
 569
 570   return entry;
 571 }
 572
 573 /**
 574  * gst_index_add_id:
 575  * @index: the index to add the entry to
 576  * @id: the id of the index writer
 577  * @description: the description of the index writer
 578  *
 579  * Add an id entry into the index.
 580  *
 581  * Returns: a pointer to the newly added entry in the index.
 582  */
 583 GstIndexEntry *
 584 gst_index_add_id (GstIndex * index, gint id, gchar * description)
 585 {
 586   GstIndexEntry *entry;
 587
 588   g_return_val_if_fail (GST_IS_INDEX (index), NULL);
 589   g_return_val_if_fail (description != NULL, NULL);
 590
 591   if (!GST_INDEX_IS_WRITABLE (index) || id == -1)
 592     return NULL;
 593
 594   entry = g_new0 (GstIndexEntry, 1);
 595   entry->type = GST_INDEX_ENTRY_ID;
 596   entry->id = id;
 597   entry->data.id.description = description;
 598
 599   gst_index_add_entry (index, entry);
 600
 601   return entry;
 602 }
 603
 604 static gboolean
 605 gst_index_path_resolver (GstIndex * index, GstObject * writer,
 606     gchar ** writer_string, gpointer data)
 607 {
 608   *writer_string = gst_object_get_path_string (writer);
 609
 610   return TRUE;
 611 }
 612
 613 static gboolean
 614 gst_index_gtype_resolver (GstIndex * index, GstObject * writer,
 615     gchar ** writer_string, gpointer data)
 616 {
 617   g_return_val_if_fail (writer != NULL, FALSE);
 618
 619   if (GST_IS_PAD (writer)) {
 620     GstElement *element =
 621         (GstElement *) gst_object_get_parent (GST_OBJECT (writer));
 622     gchar *name;
 623
 624     name = gst_object_get_name (writer);
 625     *writer_string = g_strdup_printf ("%s.%s",
 626         g_type_name (G_OBJECT_TYPE (element)), name);
 627
 628     gst_object_unref (element);
 629     g_free (name);
 630
 631   } else {
 632     *writer_string =
 633         g_strdup_printf ("%s", g_type_name (G_OBJECT_TYPE (writer)));
 634   }
 635
 636   return TRUE;
 637 }
 638
 639 /**
 640  * gst_index_get_writer_id:
 641  * @index: the index to get a unique write id for
 642  * @writer: the GstObject to allocate an id for
 643  * @id: a pointer to a gint to hold the id
 644  *
 645  * Before entries can be added to the index, a writer
 646  * should obtain a unique id. The methods to add new entries
 647  * to the index require this id as an argument.
 648  *
 649  * The application can implement a custom function to map the writer object
 650  * to a string. That string will be used to register or look up an id
 651  * in the index.
 652  *
 653  * Returns: TRUE if the writer would be mapped to an id.
 654  */
 655 gboolean
 656 gst_index_get_writer_id (GstIndex * index, GstObject * writer, gint * id)
 657 {
 658   gchar *writer_string = NULL;
 659   GstIndexEntry *entry;
 660   GstIndexClass *iclass;
 661   gboolean success = FALSE;
 662
 663   g_return_val_if_fail (GST_IS_INDEX (index), FALSE);
 664   g_return_val_if_fail (GST_IS_OBJECT (writer), FALSE);
 665   g_return_val_if_fail (id, FALSE);
 666
 667   *id = -1;
 668
 669   /* first try to get a previously cached id */
 670   entry = g_hash_table_lookup (index->writers, writer);
 671   if (entry == NULL) {
 672
 673     iclass = GST_INDEX_GET_CLASS (index);
 674
 675     /* let the app make a string */
 676     if (index->resolver) {
 677       gboolean res;
 678
 679       res =
 680           index->resolver (index, writer, &writer_string,
 681           index->resolver_user_data);
 682       if (!res)
 683         return FALSE;
 684     } else {
 685       g_warning ("no resolver found");
 686       return FALSE;
 687     }
 688
 689     /* if the index has a resolver, make it map this string to an id */
 690     if (iclass->get_writer_id) {
 691       success = iclass->get_writer_id (index, id, writer_string);
 692     }
 693     /* if the index could not resolve, we allocate one ourselves */
 694     if (!success) {
 695       *id = ++index->last_id;
 696     }
 697
 698     entry = gst_index_add_id (index, *id, writer_string);
 699     if (!entry) {
 700       /* index is probably not writable, make an entry anyway
 701        * to keep it in our cache */
 702       entry = g_new0 (GstIndexEntry, 1);
 703       entry->type = GST_INDEX_ENTRY_ID;
 704       entry->id = *id;
 705       entry->data.id.description = writer_string;
 706     }
 707     g_hash_table_insert (index->writers, writer, entry);
 708   } else {
 709     *id = entry->id;
 710   }
 711
 712   return TRUE;
 713 }
 714
 715 static void
 716 gst_index_add_entry (GstIndex * index, GstIndexEntry * entry)
 717 {
 718   GstIndexClass *iclass;
 719
 720   iclass = GST_INDEX_GET_CLASS (index);
 721
 722   if (iclass->add_entry) {
 723     iclass->add_entry (index, entry);
 724   }
 725
 726   g_signal_emit (index, gst_index_signals[ENTRY_ADDED], 0, entry);
 727 }
 728
 729 /**
 730  * gst_index_add_associationv:
 731  * @index: the index to add the entry to
 732  * @id: the id of the index writer
 733  * @flags: optinal flags for this entry
 734  * @n: number of associations
 735  * @list: list of associations
 736  *
 737  * Associate given format/value pairs with each other.
 738  *
 739  * Returns: a pointer to the newly added entry in the index.
 740  */
 741 GstIndexEntry *
 742 gst_index_add_associationv (GstIndex * index, gint id, GstAssocFlags flags,
 743     gint n, const GstIndexAssociation * list)
 744 {
 745   GstIndexEntry *entry;
 746
 747   g_return_val_if_fail (n > 0, NULL);
 748   g_return_val_if_fail (list != NULL, NULL);
 749   g_return_val_if_fail (GST_IS_INDEX (index), NULL);
 750
 751   if (!GST_INDEX_IS_WRITABLE (index) || id == -1)
 752     return NULL;
 753
 754   entry = g_malloc (sizeof (GstIndexEntry));
 755
 756   entry->type = GST_INDEX_ENTRY_ASSOCIATION;
 757   entry->id = id;
 758   entry->data.assoc.flags = flags;
 759   entry->data.assoc.assocs = g_memdup (list, sizeof (GstIndexAssociation) * n);
 760   entry->data.assoc.nassocs = n;
 761
 762   gst_index_add_entry (index, entry);
 763
 764   return entry;
 765 }
 766
 767 /**
 768  * gst_index_add_association:
 769  * @index: the index to add the entry to
 770  * @id: the id of the index writer
 771  * @flags: optinal flags for this entry
 772  * @format: the format of the value
 773  * @value: the value
 774  * @...: other format/value pairs or 0 to end the list
 775  *
 776  * Associate given format/value pairs with each other.
 777  * Be sure to pass gint64 values to this functions varargs,
 778  * you might want to use a gint64 cast to be sure.
 779  *
 780  * Returns: a pointer to the newly added entry in the index.
 781  */
 782 GstIndexEntry *
 783 gst_index_add_association (GstIndex * index, gint id, GstAssocFlags flags,
 784     GstFormat format, gint64 value, ...)
 785 {
 786   va_list args;
 787   GstIndexEntry *entry;
 788   GstIndexAssociation *list;
 789   gint n_assocs = 0;
 790   GstFormat cur_format;
 791   GArray *array;
 792
 793   g_return_val_if_fail (GST_IS_INDEX (index), NULL);
 794   g_return_val_if_fail (format != 0, NULL);
 795
 796   if (!GST_INDEX_IS_WRITABLE (index) || id == -1)
 797     return NULL;
 798
 799   array = g_array_new (FALSE, FALSE, sizeof (GstIndexAssociation));
 800
 801   {
 802     GstIndexAssociation a;
 803
 804     a.format = format;
 805     a.value = value;
 806     n_assocs = 1;
 807     g_array_append_val (array, a);
 808   }
 809
 810   va_start (args, value);
 811
 812   while ((cur_format = va_arg (args, GstFormat))) {
 813     GstIndexAssociation a;
 814
 815     a.format = cur_format;
 816     a.value = va_arg (args, gint64);
 817     n_assocs++;
 818     g_array_append_val (array, a);
 819   }
 820
 821   va_end (args);
 822
 823   list = (GstIndexAssociation *) g_array_free (array, FALSE);
 824
 825   entry = gst_index_add_associationv (index, id, flags, n_assocs, list);
 826   g_free (list);
 827
 828   return entry;
 829 }
 830
 831 /**
 832  * gst_index_add_object:
 833  * @index: the index to add the object to
 834  * @id: the id of the index writer
 835  * @key: a key for the object
 836  * @type: the GType of the object
 837  * @object: a pointer to the object to add
 838  *
 839  * Add the given object to the index with the given key.
 840  *
 841  * This function is not yet implemented.
 842  *
 843  * Returns: a pointer to the newly added entry in the index.
 844  */
 845 GstIndexEntry *
 846 gst_index_add_object (GstIndex * index, gint id, gchar * key,
 847     GType type, gpointer object)
 848 {
 849   if (!GST_INDEX_IS_WRITABLE (index) || id == -1)
 850     return NULL;
 851
 852   return NULL;
 853 }
 854
 855 static gint
 856 gst_index_compare_func (gconstpointer a, gconstpointer b, gpointer user_data)
 857 {
 858   if (a < b)
 859     return -1;
 860   if (a > b)
 861     return 1;
 862   return 0;
 863 }
 864
 865 /**
 866  * gst_index_get_assoc_entry:
 867  * @index: the index to search
 868  * @id: the id of the index writer
 869  * @method: The lookup method to use
 870  * @flags: Flags for the entry
 871  * @format: the format of the value
 872  * @value: the value to find
 873  *
 874  * Finds the given format/value in the index
 875  *
 876  * Returns: the entry associated with the value or NULL if the
 877  *   value was not found.
 878  */
 879 GstIndexEntry *
 880 gst_index_get_assoc_entry (GstIndex * index, gint id,
 881     GstIndexLookupMethod method, GstAssocFlags flags,
 882     GstFormat format, gint64 value)
 883 {
 884   g_return_val_if_fail (GST_IS_INDEX (index), NULL);
 885
 886   if (id == -1)
 887     return NULL;
 888
 889   return gst_index_get_assoc_entry_full (index, id, method, flags, format,
 890       value, gst_index_compare_func, NULL);
 891 }
 892
 893 /**
 894  * gst_index_get_assoc_entry_full:
 895  * @index: the index to search
 896  * @id: the id of the index writer
 897  * @method: The lookup method to use
 898  * @flags: Flags for the entry
 899  * @format: the format of the value
 900  * @value: the value to find
 901  * @func: the function used to compare entries
 902  * @user_data: user data passed to the compare function
 903  *
 904  * Finds the given format/value in the index with the given
 905  * compare function and user_data.
 906  *
 907  * Returns: the entry associated with the value or NULL if the
 908  *   value was not found.
 909  */
 910 GstIndexEntry *
 911 gst_index_get_assoc_entry_full (GstIndex * index, gint id,
 912     GstIndexLookupMethod method, GstAssocFlags flags,
 913     GstFormat format, gint64 value, GCompareDataFunc func, gpointer user_data)
 914 {
 915   GstIndexClass *iclass;
 916
 917   g_return_val_if_fail (GST_IS_INDEX (index), NULL);
 918
 919   if (id == -1)
 920     return NULL;
 921
 922   iclass = GST_INDEX_GET_CLASS (index);
 923
 924   if (iclass->get_assoc_entry)
 925     return iclass->get_assoc_entry (index, id, method, flags, format, value,
 926         func, user_data);
 927
 928   return NULL;
 929 }
 930
 931 /**
 932  * gst_index_entry_assoc_map:
 933  * @entry: the index to search
 934  * @format: the format of the value the find
 935  * @value: a pointer to store the value
 936  *
 937  * Gets alternative formats associated with the indexentry.
 938  *
 939  * Returns: TRUE if there was a value associated with the given
 940  * format.
 941  */
 942 gboolean
 943 gst_index_entry_assoc_map (GstIndexEntry * entry,
 944     GstFormat format, gint64 * value)
 945 {
 946   gint i;
 947
 948   g_return_val_if_fail (entry != NULL, FALSE);
 949   g_return_val_if_fail (value != NULL, FALSE);
 950
 951   for (i = 0; i < GST_INDEX_NASSOCS (entry); i++) {
 952     if (GST_INDEX_ASSOC_FORMAT (entry, i) == format) {
 953       *value = GST_INDEX_ASSOC_VALUE (entry, i);
 954       return TRUE;
 955     }
 956   }
 957   return FALSE;
 958 }