gst/gsttoc.c

   1 /* GStreamer
   2  * (c) 2010, 2012 Alexander Saprykin <xelfium@gmail.com>
   3  *
   4  * gsttoc.c: GstToc initialization and parsing/creation
   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 /**
  23  * SECTION:gsttoc
  24  * @short_description: Generic table of contents support
  25  * @see_also: #GstStructure, #GstEvent, #GstMessage, #GstQuery
  26  *
  27  * #GstToc functions are used to create/free #GstToc and #GstTocEntry structures.
  28  * Also they are used to convert #GstToc into #GstStructure and vice versa.
  29  *
  30  * #GstToc lets you to inform other elements in pipeline or application that playing
  31  * source has some kind of table of contents (TOC). These may be chapters, editions,
  32  * angles or other types. For example: DVD chapters, Matroska chapters or cue sheet
  33  * TOC. Such TOC will be useful for applications to display instead of just a
  34  * playlist.
  35  *
  36  * Using TOC is very easy. Firstly, create #GstToc structure which represents root
  37  * contents of the source. You can also attach TOC-specific tags to it. Then fill
  38  * it with #GstTocEntry entries by appending them to the #GstToc using
  39  * gst_toc_append_entry(), and appending subentries to a #GstTocEntry using
  40  * gst_toc_entry_append_sub_entry().
  41  *
  42  * Note that root level of the TOC can contain only either editions or chapters. You
  43  * should not mix them together at the same level. Otherwise you will get serialization
  44  * /deserialization errors. Make sure that no one of the entries has negative start and
  45  *  stop values.
  46  *
  47  * Use gst_event_new_toc() to create a new TOC #GstEvent, and gst_event_parse_toc() to
  48  * parse received TOC event. Use gst_event_new_toc_select() to create a new TOC select #GstEvent,
  49  * and gst_event_parse_toc_select() to parse received TOC select event. The same rule for
  50  * the #GstMessage: gst_message_new_toc() to create new TOC #GstMessage, and
  51  * gst_message_parse_toc() to parse received TOC message.
  52  *
  53  * TOCs can have global scope or current scope. Global scope TOCs contain
  54  * all entries that can possibly be selected using a toc select event, and
  55  * are what an application is usually interested in. TOCs with current scope
  56  * only contain the parts of the TOC relevant to the currently selected/playing
  57  * stream; the current scope TOC is used by downstream elements such as muxers
  58  * to write correct TOC entries when transcoding files, for example. When
  59  * playing a DVD, the global TOC would contain a hierarchy of all titles,
  60  * chapters and angles, for example, while the current TOC would only contain
  61  * the chapters for the currently playing title if playback of a specific
  62  * title was requested.
  63  *
  64  * Applications and plugins should not rely on TOCs having a certain kind of
  65  * structure, but should allow for different alternatives. For example, a
  66  * simple CUE sheet embedded in a file may be presented as a flat list of
  67  * track entries, or could have a top-level edition node (or some other
  68  * alternative type entry) with track entries underneath that node; or even
  69  * multiple top-level edition nodes (or some other alternative type entries)
  70  * each with track entries underneath, in case the source file has extracted
  71  * a track listing from different sources).
  72  */
  73
  74 #ifdef HAVE_CONFIG_H
  75 #  include "config.h"
  76 #endif
  77
  78 #include "gst_private.h"
  79 #include "gstenumtypes.h"
  80 #include "gsttaglist.h"
  81 #include "gststructure.h"
  82 #include "gstvalue.h"
  83 #include "gsttoc.h"
  84 #include "gstpad.h"
  85 #include "gstquark.h"
  86
  87 struct _GstTocEntry
  88 {
  89   GstMiniObject mini_object;
  90
  91   GstToc *toc;
  92   GstTocEntry *parent;
  93
  94   gchar *uid;
  95   GstTocEntryType type;
  96   GstClockTime start, stop;
  97   GList *subentries;
  98   GstTagList *tags;
  99   GstTocLoopType loop_type;
 100   gint repeat_count;
 101 };
 102
 103 struct _GstToc
 104 {
 105   GstMiniObject mini_object;
 106
 107   GstTocScope scope;
 108   GList *entries;
 109   GstTagList *tags;
 110 };
 111
 112 #undef gst_toc_copy
 113 static GstToc *gst_toc_copy (const GstToc * toc);
 114 static void gst_toc_free (GstToc * toc);
 115 #undef gst_toc_entry_copy
 116 static GstTocEntry *gst_toc_entry_copy (const GstTocEntry * toc);
 117 static void gst_toc_entry_free (GstTocEntry * toc);
 118
 119 GType _gst_toc_type = 0;
 120 GType _gst_toc_entry_type = 0;
 121
 122 GST_DEFINE_MINI_OBJECT_TYPE (GstToc, gst_toc);
 123 GST_DEFINE_MINI_OBJECT_TYPE (GstTocEntry, gst_toc_entry);
 124
 125 /**
 126  * gst_toc_new:
 127  * @scope: scope of this TOC
 128  *
 129  * Create a new #GstToc structure.
 130  *
 131  * Returns: (transfer full): newly allocated #GstToc structure, free it
 132  *     with gst_toc_unref().
 133  */
 134 GstToc *
 135 gst_toc_new (GstTocScope scope)
 136 {
 137   GstToc *toc;
 138
 139   g_return_val_if_fail (scope == GST_TOC_SCOPE_GLOBAL ||
 140       scope == GST_TOC_SCOPE_CURRENT, NULL);
 141
 142   toc = g_slice_new0 (GstToc);
 143
 144   gst_mini_object_init (GST_MINI_OBJECT_CAST (toc), 0, GST_TYPE_TOC,
 145       (GstMiniObjectCopyFunction) gst_toc_copy, NULL,
 146       (GstMiniObjectFreeFunction) gst_toc_free);
 147
 148   toc->scope = scope;
 149   toc->tags = gst_tag_list_new_empty ();
 150
 151   return toc;
 152 }
 153
 154 /**
 155  * gst_toc_get_scope:
 156  * @toc: a #GstToc instance
 157  *
 158  * Returns: scope of @toc
 159  */
 160 GstTocScope
 161 gst_toc_get_scope (const GstToc * toc)
 162 {
 163   g_return_val_if_fail (toc != NULL, GST_TOC_SCOPE_GLOBAL);
 164
 165   return toc->scope;
 166 }
 167
 168 /**
 169  * gst_toc_set_tags:
 170  * @toc: A #GstToc instance
 171  * @tags: (allow-none) (transfer full): A #GstTagList or %NULL
 172  *
 173  * Set a #GstTagList with tags for the complete @toc.
 174  */
 175 void
 176 gst_toc_set_tags (GstToc * toc, GstTagList * tags)
 177 {
 178   g_return_if_fail (toc != NULL);
 179   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 180
 181   if (toc->tags)
 182     gst_tag_list_unref (toc->tags);
 183   toc->tags = tags;
 184 }
 185
 186 /**
 187  * gst_toc_merge_tags:
 188  * @toc: A #GstToc instance
 189  * @tags: (allow-none): A #GstTagList or %NULL
 190  * @mode: A #GstTagMergeMode
 191  *
 192  * Merge @tags into the existing tags of @toc using @mode.
 193  */
 194 void
 195 gst_toc_merge_tags (GstToc * toc, GstTagList * tags, GstTagMergeMode mode)
 196 {
 197   g_return_if_fail (toc != NULL);
 198   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 199
 200   if (!toc->tags) {
 201     toc->tags = gst_tag_list_ref (tags);
 202   } else {
 203     GstTagList *tmp = gst_tag_list_merge (toc->tags, tags, mode);
 204     gst_tag_list_unref (toc->tags);
 205     toc->tags = tmp;
 206   }
 207 }
 208
 209 /**
 210  * gst_toc_get_tags:
 211  * @toc: A #GstToc instance
 212  *
 213  * Gets the tags for @toc.
 214  *
 215  * Returns: (transfer none): A #GstTagList for @entry
 216  */
 217 GstTagList *
 218 gst_toc_get_tags (const GstToc * toc)
 219 {
 220   g_return_val_if_fail (toc != NULL, NULL);
 221
 222   return toc->tags;
 223 }
 224
 225 /**
 226  * gst_toc_append_entry:
 227  * @toc: A #GstToc instance
 228  * @entry: (transfer full): A #GstTocEntry
 229  *
 230  * Appends the #GstTocEntry @entry to @toc.
 231  */
 232 void
 233 gst_toc_append_entry (GstToc * toc, GstTocEntry * entry)
 234 {
 235   g_return_if_fail (toc != NULL);
 236   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 237   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 238   g_return_if_fail (entry->toc == NULL);
 239   g_return_if_fail (entry->parent == NULL);
 240
 241   toc->entries = g_list_append (toc->entries, entry);
 242   entry->toc = toc;
 243
 244   GST_LOG ("appended %s entry with uid %s to toc %p",
 245       gst_toc_entry_type_get_nick (entry->type), entry->uid, toc);
 246
 247   gst_toc_dump (toc);
 248 }
 249
 250 /**
 251  * gst_toc_get_entries:
 252  * @toc: A #GstToc instance
 253  *
 254  * Gets the list of #GstTocEntry of @toc.
 255  *
 256  * Returns: (transfer none) (element-type Gst.TocEntry): A #GList of #GstTocEntry for @entry
 257  */
 258 GList *
 259 gst_toc_get_entries (const GstToc * toc)
 260 {
 261   g_return_val_if_fail (toc != NULL, NULL);
 262
 263   return toc->entries;
 264 }
 265
 266 static GstTocEntry *
 267 gst_toc_entry_new_internal (GstTocEntryType type, const gchar * uid)
 268 {
 269   GstTocEntry *entry;
 270
 271   entry = g_slice_new0 (GstTocEntry);
 272
 273   gst_mini_object_init (GST_MINI_OBJECT_CAST (entry), 0, GST_TYPE_TOC_ENTRY,
 274       (GstMiniObjectCopyFunction) gst_toc_entry_copy, NULL,
 275       (GstMiniObjectFreeFunction) gst_toc_entry_free);
 276
 277   entry->uid = g_strdup (uid);
 278   entry->type = type;
 279   entry->tags = NULL;
 280   entry->start = entry->stop = GST_CLOCK_TIME_NONE;
 281
 282   return entry;
 283 }
 284
 285 /**
 286  * gst_toc_entry_new:
 287  * @type: entry type.
 288  * @uid: unique ID (UID) in the whole TOC.
 289  *
 290  * Create new #GstTocEntry structure.
 291  *
 292  * Returns: newly allocated #GstTocEntry structure, free it with gst_toc_entry_unref().
 293  */
 294 GstTocEntry *
 295 gst_toc_entry_new (GstTocEntryType type, const gchar * uid)
 296 {
 297   g_return_val_if_fail (uid != NULL, NULL);
 298
 299   return gst_toc_entry_new_internal (type, uid);
 300 }
 301
 302 static void
 303 gst_toc_free (GstToc * toc)
 304 {
 305   g_list_foreach (toc->entries, (GFunc) gst_mini_object_unref, NULL);
 306   g_list_free (toc->entries);
 307
 308   if (toc->tags != NULL)
 309     gst_tag_list_unref (toc->tags);
 310
 311   g_slice_free (GstToc, toc);
 312 }
 313
 314 static void
 315 gst_toc_entry_free (GstTocEntry * entry)
 316 {
 317   g_return_if_fail (entry != NULL);
 318
 319   g_list_foreach (entry->subentries, (GFunc) gst_mini_object_unref, NULL);
 320   g_list_free (entry->subentries);
 321
 322   g_free (entry->uid);
 323
 324   if (entry->tags != NULL)
 325     gst_tag_list_unref (entry->tags);
 326
 327   g_slice_free (GstTocEntry, entry);
 328 }
 329
 330 static GstTocEntry *
 331 gst_toc_entry_find_sub_entry (const GstTocEntry * entry, const gchar * uid)
 332 {
 333   GList *cur;
 334   GstTocEntry *subentry, *subsubentry;
 335
 336   g_return_val_if_fail (entry != NULL, NULL);
 337   g_return_val_if_fail (uid != NULL, NULL);
 338
 339   cur = entry->subentries;
 340   while (cur != NULL) {
 341     subentry = cur->data;
 342
 343     if (g_strcmp0 (subentry->uid, uid) == 0)
 344       return subentry;
 345
 346     subsubentry = gst_toc_entry_find_sub_entry (subentry, uid);
 347     if (subsubentry != NULL)
 348       return subsubentry;
 349
 350     cur = cur->next;
 351   }
 352
 353   return NULL;
 354 }
 355
 356 /**
 357  * gst_toc_find_entry:
 358  * @toc: #GstToc to search in.
 359  * @uid: UID to find #GstTocEntry with.
 360  *
 361  * Find #GstTocEntry with given @uid in the @toc.
 362  *
 363  * Returns: (transfer none) (nullable): #GstTocEntry with specified
 364  * @uid from the @toc, or %NULL if not found.
 365  */
 366 GstTocEntry *
 367 gst_toc_find_entry (const GstToc * toc, const gchar * uid)
 368 {
 369   GList *cur;
 370   GstTocEntry *entry, *subentry;
 371
 372   g_return_val_if_fail (toc != NULL, NULL);
 373   g_return_val_if_fail (uid != NULL, NULL);
 374
 375   cur = toc->entries;
 376   while (cur != NULL) {
 377     entry = cur->data;
 378
 379     if (g_strcmp0 (entry->uid, uid) == 0)
 380       return entry;
 381
 382     subentry = gst_toc_entry_find_sub_entry (entry, uid);
 383     if (subentry != NULL)
 384       return subentry;
 385     cur = cur->next;
 386   }
 387
 388   return NULL;
 389 }
 390
 391 /**
 392  * gst_toc_entry_copy:
 393  * @entry: #GstTocEntry to copy.
 394  *
 395  * Copy #GstTocEntry with all subentries (deep copy).
 396  *
 397  * Returns: (nullable): newly allocated #GstTocEntry in case of
 398  * success, %NULL otherwise; free it when done with
 399  * gst_toc_entry_unref().
 400  */
 401 static GstTocEntry *
 402 gst_toc_entry_copy (const GstTocEntry * entry)
 403 {
 404   GstTocEntry *ret, *sub;
 405   GstTagList *list;
 406   GList *cur;
 407
 408   g_return_val_if_fail (entry != NULL, NULL);
 409
 410   ret = gst_toc_entry_new (entry->type, entry->uid);
 411
 412   ret->start = entry->start;
 413   ret->stop = entry->stop;
 414
 415   if (GST_IS_TAG_LIST (entry->tags)) {
 416     list = gst_tag_list_copy (entry->tags);
 417     if (ret->tags)
 418       gst_tag_list_unref (ret->tags);
 419     ret->tags = list;
 420   }
 421
 422   cur = entry->subentries;
 423   while (cur != NULL) {
 424     sub = gst_toc_entry_copy (cur->data);
 425
 426     if (sub != NULL)
 427       ret->subentries = g_list_prepend (ret->subentries, sub);
 428
 429     cur = cur->next;
 430   }
 431   ret->subentries = g_list_reverse (ret->subentries);
 432
 433   return ret;
 434 }
 435
 436 /**
 437  * gst_toc_copy:
 438  * @toc: #GstToc to copy.
 439  *
 440  * Copy #GstToc with all subentries (deep copy).
 441  *
 442  * Returns: (nullable): newly allocated #GstToc in case of success,
 443  * %NULL otherwise; free it when done with gst_toc_unref().
 444  */
 445 static GstToc *
 446 gst_toc_copy (const GstToc * toc)
 447 {
 448   GstToc *ret;
 449   GstTocEntry *entry;
 450   GList *cur;
 451   GstTagList *list;
 452
 453   g_return_val_if_fail (toc != NULL, NULL);
 454
 455   ret = gst_toc_new (toc->scope);
 456
 457   if (GST_IS_TAG_LIST (toc->tags)) {
 458     list = gst_tag_list_copy (toc->tags);
 459     gst_tag_list_unref (ret->tags);
 460     ret->tags = list;
 461   }
 462
 463   cur = toc->entries;
 464   while (cur != NULL) {
 465     entry = gst_toc_entry_copy (cur->data);
 466
 467     if (entry != NULL)
 468       ret->entries = g_list_prepend (ret->entries, entry);
 469
 470     cur = cur->next;
 471   }
 472   ret->entries = g_list_reverse (ret->entries);
 473   return ret;
 474 }
 475
 476 /**
 477  * gst_toc_entry_set_start_stop_times:
 478  * @entry: #GstTocEntry to set values.
 479  * @start: start value to set.
 480  * @stop: stop value to set.
 481  *
 482  * Set @start and @stop values for the @entry.
 483  */
 484 void
 485 gst_toc_entry_set_start_stop_times (GstTocEntry * entry, gint64 start,
 486     gint64 stop)
 487 {
 488   g_return_if_fail (entry != NULL);
 489
 490   entry->start = start;
 491   entry->stop = stop;
 492 }
 493
 494 /**
 495  * gst_toc_entry_get_start_stop_times:
 496  * @entry: #GstTocEntry to get values from.
 497  * @start: (out) (allow-none): the storage for the start value, leave
 498  *   %NULL if not need.
 499  * @stop: (out) (allow-none): the storage for the stop value, leave
 500  *   %NULL if not need.
 501  *
 502  * Get @start and @stop values from the @entry and write them into appropriate
 503  * storages.
 504  *
 505  * Returns: %TRUE if all non-%NULL storage pointers were filled with appropriate
 506  * values, %FALSE otherwise.
 507  */
 508 gboolean
 509 gst_toc_entry_get_start_stop_times (const GstTocEntry * entry, gint64 * start,
 510     gint64 * stop)
 511 {
 512   g_return_val_if_fail (entry != NULL, FALSE);
 513
 514   if (start != NULL)
 515     *start = entry->start;
 516   if (stop != NULL)
 517     *stop = entry->stop;
 518
 519   return TRUE;
 520 }
 521
 522 /**
 523  * gst_toc_entry_set_loop:
 524  * @entry: #GstTocEntry to set values.
 525  * @loop_type: loop_type value to set.
 526  * @repeat_count: repeat_count value to set.
 527  *
 528  * Set @loop_type and @repeat_count values for the @entry.
 529  *
 530  * Since: 1.4
 531  */
 532 void
 533 gst_toc_entry_set_loop (GstTocEntry * entry, GstTocLoopType loop_type,
 534     gint repeat_count)
 535 {
 536   g_return_if_fail (entry != NULL);
 537
 538   entry->loop_type = loop_type;
 539   entry->repeat_count = repeat_count;
 540 }
 541
 542 /**
 543  * gst_toc_entry_get_loop:
 544  * @entry: #GstTocEntry to get values from.
 545  * @loop_type: (out) (allow-none): the storage for the loop_type
 546  *             value, leave %NULL if not need.
 547  * @repeat_count: (out) (allow-none): the storage for the repeat_count
 548  *                value, leave %NULL if not need.
 549  *
 550  * Get @loop_type and @repeat_count values from the @entry and write them into
 551  * appropriate storages. Loops are e.g. used by sampled instruments. GStreamer
 552  * is not automatically applying the loop. The application can process this
 553  * meta data and use it e.g. to send a seek-event to loop a section.
 554  *
 555  * Returns: %TRUE if all non-%NULL storage pointers were filled with appropriate
 556  * values, %FALSE otherwise.
 557  *
 558  * Since: 1.4
 559  */
 560 gboolean
 561 gst_toc_entry_get_loop (const GstTocEntry * entry, GstTocLoopType * loop_type,
 562     gint * repeat_count)
 563 {
 564   g_return_val_if_fail (entry != NULL, FALSE);
 565
 566   if (loop_type != NULL)
 567     *loop_type = entry->loop_type;
 568   if (repeat_count != NULL)
 569     *repeat_count = entry->repeat_count;
 570
 571   return TRUE;
 572 }
 573
 574
 575 /**
 576  * gst_toc_entry_type_get_nick:
 577  * @type: a #GstTocEntryType.
 578  *
 579  * Converts @type to a string representation.
 580  *
 581  * Returns: Returns a human-readable string for @type. This string is
 582  *    only for debugging purpose and should not be displayed in a user
 583  *    interface.
 584  */
 585 const gchar *
 586 gst_toc_entry_type_get_nick (GstTocEntryType type)
 587 {
 588   switch (type) {
 589     case GST_TOC_ENTRY_TYPE_ANGLE:
 590       return "angle";
 591     case GST_TOC_ENTRY_TYPE_VERSION:
 592       return "version";
 593     case GST_TOC_ENTRY_TYPE_EDITION:
 594       return "edition";
 595     case GST_TOC_ENTRY_TYPE_TITLE:
 596       return "title";
 597     case GST_TOC_ENTRY_TYPE_TRACK:
 598       return "track";
 599     case GST_TOC_ENTRY_TYPE_CHAPTER:
 600       return "chapter";
 601     default:
 602       break;
 603   }
 604   return "invalid";
 605 }
 606
 607 /**
 608  * gst_toc_entry_get_entry_type:
 609  * @entry: a #GstTocEntry
 610  *
 611  * Returns: @entry's entry type
 612  */
 613 GstTocEntryType
 614 gst_toc_entry_get_entry_type (const GstTocEntry * entry)
 615 {
 616   g_return_val_if_fail (entry != NULL, GST_TOC_ENTRY_TYPE_INVALID);
 617
 618   return entry->type;
 619 }
 620
 621 /**
 622  * gst_toc_entry_is_alternative:
 623  * @entry: a #GstTocEntry
 624  *
 625  * Returns: %TRUE if @entry's type is an alternative type, otherwise %FALSE
 626  */
 627 gboolean
 628 gst_toc_entry_is_alternative (const GstTocEntry * entry)
 629 {
 630   g_return_val_if_fail (entry != NULL, FALSE);
 631
 632   return GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE (entry->type);
 633 }
 634
 635 /**
 636  * gst_toc_entry_is_sequence:
 637  * @entry: a #GstTocEntry
 638  *
 639  * Returns: %TRUE if @entry's type is a sequence type, otherwise %FALSE
 640  */
 641 gboolean
 642 gst_toc_entry_is_sequence (const GstTocEntry * entry)
 643 {
 644   g_return_val_if_fail (entry != NULL, FALSE);
 645
 646   return GST_TOC_ENTRY_TYPE_IS_SEQUENCE (entry->type);
 647 }
 648
 649 /**
 650  * gst_toc_entry_get_uid:
 651  * @entry: A #GstTocEntry instance
 652  *
 653  * Gets the UID of @entry.
 654  *
 655  * Returns: (transfer none): The UID of @entry
 656  */
 657 const gchar *
 658 gst_toc_entry_get_uid (const GstTocEntry * entry)
 659 {
 660   g_return_val_if_fail (entry != NULL, NULL);
 661
 662   return entry->uid;
 663 }
 664
 665 /**
 666  * gst_toc_entry_append_sub_entry:
 667  * @entry: A #GstTocEntry instance
 668  * @subentry: (transfer full): A #GstTocEntry
 669  *
 670  * Appends the #GstTocEntry @subentry to @entry.
 671  */
 672 void
 673 gst_toc_entry_append_sub_entry (GstTocEntry * entry, GstTocEntry * subentry)
 674 {
 675   g_return_if_fail (entry != NULL);
 676   g_return_if_fail (subentry != NULL);
 677   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 678   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST
 679           (subentry)));
 680   g_return_if_fail (subentry->toc == NULL);
 681   g_return_if_fail (subentry->parent == NULL);
 682
 683   entry->subentries = g_list_append (entry->subentries, subentry);
 684   subentry->toc = entry->toc;
 685   subentry->parent = entry;
 686
 687   GST_LOG ("appended %s subentry with uid %s to entry %s",
 688       gst_toc_entry_type_get_nick (subentry->type), subentry->uid, entry->uid);
 689 }
 690
 691 /**
 692  * gst_toc_entry_get_sub_entries:
 693  * @entry: A #GstTocEntry instance
 694  *
 695  * Gets the sub-entries of @entry.
 696  *
 697  * Returns: (transfer none) (element-type Gst.TocEntry): A #GList of #GstTocEntry of @entry
 698  */
 699 GList *
 700 gst_toc_entry_get_sub_entries (const GstTocEntry * entry)
 701 {
 702   g_return_val_if_fail (entry != NULL, NULL);
 703
 704   return entry->subentries;
 705 }
 706
 707 /**
 708  * gst_toc_entry_set_tags:
 709  * @entry: A #GstTocEntry instance
 710  * @tags: (allow-none) (transfer full): A #GstTagList or %NULL
 711  *
 712  * Set a #GstTagList with tags for the complete @entry.
 713  */
 714 void
 715 gst_toc_entry_set_tags (GstTocEntry * entry, GstTagList * tags)
 716 {
 717   g_return_if_fail (entry != NULL);
 718   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 719
 720   if (entry->tags)
 721     gst_tag_list_unref (entry->tags);
 722   entry->tags = tags;
 723 }
 724
 725 /**
 726  * gst_toc_entry_merge_tags:
 727  * @entry: A #GstTocEntry instance
 728  * @tags: (allow-none): A #GstTagList or %NULL
 729  * @mode: A #GstTagMergeMode
 730  *
 731  * Merge @tags into the existing tags of @entry using @mode.
 732  */
 733 void
 734 gst_toc_entry_merge_tags (GstTocEntry * entry, GstTagList * tags,
 735     GstTagMergeMode mode)
 736 {
 737   g_return_if_fail (entry != NULL);
 738   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 739
 740   if (!entry->tags) {
 741     entry->tags = gst_tag_list_ref (tags);
 742   } else {
 743     GstTagList *tmp = gst_tag_list_merge (entry->tags, tags, mode);
 744     gst_tag_list_unref (entry->tags);
 745     entry->tags = tmp;
 746   }
 747 }
 748
 749 /**
 750  * gst_toc_entry_get_tags:
 751  * @entry: A #GstTocEntry instance
 752  *
 753  * Gets the tags for @entry.
 754  *
 755  * Returns: (transfer none): A #GstTagList for @entry
 756  */
 757 GstTagList *
 758 gst_toc_entry_get_tags (const GstTocEntry * entry)
 759 {
 760   g_return_val_if_fail (entry != NULL, NULL);
 761
 762   return entry->tags;
 763 }
 764
 765 /**
 766  * gst_toc_entry_get_toc:
 767  * @entry: A #GstTocEntry instance
 768  *
 769  * Gets the parent #GstToc of @entry.
 770  *
 771  * Returns: (transfer none): The parent #GstToc of @entry
 772  */
 773 GstToc *
 774 gst_toc_entry_get_toc (GstTocEntry * entry)
 775 {
 776   g_return_val_if_fail (entry != NULL, NULL);
 777
 778   return entry->toc;
 779 }
 780
 781 /**
 782  * gst_toc_entry_get_parent:
 783  * @entry: A #GstTocEntry instance
 784  *
 785  * Gets the parent #GstTocEntry of @entry.
 786  *
 787  * Returns: (transfer none): The parent #GstTocEntry of @entry
 788  */
 789 GstTocEntry *
 790 gst_toc_entry_get_parent (GstTocEntry * entry)
 791 {
 792   g_return_val_if_fail (entry != NULL, NULL);
 793
 794   return entry->parent;
 795 }
 796
 797 #ifndef GST_DISABLE_GST_DEBUG
 798 static void
 799 gst_toc_dump_entries (GList * entries, guint depth)
 800 {
 801   GList *e;
 802   gchar *indent;
 803
 804   indent = g_malloc0 (depth + 1);
 805   memset (indent, ' ', depth);
 806   for (e = entries; e != NULL; e = e->next) {
 807     GstTocEntry *entry = e->data;
 808
 809     GST_TRACE ("%s+ %s (%s), %" GST_TIME_FORMAT " - %" GST_TIME_FORMAT ", "
 810         "tags: %" GST_PTR_FORMAT, indent, entry->uid,
 811         gst_toc_entry_type_get_nick (entry->type),
 812         GST_TIME_ARGS (entry->start), GST_TIME_ARGS (entry->stop), entry->tags);
 813
 814     if (entry->subentries != NULL)
 815       gst_toc_dump_entries (entry->subentries, depth + 2);
 816   }
 817   g_free (indent);
 818 }
 819 #endif
 820
 821 void
 822 gst_toc_dump (GstToc * toc)
 823 {
 824 #ifndef GST_DISABLE_GST_DEBUG
 825   GST_TRACE ("        Toc %p, scope: %s, tags: %" GST_PTR_FORMAT, toc,
 826       (toc->scope == GST_TOC_SCOPE_GLOBAL) ? "global" : "current", toc->tags);
 827   gst_toc_dump_entries (toc->entries, 2);
 828 #endif
 829 }
 830
 831 void
 832 _priv_gst_toc_initialize (void)
 833 {
 834   _gst_toc_type = gst_toc_get_type ();
 835   _gst_toc_entry_type = gst_toc_entry_get_type ();
 836 }