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
Generated by GTK-Doc V1.17