GstToc

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