## GstToc GstToc — Generic table of contents support |

## Synopsis

    #include <gst/gst.h>

                        GstToc;
    enum                GstTocScope;
                        GstTocEntry;
    enum                GstTocEntryType;
    GstToc *            gst_toc_new                         (GstTocScope scope);
    #define             gst_toc_ref                         (toc)
    #define             gst_toc_unref                       (toc)
    #define             gst_toc_copy                        (toc)
    #define             gst_toc_make_writable               (toc)
    GstTocScope         gst_toc_get_scope                   (const GstToc *toc);
    GList *             gst_toc_get_entries                 (const GstToc *toc);
    void                gst_toc_append_entry                (GstToc *toc,
                                                             GstTocEntry *entry);
    GstTagList *        gst_toc_get_tags                    (const GstToc *toc);
    void                gst_toc_merge_tags                  (GstToc *toc,
                                                             GstTagList *tags,
                                                             GstTagMergeMode mode);
    void                gst_toc_set_tags                    (GstToc *toc,
                                                             GstTagList *tags);
    void                gst_toc_dump                        (GstToc *toc);
    GstTocEntry *       gst_toc_entry_new                   (GstTocEntryType type,
                                                             const gchar *uid);
    #define             gst_toc_entry_ref                   (entry)
    #define             gst_toc_entry_unref                 (entry)
    #define             gst_toc_entry_copy                  (entry)
    #define             gst_toc_entry_make_writable         (entry)
    GstTocEntry *       gst_toc_find_entry                  (const GstToc *toc,
                                                             const gchar *uid);
    GstToc *            gst_toc_entry_get_toc               (GstTocEntry *entry);
    const gchar *       gst_toc_entry_get_uid               (const GstTocEntry *entry);
    GstTocEntry *       gst_toc_entry_get_parent            (GstTocEntry *entry);
    GList *             gst_toc_entry_get_sub_entries       (const GstTocEntry *entry);
    void                gst_toc_entry_append_sub_entry      (GstTocEntry *entry,
                                                             GstTocEntry *subentry);
    gboolean            gst_toc_entry_get_start_stop_times  (const GstTocEntry *entry,
                                                             gint64 *start,
                                                             gint64 *stop);
    void                gst_toc_entry_set_start_stop_times  (GstTocEntry *entry,
                                                             gint64 start,
                                                             gint64 stop);
    GstTagList *        gst_toc_entry_get_tags              (const GstTocEntry *entry);
    void                gst_toc_entry_merge_tags            (GstTocEntry *entry,
                                                             GstTagList *tags,
                                                             GstTagMergeMode mode);
    void                gst_toc_entry_set_tags              (GstTocEntry *entry,
                                                             GstTagList *tags);
    const gchar *       gst_toc_entry_type_get_nick         (GstTocEntryType type);
    GstTocEntryType     gst_toc_entry_get_entry_type        (const GstTocEntry *entry);
    gboolean            gst_toc_entry_is_alternative        (const GstTocEntry *entry);
    gboolean            gst_toc_entry_is_sequence           (const GstTocEntry *entry);
    #define             GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE   (entry_type)
    #define             GST_TOC_ENTRY_TYPE_IS_SEQUENCE      (entry_type)

## 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 the GstToc using `gst_toc_append_entry()`, and appending subentries to a GstTocEntry using `gst_toc_entry_append_sub_entry()`.

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.

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.

TOCs can have global scope or current scope. Global scope TOCs contain all entries that can possibly be selected using a toc select event, and are what an application is usually interested in. TOCs with current scope only contain the parts of the TOC relevant to the currently selected/playing stream; the current scope TOC is used by downstream elements such as muxers to write correct TOC entries when transcoding files, for example. When playing a DVD, the global TOC would contain a hierarchy of all titles, chapters and angles, for example, while the current TOC would only contain the chapters for the currently playing title if playback of a specific title was requested.

Applications and plugins should not rely on TOCs having a certain kind of structure, but should allow for different alternatives. For example, a simple CUE sheet embedded in a file may be presented as a flat list of track entries, or could have a top-level edition node (or some other alternative type entry) with track entries underneath that node; or even multiple top-level edition nodes (or some other alternative type entries) each with track entries underneath, in case the source file has extracted a track listing from different sources).

## Details

### GstToc

    typedef struct _GstToc GstToc;

### enum GstTocScope

    typedef enum {
      GST_TOC_SCOPE_GLOBAL = 1,
      GST_TOC_SCOPE_CURRENT = 2
    } GstTocScope;

The scope of a TOC.

`GST_TOC_SCOPE_GLOBAL` | global TOC representing all selectable options (this is what applications are usually interested in)
`GST_TOC_SCOPE_CURRENT` | TOC for the currently active/selected stream (this is a TOC representing the current stream from start to EOS, and is what a TOC writer / muxer is usually interested in; it will usually be a subset of the global TOC, e.g. just the chapters of the current title, or the chapters selected for playback from the current title)

### GstTocEntry

    typedef struct _GstTocEntry GstTocEntry;

### enum GstTocEntryType

    typedef enum {
      GST_TOC_ENTRY_TYPE_ANGLE       = -3,
      GST_TOC_ENTRY_TYPE_VERSION     = -2,
      GST_TOC_ENTRY_TYPE_EDITION     = -1,
      GST_TOC_ENTRY_TYPE_INVALID     = 0,
      GST_TOC_ENTRY_TYPE_TITLE       = 1,
      GST_TOC_ENTRY_TYPE_TRACK       = 2,
      GST_TOC_ENTRY_TYPE_CHAPTER     = 3,
    } GstTocEntryType;

The different types of TOC entries (see GstTocEntry).

There are two types of TOC entries: alternatives or parts in a sequence.

`GST_TOC_ENTRY_TYPE_ANGLE` | entry is an angle (i.e. an alternative)
`GST_TOC_ENTRY_TYPE_VERSION` | entry is a version (i.e. alternative)
`GST_TOC_ENTRY_TYPE_EDITION` | entry is an edition (i.e. alternative)
`GST_TOC_ENTRY_TYPE_INVALID` | invalid entry type value
`GST_TOC_ENTRY_TYPE_TITLE` | entry is a title (i.e. a part of a sequence)
`GST_TOC_ENTRY_TYPE_TRACK` | entry is a track (i.e. a part of a sequence)
`GST_TOC_ENTRY_TYPE_CHAPTER` | entry is a chapter (i.e. a part of a sequence)

### gst_toc_new ()

    GstToc *            gst_toc_new                         (GstTocScope scope);

Create a new GstToc structure.

`scope` : | scope of this TOC
Returns : | newly allocated GstToc structure, free it with `gst_toc_unref()`. [transfer full]

### gst_toc_ref()

    #define gst_toc_ref(toc)            (GstToc*)gst_mini_object_ref(GST_MINI_OBJECT_CAST(toc))

### gst_toc_unref()

    #define gst_toc_unref(toc)          gst_mini_object_unref(GST_MINI_OBJECT_CAST(toc))

### gst_toc_copy()

    #define gst_toc_copy(toc)           (GstToc*)gst_mini_object_copy(GST_MINI_OBJECT_CAST(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_unref()`.

### gst_toc_make_writable()

    #define gst_toc_make_writable(toc)  (GstToc*)gst_mini_object_make_writable(GST_MINI_OBJECT_CAST(toc))

### gst_toc_get_scope ()

    GstTocScope         gst_toc_get_scope                   (const GstToc *toc);

`toc` : | a GstToc instance
Returns : | scope of `toc`

### gst_toc_get_entries ()

    GList *             gst_toc_get_entries                 (const GstToc *toc);

Gets the list of GstTocEntry of `toc`.

`toc` : | A GstToc instance
Returns : | A GList of GstTocEntry for `entry`. [transfer none][element-type Gst.TocEntry]

### gst_toc_append_entry ()

    void                gst_toc_append_entry                (GstToc *toc,
                                                             GstTocEntry *entry);

Appends the GstTocEntry `entry` to `toc`.

`toc` : | A GstToc instance
`entry` : | A GstTocEntry. [transfer full]

### gst_toc_get_tags ()

    GstTagList *        gst_toc_get_tags                    (const GstToc *toc);

Gets the tags for `toc`.

`toc` : | A GstToc instance
Returns : | A GstTagList for `entry`. [transfer none]

### gst_toc_merge_tags ()

    void                gst_toc_merge_tags                  (GstToc *toc,
                                                             GstTagList *tags,
                                                             GstTagMergeMode mode);

Merge `tags` into the existing tags of `toc` using `mode`.

`toc` : | A GstToc instance
`tags` : | A GstTagList or `NULL`. [allow-none]
`mode` : | A GstTagMergeMode

### gst_toc_set_tags ()

    void                gst_toc_set_tags                    (GstToc *toc,
                                                             GstTagList *tags);

Set a GstTagList with tags for the complete `toc`.

`toc` : | A GstToc instance
`tags` : | A GstTagList or `NULL`. [allow-none][transfer full]

### gst_toc_dump ()

    void                gst_toc_dump                        (GstToc *toc);

### 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_unref()`.

### gst_toc_entry_ref()

    #define gst_toc_entry_ref(entry)            (GstTocEntry*)gst_mini_object_ref(GST_MINI_OBJECT_CAST(entry))

### gst_toc_entry_unref()

    #define gst_toc_entry_unref(entry)          gst_mini_object_unref(GST_MINI_OBJECT_CAST(entry))

### gst_toc_entry_copy()

    #define gst_toc_entry_copy(entry)           (GstTocEntry*)gst_mini_object_copy(GST_MINI_OBJECT_CAST(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_unref()`.

### gst_toc_entry_make_writable()

    #define gst_toc_entry_make_writable(entry)  (GstTocEntry*)gst_mini_object_make_writable(GST_MINI_OBJECT_CAST(entry))

### 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. [transfer none]

### gst_toc_entry_get_toc ()

    GstToc *            gst_toc_entry_get_toc               (GstTocEntry *entry);

Gets the parent GstToc of `entry`.

`entry` : | A GstTocEntry instance
Returns : | The parent GstToc of `entry`. [transfer none]

### gst_toc_entry_get_uid ()

    const gchar *       gst_toc_entry_get_uid               (const GstTocEntry *entry);

Gets the UID of `entry`.

`entry` : | A GstTocEntry instance
Returns : | The UID of `entry`. [transfer none]

### gst_toc_entry_get_parent ()

    GstTocEntry *       gst_toc_entry_get_parent            (GstTocEntry *entry);

Gets the parent GstTocEntry of `entry`.

`entry` : | A GstTocEntry instance
Returns : | The parent GstTocEntry of `entry`. [transfer none]

### gst_toc_entry_get_sub_entries ()

    GList *             gst_toc_entry_get_sub_entries       (const GstTocEntry *entry);

Gets the sub-entries of `entry`.

`entry` : | A GstTocEntry instance
Returns : | A GList of GstTocEntry of `entry`. [transfer none][element-type Gst.TocEntry]

### gst_toc_entry_append_sub_entry ()

    void                gst_toc_entry_append_sub_entry      (GstTocEntry *entry,
                                                             GstTocEntry *subentry);

Appends the GstTocEntry `subentry` to `entry`.

`entry` : | A GstTocEntry instance
`subentry` : | A GstTocEntry. [transfer full]

### gst_toc_entry_get_start_stop_times ()

    gboolean            gst_toc_entry_get_start_stop_times  (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.

### gst_toc_entry_set_start_stop_times ()

    void                gst_toc_entry_set_start_stop_times  (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.

### gst_toc_entry_get_tags ()

    GstTagList *        gst_toc_entry_get_tags              (const GstTocEntry *entry);

Gets the tags for `entry`.

`entry` : | A GstTocEntry instance
Returns : | A GstTagList for `entry`. [transfer none]

### gst_toc_entry_merge_tags ()

    void                gst_toc_entry_merge_tags            (GstTocEntry *entry,
                                                             GstTagList *tags,
                                                             GstTagMergeMode mode);

Merge `tags` into the existing tags of `entry` using `mode`.

`entry` : | A GstTocEntry instance
`tags` : | A GstTagList or `NULL`. [allow-none]
`mode` : | A GstTagMergeMode

### gst_toc_entry_set_tags ()

    void                gst_toc_entry_set_tags              (GstTocEntry *entry,
                                                             GstTagList *tags);

Set a GstTagList with tags for the complete `entry`.

`entry` : | A GstTocEntry instance
`tags` : | A GstTagList or `NULL`. [allow-none][transfer full]

### gst_toc_entry_type_get_nick ()

    const gchar *       gst_toc_entry_type_get_nick         (GstTocEntryType type);

Converts `type` to a string representation.

`type` : | a GstTocEntryType.
Returns : | Returns a human-readable string for `type`. This string is only for debugging purpose and should not be displayed in a user interface.

### gst_toc_entry_get_entry_type ()

    GstTocEntryType     gst_toc_entry_get_entry_type        (const GstTocEntry *entry);

`entry` : | a GstTocEntry
Returns : | `entry`'s entry type

### gst_toc_entry_is_alternative ()

    gboolean            gst_toc_entry_is_alternative        (const GstTocEntry *entry);

`entry` : | a GstTocEntry
Returns : | `TRUE` if `entry`'s type is an alternative type, otherwise `FALSE`

### gst_toc_entry_is_sequence ()

    gboolean            gst_toc_entry_is_sequence           (const GstTocEntry *entry);

`entry` : | a GstTocEntry
Returns : | `TRUE` if `entry`'s type is a sequence type, otherwise `FALSE`

### GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE()

    #define GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE(entry_type)  (entry_type < 0)

### GST_TOC_ENTRY_TYPE_IS_SEQUENCE()

    #define GST_TOC_ENTRY_TYPE_IS_SEQUENCE(entry_type)     (entry_type > 0)

## See Also

GstStructure, GstEvent, GstMessage, GstQuery