gst/gsttoc.h

   1 /* GStreamer
   2  * (c) 2010, 2012 Alexander Saprykin <xelfium@gmail.com>
   3  *
   4  * gsttoc.h: generic TOC API declaration
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22 #ifndef __GST_TOC_H__
  23 #define __GST_TOC_H__
  24
  25 #include <gst/gstconfig.h>
  26 #include <gst/gstminiobject.h>
  27 #include <gst/gststructure.h>
  28 #include <gst/gsttaglist.h>
  29 #include <gst/gstformat.h>
  30
  31 G_BEGIN_DECLS
  32
  33 GST_API GType _gst_toc_type;
  34
  35 GST_API GType _gst_toc_entry_type;
  36
  37 #define GST_TYPE_TOC (_gst_toc_type)
  38 #define GST_TYPE_TOC_ENTRY (_gst_toc_entry_type)
  39
  40 typedef struct _GstTocEntry GstTocEntry;
  41 typedef struct _GstToc GstToc;
  42
  43 /**
  44  * GstTocScope:
  45  * @GST_TOC_SCOPE_GLOBAL: global TOC representing all selectable options
  46  *     (this is what applications are usually interested in)
  47  * @GST_TOC_SCOPE_CURRENT: TOC for the currently active/selected stream
  48  *     (this is a TOC representing the current stream from start to EOS,
  49  *     and is what a TOC writer / muxer is usually interested in; it will
  50  *     usually be a subset of the global TOC, e.g. just the chapters of
  51  *     the current title, or the chapters selected for playback from the
  52  *     current title)
  53  *
  54  * The scope of a TOC.
  55  */
  56 typedef enum {
  57   GST_TOC_SCOPE_GLOBAL = 1,
  58   GST_TOC_SCOPE_CURRENT = 2
  59 } GstTocScope;
  60
  61 /**
  62  * GstTocEntryType:
  63  * @GST_TOC_ENTRY_TYPE_ANGLE: entry is an angle (i.e. an alternative)
  64  * @GST_TOC_ENTRY_TYPE_VERSION: entry is a version (i.e. alternative)
  65  * @GST_TOC_ENTRY_TYPE_EDITION: entry is an edition (i.e. alternative)
  66  * @GST_TOC_ENTRY_TYPE_INVALID: invalid entry type value
  67  * @GST_TOC_ENTRY_TYPE_TITLE: entry is a title (i.e. a part of a sequence)
  68  * @GST_TOC_ENTRY_TYPE_TRACK: entry is a track (i.e. a part of a sequence)
  69  * @GST_TOC_ENTRY_TYPE_CHAPTER: entry is a chapter (i.e. a part of a sequence)
  70  *
  71  * The different types of TOC entries (see #GstTocEntry).
  72  *
  73  * There are two types of TOC entries: alternatives or parts in a sequence.
  74  */
  75 typedef enum {
  76   GST_TOC_ENTRY_TYPE_ANGLE       = -3,
  77   GST_TOC_ENTRY_TYPE_VERSION     = -2,
  78   GST_TOC_ENTRY_TYPE_EDITION     = -1,
  79   GST_TOC_ENTRY_TYPE_INVALID     = 0,
  80   GST_TOC_ENTRY_TYPE_TITLE       = 1,
  81   GST_TOC_ENTRY_TYPE_TRACK       = 2,
  82   GST_TOC_ENTRY_TYPE_CHAPTER     = 3,
  83 } GstTocEntryType;
  84
  85 /**
  86  * GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE:
  87  * @entry_type: The #GstTocEntryType from a #GstTocEntry
  88  *
  89  * Checks if @entry_type indicates that its #GstTocEntry is an alternative.
  90  */
  91 #define GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE(entry_type)  (entry_type < 0)
  92
  93 /**
  94  * GST_TOC_ENTRY_TYPE_IS_SEQUENCE:
  95  * @entry_type: The #GstTocEntryType from a #GstTocEntry
  96  *
  97  * Checks if @entry_type indicates that its #GstTocEntry is a sequence.
  98  */
  99 #define GST_TOC_ENTRY_TYPE_IS_SEQUENCE(entry_type)     (entry_type > 0)
 100
 101 /**
 102  * GstTocLoopType:
 103  * @GST_TOC_LOOP_NONE: single forward playback
 104  * @GST_TOC_LOOP_FORWARD: repeat forward
 105  * @GST_TOC_LOOP_REVERSE: repeat backward
 106  * @GST_TOC_LOOP_PING_PONG: repeat forward and backward
 107  *
 108  * How a #GstTocEntry should be repeated. By default, entries are played a
 109  * single time.
 110  *
 111  * Since: 1.4
 112  */
 113 typedef enum {
 114   GST_TOC_LOOP_NONE = 0,
 115   GST_TOC_LOOP_FORWARD,
 116   GST_TOC_LOOP_REVERSE,
 117   GST_TOC_LOOP_PING_PONG
 118 } GstTocLoopType;
 119
 120 /**
 121  * GST_TOC_REPEAT_COUNT_INFINITE:
 122  *
 123  * Special value for the repeat_count set in gst_toc_entry_set_loop() or
 124  * returned by gst_toc_entry_set_loop() to indicate infinite looping.
 125  *
 126  * Since: 1.4
 127  */
 128 #define GST_TOC_REPEAT_COUNT_INFINITE (-1)
 129
 130 /* functions to return type structures */
 131
 132 GST_API
 133 GType           gst_toc_get_type                (void);
 134
 135 GST_API
 136 GType           gst_toc_entry_get_type          (void);
 137
 138 /* functions to create, ref and unref/free TOCs */
 139
 140 GST_API
 141 GstToc *           gst_toc_new                     (GstTocScope scope);
 142
 143 GST_API
 144 GstTocScope        gst_toc_get_scope               (const GstToc *toc);
 145
 146 GST_API
 147 void               gst_toc_set_tags                (GstToc *toc, GstTagList * tags);
 148
 149 GST_API
 150 void               gst_toc_merge_tags              (GstToc *toc, GstTagList *tags, GstTagMergeMode mode);
 151
 152 GST_API
 153 GstTagList *       gst_toc_get_tags                (const GstToc *toc);
 154
 155 GST_API
 156 void               gst_toc_append_entry            (GstToc *toc, GstTocEntry *entry);
 157
 158 GST_API
 159 GList *            gst_toc_get_entries             (const GstToc *toc);
 160
 161 GST_API
 162 void               gst_toc_dump                    (GstToc *toc);
 163
 164 #define gst_toc_ref(toc)            (GstToc*)gst_mini_object_ref(GST_MINI_OBJECT_CAST(toc))
 165 #define gst_toc_unref(toc)          gst_mini_object_unref(GST_MINI_OBJECT_CAST(toc))
 166 #define gst_toc_copy(toc)           (GstToc*)gst_mini_object_copy(GST_MINI_OBJECT_CAST(toc))
 167 #define gst_toc_make_writable(toc)  (GstToc*)gst_mini_object_make_writable(GST_MINI_OBJECT_CAST(toc))
 168
 169 /* functions to create, ref and unref/free TOC entries */
 170
 171 GST_API
 172 GstTocEntry *   gst_toc_entry_new               (GstTocEntryType type, const gchar *uid);
 173
 174 #define gst_toc_entry_ref(entry)            (GstTocEntry*)gst_mini_object_ref(GST_MINI_OBJECT_CAST(entry))
 175 #define gst_toc_entry_unref(entry)          gst_mini_object_unref(GST_MINI_OBJECT_CAST(entry))
 176 #define gst_toc_entry_copy(entry)           (GstTocEntry*)gst_mini_object_copy(GST_MINI_OBJECT_CAST(entry))
 177 #define gst_toc_entry_make_writable(entry)  (GstTocEntry*)gst_mini_object_make_writable(GST_MINI_OBJECT_CAST(entry))
 178
 179 GST_API
 180 GstTocEntry *      gst_toc_find_entry                    (const GstToc *toc, const gchar *uid);
 181
 182 GST_API
 183 GstTocEntryType    gst_toc_entry_get_entry_type          (const GstTocEntry *entry);
 184
 185 GST_API
 186 const gchar *      gst_toc_entry_get_uid                 (const GstTocEntry *entry);
 187
 188 GST_API
 189 void               gst_toc_entry_append_sub_entry        (GstTocEntry *entry, GstTocEntry *subentry);
 190
 191 GST_API
 192 GList *            gst_toc_entry_get_sub_entries         (const GstTocEntry *entry);
 193
 194 GST_API
 195 void               gst_toc_entry_set_tags                (GstTocEntry *entry, GstTagList *tags);
 196
 197 GST_API
 198 void               gst_toc_entry_merge_tags              (GstTocEntry *entry, GstTagList *tags, GstTagMergeMode mode);
 199
 200 GST_API
 201 GstTagList *       gst_toc_entry_get_tags                (const GstTocEntry *entry);
 202
 203 GST_API
 204 gboolean           gst_toc_entry_is_alternative          (const GstTocEntry *entry);
 205
 206 GST_API
 207 gboolean           gst_toc_entry_is_sequence             (const GstTocEntry *entry);
 208
 209 GST_API
 210 void               gst_toc_entry_set_start_stop_times    (GstTocEntry *entry, gint64 start, gint64 stop);
 211
 212 GST_API
 213 gboolean           gst_toc_entry_get_start_stop_times    (const GstTocEntry *entry, gint64 *start, gint64 *stop);
 214
 215 GST_API
 216 void               gst_toc_entry_set_loop                (GstTocEntry *entry, GstTocLoopType loop_type, gint repeat_count);
 217
 218 GST_API
 219 gboolean           gst_toc_entry_get_loop                (const GstTocEntry *entry, GstTocLoopType *loop_type, gint *repeat_count);
 220
 221 GST_API
 222 GstToc *           gst_toc_entry_get_toc                 (GstTocEntry *entry);
 223
 224 GST_API
 225 GstTocEntry *      gst_toc_entry_get_parent              (GstTocEntry *entry);
 226
 227
 228 GST_API
 229 const gchar *      gst_toc_entry_type_get_nick     (GstTocEntryType type);
 230
 231 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 232 static inline void
 233 _gst_autoptr_toc_unref (GstToc *toc)
 234 {
 235   gst_toc_unref (toc);
 236 }
 237
 238 static inline void
 239 _gst_autoptr_toc_entry_unref (GstTocEntry *entry)
 240 {
 241   gst_toc_entry_unref (entry);
 242 }
 243
 244 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstToc, _gst_autoptr_toc_unref)
 245 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstTocEntry, _gst_autoptr_toc_entry_unref)
 246 #endif
 247
 248 G_END_DECLS
 249
 250 #endif /* __GST_TOC_H__ */
 251