GstTocSetter

## GstTocSetter GstTocSetter — Element interface that allows setting and retrieval of the TOC |

## Synopsis

    #include <gst/gst.h>

                        GstTocSetter;
    struct              GstTocSetterIFace;
    const GstToc *      gst_toc_setter_get_toc              (GstTocSetter *setter);
    GstToc *            gst_toc_setter_get_toc_copy         (GstTocSetter *setter);
    void                gst_toc_setter_reset_toc            (GstTocSetter *setter);
    void                gst_toc_setter_set_toc              (GstTocSetter *setter,
                                                             const GstToc *toc);
    const GstTocEntry * gst_toc_setter_get_toc_entry        (GstTocSetter *setter,
                                                             const gchar *uid);
    GstTocEntry *       gst_toc_setter_get_toc_entry_copy   (GstTocSetter *setter,
                                                             const gchar *uid);
    gboolean            gst_toc_setter_add_toc_entry        (GstTocSetter *setter,
                                                             const gchar *parent_uid,
                                                             const GstTocEntry *entry);

## Description

Element interface that allows setting of the TOC.

Elements that support some kind of chapters or editions (or tracks like in the FLAC cue sheet) will implement this interface.

If you just want to retrieve the TOC in your application then all you need to do is watch for TOC messages on your pipeline's bus (or you can perform TOC query). This interface is only for setting TOC data, not for extracting it. To set TOC from the application, find proper tocsetter element and set TOC using `gst_toc_setter_set_toc()`.

Elements implementing the GstTocSetter interface can extend existing TOC by getting extend UID for that (you can use `gst_toc_find_entry()` to retrieve it) with any TOC entries received from downstream.

## Details

### GstTocSetter

    typedef struct _GstTocSetter GstTocSetter;

Opaque GstTocSetter data structure.

### struct GstTocSetterIFace

    struct GstTocSetterIFace {
      GTypeInterface g_iface;

      /* signals */

      /* virtual table */
    };

GstTocSetterIFace interface.

GTypeInterface `g_iface`; | parent interface type.

### gst_toc_setter_get_toc ()

    const GstToc *      gst_toc_setter_get_toc              (GstTocSetter *setter);

Return current TOC the setter uses. The TOC should not be modified or freed.

This function is not thread-safe. Use `gst_toc_setter_get_toc_copy()` instead.

`setter` : | a GstTocSetter.
Returns : | a current snapshot of the TOC used in the setter or NULL if none is used.

Since 0.10.37

### gst_toc_setter_get_toc_copy ()

    GstToc *            gst_toc_setter_get_toc_copy         (GstTocSetter *setter);

Return current TOC the setter uses. The difference between this function and `gst_toc_setter_get_toc()` is that this function returns deep copy of the TOC, so you can modify it in any way. This function is thread-safe. Free it when done with `gst_toc_free()`.

`setter` : | a GstTocSetter.
Returns : | a copy of the current snapshot of the TOC used in the setter or NULL if none is used.

Since 0.10.37

### gst_toc_setter_reset_toc ()

    void                gst_toc_setter_reset_toc            (GstTocSetter *setter);

Reset the internal TOC. Elements should call this from within the state-change handler.

`setter` : | a GstTocSetter.

Since 0.10.37

### gst_toc_setter_set_toc ()

    void                gst_toc_setter_set_toc              (GstTocSetter *setter,
                                                             const GstToc *toc);

Set the given TOC on the setter. Previously setted TOC will be freed before setting a new one.

`setter` : | a GstTocSetter.
`toc` : | a GstToc to set.

Since 0.10.37

### gst_toc_setter_get_toc_entry ()

    const GstTocEntry * gst_toc_setter_get_toc_entry        (GstTocSetter *setter,
                                                             const gchar *uid);

Return GstTocEntry (if any) with given `uid`. Returned entry should not be modified or freed.

This function is not thread-safe. Use `gst_toc_setter_get_toc_entry_copy()` instead.

`setter` : | a GstTocSetter.
`uid` : | UID to find entry with.
Returns : | a TOC entry with given `uid` from the TOC in the setter or NULL if none entry with such `uid` was found.

Since 0.10.37

### gst_toc_setter_get_toc_entry_copy ()

    GstTocEntry *       gst_toc_setter_get_toc_entry_copy   (GstTocSetter *setter,
                                                             const gchar *uid);

Return GstTocEntry (if any) with given `uid`. It perform a deep copying, so you can modify returned value. Free it when done with `gst_toc_entry_free()`. This function is thread-safe.

`setter` : | a GstTocSetter.
`uid` : | UID to find entry with.
Returns : | a TOC entry with given `uid` from the TOC in the setter or NULL if none entry with such `uid` was found.

Since 0.10.37

### gst_toc_setter_add_toc_entry ()

    gboolean            gst_toc_setter_add_toc_entry        (GstTocSetter *setter,
                                                             const gchar *parent_uid,
                                                             const GstTocEntry *entry);

Try to find entry with given `parent_uid` and append an `entry` to that GstTocEntry.

`setter` : | a GstTocSetter.
`parent_uid` : | UID of the parent entry to append given `entry`. Use 0 for the TOC root level.
`entry` : | GstTocEntry to append.
Returns : | TRUE if entry with `parent_uid` was found, FALSE otherwise.

Since 0.10.37