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