GstIndex

## GstIndex GstIndex — Generate indexes on objects |

## Synopsis

    #include <gst/gst.h>

                        GstIndex;
                        GstIndexEntry;
                        GstIndexGroup;
    enum                GstIndexCertainty;
    enum                GstIndexEntryType;
    enum                GstIndexLookupMethod;
    #define             GST_INDEX_NASSOCS                   (entry)
    #define             GST_INDEX_ASSOC_FLAGS               (entry)
    #define             GST_INDEX_ASSOC_FORMAT              (entry,i)
    #define             GST_INDEX_ASSOC_VALUE               (entry,i)
                        GstIndexAssociation;
    enum                GstAssocFlags;
    #define             GST_INDEX_FORMAT_FORMAT             (entry)
    #define             GST_INDEX_FORMAT_KEY                (entry)
    #define             GST_INDEX_ID_INVALID
    #define             GST_INDEX_ID_DESCRIPTION            (entry)
    gboolean            (*GstIndexFilter)                   (GstIndex *index,
                                                             GstIndexEntry *entry,
                                                             gpointer user_data);
    enum                GstIndexResolverMethod;
    gboolean            (*GstIndexResolver)                 (GstIndex *index,
                                                             GstObject *writer,
                                                             gchar **writer_string,
                                                             gpointer user_data);
    enum                GstIndexFlags;
    #define             GST_INDEX_IS_READABLE               (obj)
    #define             GST_INDEX_IS_WRITABLE               (obj)
    GstIndex*           gst_index_new                       (void);
    void                gst_index_commit                    (GstIndex *index,
                                                             gint id);
    gint                gst_index_get_group                 (GstIndex *index);
    gint                gst_index_new_group                 (GstIndex *index);
    gboolean            gst_index_set_group                 (GstIndex *index,
                                                             gint groupnum);
    void                gst_index_set_certainty             (GstIndex *index,
                                                             GstIndexCertainty certainty);
    GstIndexCertainty   gst_index_get_certainty             (GstIndex *index);
    void                gst_index_set_filter                (GstIndex *index,
                                                             GstIndexFilter filter,
                                                             gpointer user_data);
    void                gst_index_set_filter_full           (GstIndex *index,
                                                             GstIndexFilter filter,
                                                             gpointer user_data,
                                                             GDestroyNotify user_data_destroy);
    void                gst_index_set_resolver              (GstIndex *index,
                                                             GstIndexResolver resolver,
                                                             gpointer user_data);
    void                gst_index_set_resolver_full         (GstIndex *index,
                                                             GstIndexResolver resolver,
                                                             gpointer user_data,
                                                             GDestroyNotify user_data_destroy);
    gboolean            gst_index_get_writer_id             (GstIndex *index,
                                                             GstObject *writer,
                                                             gint *id);
    GstIndexEntry*      gst_index_add_format                (GstIndex *index,
                                                             gint id,
                                                             GstFormat format);
    GstIndexEntry*      gst_index_add_association           (GstIndex *index,
                                                             gint id,
                                                             GstAssocFlags flags,
                                                             GstFormat format,
                                                             gint64 value,
                                                             ...);
    GstIndexEntry*      gst_index_add_associationv          (GstIndex *index,
                                                             gint id,
                                                             GstAssocFlags flags,
                                                             gint n,
                                                             const GstIndexAssociation *list);
    GstIndexEntry*      gst_index_add_object                (GstIndex *index,
                                                             gint id,
                                                             gchar *key,
                                                             GType type,
                                                             gpointer object);
    GstIndexEntry*      gst_index_add_id                    (GstIndex *index,
                                                             gint id,
                                                             gchar *description);
    GstIndexEntry*      gst_index_get_assoc_entry           (GstIndex *index,
                                                             gint id,
                                                             GstIndexLookupMethod method,
                                                             GstAssocFlags flags,
                                                             GstFormat format,
                                                             gint64 value);
    GstIndexEntry*      gst_index_get_assoc_entry_full      (GstIndex *index,
                                                             gint id,
                                                             GstIndexLookupMethod method,
                                                             GstAssocFlags flags,
                                                             GstFormat format,
                                                             gint64 value,
                                                             GCompareDataFunc func,
                                                             gpointer user_data);
    GstIndexEntry*      gst_index_entry_copy                (GstIndexEntry *entry);
    void                gst_index_entry_free                (GstIndexEntry *entry);
    gboolean            gst_index_entry_assoc_map           (GstIndexEntry *entry,
                                                             GstFormat format,
                                                             gint64 *value);

## Object Hierarchy

      GObject
       +----GstObject
             +----GstIndex

## Properties

      "resolver"                 GstIndexResolver      : Read / Write

## Signals

      "entry-added"                                    : Run Last

## Description

GstIndex is used to generate a stream index of one or more elements in a pipeline.

## Details

### GstIndex

    typedef struct _GstIndex GstIndex;

Opaque GstIndex structure.

### GstIndexEntry

    typedef struct {
    } GstIndexEntry;

The basic element of an index.

### GstIndexGroup

    typedef struct {
    } GstIndexGroup;

A group of related entries in an index.

### enum GstIndexCertainty

    typedef enum {
      GST_INDEX_UNKNOWN,
      GST_INDEX_CERTAIN,
      GST_INDEX_FUZZY
    } GstIndexCertainty;

The certainty of a group in the index.

`GST_INDEX_UNKNOWN` | accuracy is not known
`GST_INDEX_CERTAIN` | accuracy is perfect
`GST_INDEX_FUZZY` | accuracy is fuzzy

### enum GstIndexEntryType

    typedef enum {
      GST_INDEX_ENTRY_ID,
      GST_INDEX_ENTRY_ASSOCIATION,
      GST_INDEX_ENTRY_OBJECT,
      GST_INDEX_ENTRY_FORMAT
    } GstIndexEntryType;

The different types of entries in the index.

`GST_INDEX_ENTRY_ID` | This entry is an id that maps an index id to its owner object
`GST_INDEX_ENTRY_ASSOCIATION` | This entry is an association between formats
`GST_INDEX_ENTRY_OBJECT` | An object
`GST_INDEX_ENTRY_FORMAT` | A format definition

### enum GstIndexLookupMethod

    typedef enum {
      GST_INDEX_LOOKUP_EXACT,
      GST_INDEX_LOOKUP_BEFORE,
      GST_INDEX_LOOKUP_AFTER
    } GstIndexLookupMethod;

Specify the method to find an index entry in the index.

`GST_INDEX_LOOKUP_EXACT` | There has to be an exact indexentry with the given format/value
`GST_INDEX_LOOKUP_BEFORE` | The exact entry or the one before it
`GST_INDEX_LOOKUP_AFTER` | The exact entry or the one after it

### GST_INDEX_NASSOCS()

    #define GST_INDEX_NASSOCS(entry)		((entry)->data.assoc.nassocs)

Get the number of associations in the entry.

`entry` : | The entry to query

### GST_INDEX_ASSOC_FLAGS()

    #define GST_INDEX_ASSOC_FLAGS(entry)		((entry)->data.assoc.flags)

Get the flags for this entry.

`entry` : | The entry to query

### GST_INDEX_ASSOC_FORMAT()

    #define GST_INDEX_ASSOC_FORMAT(entry,i)		((entry)->data.assoc.assocs[(i)].format)

Get the i-th format of the entry.

`entry` : | The entry to query
`i` : | The format index

### GST_INDEX_ASSOC_VALUE()

    #define GST_INDEX_ASSOC_VALUE(entry,i)		((entry)->data.assoc.assocs[(i)].value)

Get the i-th value of the entry.

`entry` : | The entry to query
`i` : | The value index

### GstIndexAssociation

    typedef struct {
      GstFormat 	format;
      gint64 	value;
    } GstIndexAssociation;

An association in an entry.

GstFormat `format`; | the format of the association
gint64 `value`; | the value of the association

### enum GstAssocFlags

    typedef enum {
      GST_ASSOCIATION_FLAG_NONE 	  = 0,
      GST_ASSOCIATION_FLAG_KEY_UNIT   = (1 << 0),
      GST_ASSOCIATION_FLAG_DELTA_UNIT = (1 << 1),

      /* new flags should start here */
      GST_ASSOCIATION_FLAG_LAST	= (1 << 8)
    } GstAssocFlags;

Flags for an association entry.

`GST_ASSOCIATION_FLAG_NONE` | no extra flags
`GST_ASSOCIATION_FLAG_KEY_UNIT` | the entry marks a key unit, a key unit is one that marks a place where one can randomly seek to.
`GST_ASSOCIATION_FLAG_DELTA_UNIT` | the entry marks a delta unit, a delta unit is one that marks a place where one can relatively seek to.
`GST_ASSOCIATION_FLAG_LAST` | extra user defined flags should start here.

### GST_INDEX_FORMAT_FORMAT()

    #define GST_INDEX_FORMAT_FORMAT(entry)		((entry)->data.format.format)

Get the format of the format entry

`entry` : | The entry to query

### GST_INDEX_FORMAT_KEY()

    #define GST_INDEX_FORMAT_KEY(entry)		((entry)->data.format.key)

Get the key of the format entry

`entry` : | The entry to query

### GST_INDEX_ID_INVALID

    #define GST_INDEX_ID_INVALID			(-1)

Constant for an invalid index id

### GST_INDEX_ID_DESCRIPTION()

    #define GST_INDEX_ID_DESCRIPTION(entry)		((entry)->data.id.description)

Get the description of the id entry

`entry` : | The entry to query

### GstIndexFilter ()

    gboolean            (*GstIndexFilter)                   (GstIndex *index,
                                                             GstIndexEntry *entry,
                                                             gpointer user_data);

Function to filter out entries in the index.

`index` : | The index being queried
`entry` : | The entry to be added.
`user_data` : | User data passed to the function.
Returns : | This function should return `TRUE` if the entry is to be added to the index, `FALSE` otherwise.

### enum GstIndexResolverMethod

    typedef enum {
      GST_INDEX_RESOLVER_CUSTOM,
      GST_INDEX_RESOLVER_GTYPE,
      GST_INDEX_RESOLVER_PATH
    } GstIndexResolverMethod;

The method used to resolve index writers

`GST_INDEX_RESOLVER_CUSTOM` | Use a custom resolver
`GST_INDEX_RESOLVER_GTYPE` | Resolve based on the GType of the object
`GST_INDEX_RESOLVER_PATH` | Resolve on the path in graph

### GstIndexResolver ()

    gboolean            (*GstIndexResolver)                 (GstIndex *index,
                                                             GstObject *writer,
                                                             gchar **writer_string,
                                                             gpointer user_data);

Function to resolve ids to writer descriptions.

`index` : | the index being queried.
`writer` : | The object that wants to write
`writer_string` : | A description of the writer.
`user_data` : | user_data as registered
Returns : | `TRUE` if an id could be assigned to the writer.

### enum GstIndexFlags

    typedef enum {
      GST_INDEX_WRITABLE    = (GST_OBJECT_FLAG_LAST << 0),
      GST_INDEX_READABLE    = (GST_OBJECT_FLAG_LAST << 1),

      GST_INDEX_FLAG_LAST   = (GST_OBJECT_FLAG_LAST << 8)
    } GstIndexFlags;

Flags for this index

`GST_INDEX_WRITABLE` | The index is writable
`GST_INDEX_READABLE` | The index is readable
`GST_INDEX_FLAG_LAST` | First flag that can be used by subclasses

### GST_INDEX_IS_READABLE()

    #define GST_INDEX_IS_READABLE(obj)    (GST_OBJECT_FLAG_IS_SET (obj, GST_INDEX_READABLE))

Check if the index can be read from

`obj` : | The index to check

### GST_INDEX_IS_WRITABLE()

    #define GST_INDEX_IS_WRITABLE(obj)    (GST_OBJECT_FLAG_IS_SET (obj, GST_INDEX_WRITABLE))

Check if the index can be written to

`obj` : | The index to check

### gst_index_new ()

    GstIndex*           gst_index_new                       (void);

Create a new tileindex object

Returns : | a new index object

### gst_index_commit ()

    void                gst_index_commit                    (GstIndex *index,
                                                             gint id);

Tell the index that the writer with the given id is done with this index and is not going to write any more entries to it.

`index` : | the index to commit
`id` : | the writer that commited the index

### gst_index_get_group ()

    gint                gst_index_get_group                 (GstIndex *index);

Get the id of the current group.

`index` : | the index to get the current group from
Returns : | the id of the current group.

### gst_index_new_group ()

    gint                gst_index_new_group                 (GstIndex *index);

Create a new group for the given index. It will be set as the current group.

`index` : | the index to create the new group in
Returns : | the id of the newly created group.

### gst_index_set_group ()

    gboolean            gst_index_set_group                 (GstIndex *index,
                                                             gint groupnum);

Set the current groupnumber to the given argument.

`index` : | the index to set the new group in
`groupnum` : | the groupnumber to set
Returns : | TRUE if the operation succeeded, FALSE if the group did not exist.

### gst_index_set_certainty ()

    void                gst_index_set_certainty             (GstIndex *index,
                                                             GstIndexCertainty certainty);

Set the certainty of the given index.

`index` : | the index to set the certainty on
`certainty` : | the certainty to set

### gst_index_get_certainty ()

    GstIndexCertainty   gst_index_get_certainty             (GstIndex *index);

Get the certainty of the given index.

`index` : | the index to get the certainty of
Returns : | the certainty of the index.

### gst_index_set_filter ()

    void                gst_index_set_filter                (GstIndex *index,
                                                             GstIndexFilter filter,
                                                             gpointer user_data);

Lets the app register a custom filter function so that it can select what entries should be stored in the index.

`index` : | the index to register the filter on
`filter` : | the filter to register
`user_data` : | data passed to the filter function

### gst_index_set_filter_full ()

    void                gst_index_set_filter_full           (GstIndex *index,
                                                             GstIndexFilter filter,
                                                             gpointer user_data,
                                                             GDestroyNotify user_data_destroy);

Lets the app register a custom filter function so that it can select what entries should be stored in the index.

`index` : | the index to register the filter on
`filter` : | the filter to register
`user_data` : | data passed to the filter function
`user_data_destroy` : | function to call when `user_data` is unset

### gst_index_set_resolver ()

    void                gst_index_set_resolver              (GstIndex *index,
                                                             GstIndexResolver resolver,
                                                             gpointer user_data);

Lets the app register a custom function to map index ids to writer descriptions.

`index` : | the index to register the resolver on
`resolver` : | the resolver to register
`user_data` : | data passed to the resolver function

### gst_index_set_resolver_full ()

    void                gst_index_set_resolver_full         (GstIndex *index,
                                                             GstIndexResolver resolver,
                                                             gpointer user_data,
                                                             GDestroyNotify user_data_destroy);

Lets the app register a custom function to map index ids to writer descriptions.

`index` : | the index to register the resolver on
`resolver` : | the resolver to register
`user_data` : | data passed to the resolver function
`user_data_destroy` : | destroy function for `user_data`

Since 0.10.18

### gst_index_get_writer_id ()

    gboolean            gst_index_get_writer_id             (GstIndex *index,
                                                             GstObject *writer,
                                                             gint *id);

Before entries can be added to the index, a writer should obtain a unique id. The methods to add new entries to the index require this id as an argument.

The application can implement a custom function to map the writer object to a string. That string will be used to register or look up an id in the index.

`index` : | the index to get a unique write id for
`writer` : | the GstObject to allocate an id for
`id` : | a pointer to a gint to hold the id
Returns : | TRUE if the writer would be mapped to an id.

### gst_index_add_format ()

    GstIndexEntry*      gst_index_add_format                (GstIndex *index,
                                                             gint id,
                                                             GstFormat format);

Adds a format entry into the index. This function is used to map dynamic GstFormat ids to their original format key.

`index` : | the index to add the entry to
`id` : | the id of the index writer
`format` : | the format to add to the index
Returns : | a pointer to the newly added entry in the index.

### gst_index_add_association ()

    GstIndexEntry*      gst_index_add_association           (GstIndex *index,
                                                             gint id,
                                                             GstAssocFlags flags,
                                                             GstFormat format,
                                                             gint64 value,
                                                             ...);

Associate given format/value pairs with each other. Be sure to pass gint64 values to this functions varargs, you might want to use a gint64 cast to be sure.

`index` : | the index to add the entry to
`id` : | the id of the index writer
`flags` : | optinal flags for this entry
`format` : | the format of the value
`value` : | the value
`...` : | other format/value pairs or 0 to end the list
Returns : | a pointer to the newly added entry in the index.

### gst_index_add_associationv ()

    GstIndexEntry*      gst_index_add_associationv          (GstIndex *index,
                                                             gint id,
                                                             GstAssocFlags flags,
                                                             gint n,
                                                             const GstIndexAssociation *list);

Associate given format/value pairs with each other.

`index` : | the index to add the entry to
`id` : | the id of the index writer
`flags` : | optinal flags for this entry
`n` : | number of associations
`list` : | list of associations
Returns : | a pointer to the newly added entry in the index.

### gst_index_add_object ()

    GstIndexEntry*      gst_index_add_object                (GstIndex *index,
                                                             gint id,
                                                             gchar *key,
                                                             GType type,
                                                             gpointer object);

Add the given object to the index with the given key.

This function is not yet implemented.

`index` : | the index to add the object to
`id` : | the id of the index writer
`key` : | a key for the object
`type` : | the GType of the object
`object` : | a pointer to the object to add
Returns : | a pointer to the newly added entry in the index.

### gst_index_add_id ()

    GstIndexEntry*      gst_index_add_id                    (GstIndex *index,
                                                             gint id,
                                                             gchar *description);

Add an id entry into the index.

`index` : | the index to add the entry to
`id` : | the id of the index writer
`description` : | the description of the index writer
Returns : | a pointer to the newly added entry in the index.

### gst_index_get_assoc_entry ()

    GstIndexEntry*      gst_index_get_assoc_entry           (GstIndex *index,
                                                             gint id,
                                                             GstIndexLookupMethod method,
                                                             GstAssocFlags flags,
                                                             GstFormat format,
                                                             gint64 value);

Finds the given format/value in the index

`index` : | the index to search
`id` : | the id of the index writer
`method` : | The lookup method to use
`flags` : | Flags for the entry
`format` : | the format of the value
`value` : | the value to find
Returns : | the entry associated with the value or NULL if the value was not found.

### gst_index_get_assoc_entry_full ()

    GstIndexEntry*      gst_index_get_assoc_entry_full      (GstIndex *index,
                                                             gint id,
                                                             GstIndexLookupMethod method,
                                                             GstAssocFlags flags,
                                                             GstFormat format,
                                                             gint64 value,
                                                             GCompareDataFunc func,
                                                             gpointer user_data);

Finds the given format/value in the index with the given compare function and user_data.

`index` : | the index to search
`id` : | the id of the index writer
`method` : | The lookup method to use
`flags` : | Flags for the entry
`format` : | the format of the value
`value` : | the value to find
`func` : | the function used to compare entries
`user_data` : | user data passed to the compare function
Returns : | the entry associated with the value or NULL if the value was not found.

### gst_index_entry_copy ()

    GstIndexEntry*      gst_index_entry_copy                (GstIndexEntry *entry);

Copies an entry and returns the result.

`entry` : | the entry to copy
Returns : | a newly allocated GstIndexEntry.

### gst_index_entry_free ()

    void                gst_index_entry_free                (GstIndexEntry *entry);

Free the memory used by the given entry.

`entry` : | the entry to free

### gst_index_entry_assoc_map ()

    gboolean            gst_index_entry_assoc_map           (GstIndexEntry *entry,
                                                             GstFormat format,
                                                             gint64 *value);

Gets alternative formats associated with the indexentry.

`entry` : | the index to search
`format` : | the format of the value the find
`value` : | a pointer to store the value
Returns : | TRUE if there was a value associated with the given format.

## Property Details

### The `"resolver"` property

      "resolver"                 GstIndexResolver      : Read / Write

Select a predefined object to string mapper.

Default value: GST_INDEX_RESOLVER_PATH

## Signal Details

### The `"entry-added"` signal

    void                user_function                      (GstIndex      *gstindex,
                                                            GstIndexEntry *arg1,
                                                            gpointer       user_data)      : Run Last

Is emitted when a new entry is added to the index.

`gstindex` : | the object which received the signal.
`arg1` : | The entry added to the index.
`user_data` : | user data set when the signal handler was connected.

## See Also

GstIndexFactory