GstIndex

## GstIndex GstIndex — Generate indexes on objects |

## Synopsis

    #include <gst/gst.h>

    struct              GstIndex;
    struct              GstIndexEntry;
    struct              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)
    struct              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.

Elements will overload the set_index and get_index virtual methods in GstElement. When streaming data, the element will add index entries if it has an index set.

Each element that adds to the index will do that using a writer_id. The writer_id is obtained from `gst_index_get_writer_id()`.

The application that wants to index the stream will create a new index object using `gst_index_new()` or `gst_index_factory_make()`. The index is assigned to a specific element, a bin or the whole pipeline. This will cause indexable elements to add entires to the index while playing.

## Details

### struct GstIndex

    struct GstIndex;

Opaque GstIndex structure.

### struct GstIndexEntry

    struct GstIndexEntry {
    };

The basic element of an index.

### struct GstIndexGroup

    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

### struct GstIndexAssociation

    struct GstIndexAssociation {
      GstFormat     format;
      gint64        value;
    };

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 dummy index object. Use `gst_element_set_index()` to assign that to an element or pipeline. This index is not storing anything, but will still emit e.g. the "entry-added" signal.

Returns : | a new index object. [transfer full]

### 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.

### Note

The caller must not hold `writer`'s GST_OBJECT_LOCK, as the default resolver may call functions that take the object lock as well, and the lock is not recursive.

`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.

Free-function: gst_index_entry_free

`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. [transfer full]

### 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.

Free-function: gst_index_entry_free

`entry` : | the entry to copy
Returns : | a newly allocated GstIndexEntry. [transfer full]

### gst_index_entry_free ()

    void                gst_index_entry_free                (GstIndexEntry *entry);

Free the memory used by the given entry.

`entry` : | the entry to free. [transfer full]

### 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