GstIndex

GstIndex — Generate indexes on objects

Functions

Properties

GstIndexResolver resolver Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── GstObject
        ╰── GstIndex

Includes

#include <gst/gst.h>

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.

Functions

GST_INDEX_NASSOCS()

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

Get the number of associations in the entry.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

entry

The entry to query

 

i

The value index

 

GST_INDEX_FORMAT_FORMAT()

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

Get the format of the format entry

Parameters

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

Parameters

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

Parameters

entry

The entry to query

 

GstIndexFilter ()

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

Function to filter out entries in the index.

Parameters

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.


GstIndexResolver ()

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

Function to resolve ids to writer descriptions.

Parameters

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.


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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Types and Values

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

The certainty of a group in the index.

Members

GST_INDEX_UNKNOWN

accuracy is not known

 

GST_INDEX_CERTAIN

accuracy is perfect

 

GST_INDEX_FUZZY

accuracy is fuzzy

 

enum GstIndexEntryType

The different types of entries in the index.

Members

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

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

Members

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

 

struct GstIndexAssociation

struct GstIndexAssociation {
  GstFormat     format;
  gint64        value;
};

An association in an entry.

Members

GstFormat format;

the format of the association

 

gint64 value;

the value of the association

 

enum GstAssocFlags

Flags for an association entry.

Members

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.

 

enum GstIndexResolverMethod

The method used to resolve index writers

Members

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

 

enum GstIndexFlags

Flags for this index

Members

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

 

Property Details

The “resolver” property

  “resolver”                 GstIndexResolver

Select a predefined object to string mapper.

Flags: Read / Write

Default value: GST_INDEX_RESOLVER_PATH

Signal Details

The “entry-added” signal

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

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

Parameters

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.

 

Flags: Run Last

See Also

GstIndexFactory