GstToc

GstToc — Generic table of contents support

Synopsis

#include <gst/gst.h>

struct              GstToc;
struct              GstTocEntry;
enum                GstTocEntryType;
GstTocEntry *       gst_toc_entry_new                   (GstTocEntryType type,
                                                         const gchar *uid);
GstTocEntry *       gst_toc_entry_new_with_pad          (GstTocEntryType type,
                                                         const gchar *uid,
                                                         gpointer pad);
void                gst_toc_entry_free                  (GstTocEntry *entry);
GstToc *            gst_toc_new                         (void);
void                gst_toc_free                        (GstToc *toc);
GstTocEntry *       gst_toc_entry_copy                  (const GstTocEntry *entry);
GstToc *            gst_toc_copy                        (const GstToc *toc);
GstTocEntry *       gst_toc_find_entry                  (const GstToc *toc,
                                                         const gchar *uid);
gboolean            gst_toc_entry_get_start_stop        (const GstTocEntry *entry,
                                                         gint64 *start,
                                                         gint64 *stop);
void                gst_toc_entry_set_start_stop        (GstTocEntry *entry,
                                                         gint64 start,
                                                         gint64 stop);

Description

GstToc functions are used to create/free GstToc and GstTocEntry structures. Also they are used to convert GstToc into GstStructure and vice versa.

GstToc lets you to inform other elements in pipeline or application that playing source has some kind of table of contents (TOC). These may be chapters, editions, angles or other types. For example: DVD chapters, Matroska chapters or cue sheet TOC. Such TOC will be useful for applications to display instead of just a playlist.

Using TOC is very easy. Firstly, create GstToc structure which represents root contents of the source. You can also attach TOC-specific tags to it. Then fill it with GstTocEntry entries by appending them to GstToc.entries GstTocEntry.subentries lists. You should use GST_TOC_ENTRY_TYPE_CHAPTER for generic TOC entry and GST_TOC_ENTRY_TYPE_EDITION for the entries which are considered to be alternatives (like DVD angles, Matroska editions and so on).

Note that root level of the TOC can contain only either editions or chapters. You should not mix them together at the same level. Otherwise you will get serialization /deserialization errors. Make sure that no one of the entries has negative start and stop values.

Please, use GstToc.info and GstTocEntry.info fields in that way: create a GstStructure, put all info related to your element there and put this structure into the info field under the name of your element. Some fields in the info structure can be used for internal purposes, so you should use it in the way described above to not to overwrite already existent fields.

Use gst_event_new_toc() to create a new TOC GstEvent, and gst_event_parse_toc() to parse received TOC event. Use gst_event_new_toc_select() to create a new TOC select GstEvent, and gst_event_parse_toc_select() to parse received TOC select event. The same rule for the GstMessage: gst_message_new_toc() to create new TOC GstMessage, and gst_message_parse_toc() to parse received TOC message. Also you can create a new TOC query with gst_query_new_toc(), set it with gst_query_set_toc() and parse it with gst_query_parse_toc().

Details

struct GstToc

struct GstToc {
  GList *entries;
  GstTagList *tags;
  GstStructure *info;
};

Definition of TOC structure.

GList *entries;

 list of GstTocEntry entries of the TOC.

GstTagList *tags;

 tags related to the whole TOC.

GstStructure *info;

 extra information related to the TOC.

struct GstTocEntry

struct GstTocEntry {
  gchar *uid;
  GstTocEntryType type;
  GList *subentries;
  GList *pads;
  GstTagList *tags;
  GstStructure *info;
};

Definition of TOC entry structure.

gchar *uid;

 unique (for a whole TOC) id of the entry. This value should be persistent and should not be changed while updating TOC. uid should be handled as "opaque" value without meaning (e.g. applications should not assume the /editionX/chapterY/chapter/Z structure, other demuxers could do something else), it should help to track updates of certain entries.

GstTocEntryType type;

 GstTocEntryType of this entry.

GList *subentries;

 list of GstTocEntry children.

GList *pads;

 list of GstPad objects, related to this GstTocEntry.

GstTagList *tags;

 tags related to this entry.

GstStructure *info;

 extra information related to this entry.

enum GstTocEntryType

typedef enum {
  GST_TOC_ENTRY_TYPE_CHAPTER     = 0,
  GST_TOC_ENTRY_TYPE_EDITION     = 1
} GstTocEntryType;

The different types of TOC entry.

GST_TOC_ENTRY_TYPE_CHAPTER

 a chapter type entry.

GST_TOC_ENTRY_TYPE_EDITION

 an edition entry (angle or alternative in other terms).

gst_toc_entry_new ()

GstTocEntry *       gst_toc_entry_new                   (GstTocEntryType type,
                                                         const gchar *uid);

Create new GstTocEntry structure.

type :

 entry type.

uid :

 unique ID (UID) in the whole TOC.

Returns :

 newly allocated GstTocEntry structure, free it with gst_toc_entry_free().

Since 0.10.37

gst_toc_entry_new_with_pad ()

GstTocEntry *       gst_toc_entry_new_with_pad          (GstTocEntryType type,
                                                         const gchar *uid,
                                                         gpointer pad);

Create new GstTocEntry structure with GstPad related.

type :

 entry type.

uid :

 unique ID (UID) in the whole TOC.

pad :

 GstPad related to this entry.

Returns :

 newly allocated GstTocEntry structure, free it with gst_toc_entry_free() when done.

Since 0.10.37

gst_toc_entry_free ()

void                gst_toc_entry_free                  (GstTocEntry *entry);

Free unused GstTocEntry structure. Note that GstTocEntry.uid will be freed with g_free() and all GstPad objects in the GstTocEntry.pads list will be unrefed with gst_object_unref().

entry :

 GstTocEntry structure to free.

Since 0.10.37

gst_toc_new ()

GstToc *            gst_toc_new                         (void);

Create new GstToc structure.

Returns :

 newly allocated GstToc structure, free it with gst_toc_free().

Since 0.10.37

gst_toc_free ()

void                gst_toc_free                        (GstToc *toc);

Free unused GstToc structure.

toc :

 GstToc structure to free.

Since 0.10.37

gst_toc_entry_copy ()

GstTocEntry *       gst_toc_entry_copy                  (const GstTocEntry *entry);

Copy GstTocEntry with all subentries (deep copy).

entry :

 GstTocEntry to copy.

Returns :

 newly allocated GstTocEntry in case of success, NULL otherwise; free it when done with gst_toc_entry_free().

Since 0.10.37

gst_toc_copy ()

GstToc *            gst_toc_copy                        (const GstToc *toc);

Copy GstToc with all subentries (deep copy).

toc :

 GstToc to copy.

Returns :

 newly allocated GstToc in case of success, NULL otherwise; free it when done with gst_toc_free().

Since 0.10.37

gst_toc_find_entry ()

GstTocEntry *       gst_toc_find_entry                  (const GstToc *toc,
                                                         const gchar *uid);

Find GstTocEntry with given uid in the toc.

toc :

 GstToc to search in.

uid :

 UID to find GstTocEntry with.

Returns :

 GstTocEntry with specified uid from the toc, or NULL if not found.

Since 0.10.37

gst_toc_entry_get_start_stop ()

gboolean            gst_toc_entry_get_start_stop        (const GstTocEntry *entry,
                                                         gint64 *start,
                                                         gint64 *stop);

Get start and stop values from the entry and write them into appropriate storages.

entry :

 GstTocEntry to get values from.

start :

 the storage for the start value, leave NULL if not need. [out]

stop :

 the storage for the stop value, leave NULL if not need. [out]

Returns :

 TRUE if all non-NULL storage pointers were filled with appropriate values, FALSE otherwise.

Since 0.10.37

gst_toc_entry_set_start_stop ()

void                gst_toc_entry_set_start_stop        (GstTocEntry *entry,
                                                         gint64 start,
                                                         gint64 stop);

Set start and stop values for the entry.

entry :

 GstTocEntry to set values.

start :

 start value to set.

stop :

 stop value to set.

Since 0.10.37

See Also

GstStructure, GstEvent, GstMessage, GstQuery, GstPad
Generated by GTK-Doc V1.18