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