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 };
 100
 101 struct _GstToc
 102 {
 103   GstMiniObject mini_object;
 104
 105   GstTocScope scope;
 106   GList *entries;
 107   GstTagList *tags;
 108 };
 109
 110 #undef gst_toc_copy
 111 static GstToc *gst_toc_copy (const GstToc * toc);
 112 static void gst_toc_free (GstToc * toc);
 113 #undef gst_toc_entry_copy
 114 static GstTocEntry *gst_toc_entry_copy (const GstTocEntry * toc);
 115 static void gst_toc_entry_free (GstTocEntry * toc);
 116
 117 GST_DEFINE_MINI_OBJECT_TYPE (GstToc, gst_toc);
 118 GST_DEFINE_MINI_OBJECT_TYPE (GstTocEntry, gst_toc_entry);
 119
 120 /**
 121  * gst_toc_new:
 122  * @scope: scope of this TOC
 123  *
 124  * Create a new #GstToc structure.
 125  *
 126  * Returns: (transfer full): newly allocated #GstToc structure, free it
 127  *     with gst_toc_unref().
 128  */
 129 GstToc *
 130 gst_toc_new (GstTocScope scope)
 131 {
 132   GstToc *toc;
 133
 134   g_return_val_if_fail (scope == GST_TOC_SCOPE_GLOBAL ||
 135       scope == GST_TOC_SCOPE_CURRENT, NULL);
 136
 137   toc = g_slice_new0 (GstToc);
 138
 139   gst_mini_object_init (GST_MINI_OBJECT_CAST (toc), 0, GST_TYPE_TOC,
 140       (GstMiniObjectCopyFunction) gst_toc_copy, NULL,
 141       (GstMiniObjectFreeFunction) gst_toc_free);
 142
 143   toc->scope = scope;
 144   toc->tags = gst_tag_list_new_empty ();
 145
 146   return toc;
 147 }
 148
 149 /**
 150  * gst_toc_get_scope:
 151  * @toc: a #GstToc instance
 152  *
 153  * Returns: scope of @toc
 154  */
 155 GstTocScope
 156 gst_toc_get_scope (const GstToc * toc)
 157 {
 158   g_return_val_if_fail (toc != NULL, GST_TOC_SCOPE_GLOBAL);
 159
 160   return toc->scope;
 161 }
 162
 163 /**
 164  * gst_toc_set_tags:
 165  * @toc: A #GstToc instance
 166  * @tags: (allow-none) (transfer full): A #GstTagList or %NULL
 167  *
 168  * Set a #GstTagList with tags for the complete @toc.
 169  */
 170 void
 171 gst_toc_set_tags (GstToc * toc, GstTagList * tags)
 172 {
 173   g_return_if_fail (toc != NULL);
 174   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 175
 176   if (toc->tags)
 177     gst_tag_list_unref (toc->tags);
 178   toc->tags = tags;
 179 }
 180
 181 /**
 182  * gst_toc_merge_tags:
 183  * @toc: A #GstToc instance
 184  * @tags: (allow-none): A #GstTagList or %NULL
 185  * @mode: A #GstTagMergeMode
 186  *
 187  * Merge @tags into the existing tags of @toc using @mode.
 188  */
 189 void
 190 gst_toc_merge_tags (GstToc * toc, GstTagList * tags, GstTagMergeMode mode)
 191 {
 192   g_return_if_fail (toc != NULL);
 193   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 194
 195   if (!toc->tags) {
 196     toc->tags = gst_tag_list_ref (tags);
 197   } else {
 198     GstTagList *tmp = gst_tag_list_merge (toc->tags, tags, mode);
 199     gst_tag_list_unref (toc->tags);
 200     toc->tags = tmp;
 201   }
 202 }
 203
 204 /**
 205  * gst_toc_get_tags:
 206  * @toc: A #GstToc instance
 207  *
 208  * Gets the tags for @toc.
 209  *
 210  * Returns: (transfer none): A #GstTagList for @entry
 211  */
 212 GstTagList *
 213 gst_toc_get_tags (const GstToc * toc)
 214 {
 215   g_return_val_if_fail (toc != NULL, NULL);
 216
 217   return toc->tags;
 218 }
 219
 220 /**
 221  * gst_toc_append_entry:
 222  * @toc: A #GstToc instance
 223  * @entry: (transfer full): A #GstTocEntry
 224  *
 225  * Appends the #GstTocEntry @entry to @toc.
 226  */
 227 void
 228 gst_toc_append_entry (GstToc * toc, GstTocEntry * entry)
 229 {
 230   g_return_if_fail (toc != NULL);
 231   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 232   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 233   g_return_if_fail (entry->toc == NULL);
 234   g_return_if_fail (entry->parent == NULL);
 235
 236   toc->entries = g_list_append (toc->entries, entry);
 237   entry->toc = toc;
 238
 239   GST_LOG ("appended %s entry with uid %s to toc %p",
 240       gst_toc_entry_type_get_nick (entry->type), entry->uid, toc);
 241
 242   gst_toc_dump (toc);
 243 }
 244
 245 /**
 246  * gst_toc_get_entries:
 247  * @toc: A #GstToc instance
 248  *
 249  * Gets the list of #GstTocEntry of @toc.
 250  *
 251  * Returns: (transfer none) (element-type Gst.TocEntry): A #GList of #GstTocEntry for @entry
 252  */
 253 GList *
 254 gst_toc_get_entries (const GstToc * toc)
 255 {
 256   g_return_val_if_fail (toc != NULL, NULL);
 257
 258   return toc->entries;
 259 }
 260
 261 static GstTocEntry *
 262 gst_toc_entry_new_internal (GstTocEntryType type, const gchar * uid)
 263 {
 264   GstTocEntry *entry;
 265
 266   entry = g_slice_new0 (GstTocEntry);
 267
 268   gst_mini_object_init (GST_MINI_OBJECT_CAST (entry), 0, GST_TYPE_TOC_ENTRY,
 269       (GstMiniObjectCopyFunction) gst_toc_entry_copy, NULL,
 270       (GstMiniObjectFreeFunction) gst_toc_entry_free);
 271
 272   entry->uid = g_strdup (uid);
 273   entry->type = type;
 274   entry->tags = NULL;
 275   entry->start = entry->stop = GST_CLOCK_TIME_NONE;
 276
 277   return entry;
 278 }
 279
 280 /**
 281  * gst_toc_entry_new:
 282  * @type: entry type.
 283  * @uid: unique ID (UID) in the whole TOC.
 284  *
 285  * Create new #GstTocEntry structure.
 286  *
 287  * Returns: newly allocated #GstTocEntry structure, free it with gst_toc_entry_unref().
 288  */
 289 GstTocEntry *
 290 gst_toc_entry_new (GstTocEntryType type, const gchar * uid)
 291 {
 292   g_return_val_if_fail (uid != NULL, NULL);
 293
 294   return gst_toc_entry_new_internal (type, uid);
 295 }
 296
 297 static void
 298 gst_toc_free (GstToc * toc)
 299 {
 300   g_list_foreach (toc->entries, (GFunc) gst_mini_object_unref, NULL);
 301   g_list_free (toc->entries);
 302
 303   if (toc->tags != NULL)
 304     gst_tag_list_unref (toc->tags);
 305
 306   g_slice_free (GstToc, toc);
 307 }
 308
 309 static void
 310 gst_toc_entry_free (GstTocEntry * entry)
 311 {
 312   g_return_if_fail (entry != NULL);
 313
 314   g_list_foreach (entry->subentries, (GFunc) gst_mini_object_unref, NULL);
 315   g_list_free (entry->subentries);
 316
 317   g_free (entry->uid);
 318
 319   if (entry->tags != NULL)
 320     gst_tag_list_unref (entry->tags);
 321
 322   g_slice_free (GstTocEntry, entry);
 323 }
 324
 325 static GstTocEntry *
 326 gst_toc_entry_find_sub_entry (const GstTocEntry * entry, const gchar * uid)
 327 {
 328   GList *cur;
 329   GstTocEntry *subentry, *subsubentry;
 330
 331   g_return_val_if_fail (entry != NULL, NULL);
 332   g_return_val_if_fail (uid != NULL, NULL);
 333
 334   cur = entry->subentries;
 335   while (cur != NULL) {
 336     subentry = cur->data;
 337
 338     if (g_strcmp0 (subentry->uid, uid) == 0)
 339       return subentry;
 340
 341     subsubentry = gst_toc_entry_find_sub_entry (subentry, uid);
 342     if (subsubentry != NULL)
 343       return subsubentry;
 344
 345     cur = cur->next;
 346   }
 347
 348   return NULL;
 349 }
 350
 351 /**
 352  * gst_toc_find_entry:
 353  * @toc: #GstToc to search in.
 354  * @uid: UID to find #GstTocEntry with.
 355  *
 356  * Find #GstTocEntry with given @uid in the @toc.
 357  *
 358  * Returns: (transfer none): #GstTocEntry with specified @uid from the @toc, or NULL if not found.
 359  */
 360 GstTocEntry *
 361 gst_toc_find_entry (const GstToc * toc, const gchar * uid)
 362 {
 363   GList *cur;
 364   GstTocEntry *entry, *subentry;
 365
 366   g_return_val_if_fail (toc != NULL, NULL);
 367   g_return_val_if_fail (uid != NULL, NULL);
 368
 369   cur = toc->entries;
 370   while (cur != NULL) {
 371     entry = cur->data;
 372
 373     if (g_strcmp0 (entry->uid, uid) == 0)
 374       return entry;
 375
 376     subentry = gst_toc_entry_find_sub_entry (entry, uid);
 377     if (subentry != NULL)
 378       return subentry;
 379     cur = cur->next;
 380   }
 381
 382   return NULL;
 383 }
 384
 385 /**
 386  * gst_toc_entry_copy:
 387  * @entry: #GstTocEntry to copy.
 388  *
 389  * Copy #GstTocEntry with all subentries (deep copy).
 390  *
 391  * Returns: newly allocated #GstTocEntry in case of success, NULL otherwise;
 392  * free it when done with gst_toc_entry_unref().
 393  */
 394 static GstTocEntry *
 395 gst_toc_entry_copy (const GstTocEntry * entry)
 396 {
 397   GstTocEntry *ret, *sub;
 398   GstTagList *list;
 399   GList *cur;
 400
 401   g_return_val_if_fail (entry != NULL, NULL);
 402
 403   ret = gst_toc_entry_new (entry->type, entry->uid);
 404
 405   ret->start = entry->start;
 406   ret->stop = entry->stop;
 407
 408   if (GST_IS_TAG_LIST (entry->tags)) {
 409     list = gst_tag_list_copy (entry->tags);
 410     if (ret->tags)
 411       gst_tag_list_unref (ret->tags);
 412     ret->tags = list;
 413   }
 414
 415   cur = entry->subentries;
 416   while (cur != NULL) {
 417     sub = gst_toc_entry_copy (cur->data);
 418
 419     if (sub != NULL)
 420       ret->subentries = g_list_prepend (ret->subentries, sub);
 421
 422     cur = cur->next;
 423   }
 424   ret->subentries = g_list_reverse (ret->subentries);
 425
 426   return ret;
 427 }
 428
 429 /**
 430  * gst_toc_copy:
 431  * @toc: #GstToc to copy.
 432  *
 433  * Copy #GstToc with all subentries (deep copy).
 434  *
 435  * Returns: newly allocated #GstToc in case of success, NULL otherwise;
 436  * free it when done with gst_toc_unref().
 437  */
 438 static GstToc *
 439 gst_toc_copy (const GstToc * toc)
 440 {
 441   GstToc *ret;
 442   GstTocEntry *entry;
 443   GList *cur;
 444   GstTagList *list;
 445
 446   g_return_val_if_fail (toc != NULL, NULL);
 447
 448   ret = gst_toc_new (toc->scope);
 449
 450   if (GST_IS_TAG_LIST (toc->tags)) {
 451     list = gst_tag_list_copy (toc->tags);
 452     gst_tag_list_unref (ret->tags);
 453     ret->tags = list;
 454   }
 455
 456   cur = toc->entries;
 457   while (cur != NULL) {
 458     entry = gst_toc_entry_copy (cur->data);
 459
 460     if (entry != NULL)
 461       ret->entries = g_list_prepend (ret->entries, entry);
 462
 463     cur = cur->next;
 464   }
 465   ret->entries = g_list_reverse (ret->entries);
 466   return ret;
 467 }
 468
 469 /**
 470  * gst_toc_entry_set_start_stop_times:
 471  * @entry: #GstTocEntry to set values.
 472  * @start: start value to set.
 473  * @stop: stop value to set.
 474  *
 475  * Set @start and @stop values for the @entry.
 476  */
 477 void
 478 gst_toc_entry_set_start_stop_times (GstTocEntry * entry, gint64 start,
 479     gint64 stop)
 480 {
 481   g_return_if_fail (entry != NULL);
 482
 483   entry->start = start;
 484   entry->stop = stop;
 485 }
 486
 487 /**
 488  * gst_toc_entry_get_start_stop_times:
 489  * @entry: #GstTocEntry to get values from.
 490  * @start: (out): the storage for the start value, leave #NULL if not need.
 491  * @stop: (out): the storage for the stop value, leave #NULL if not need.
 492  *
 493  * Get start and stop values from the @entry and write them into appropriate storages.
 494  *
 495  * Returns: TRUE if all non-NULL storage pointers were filled with appropriate values,
 496  * FALSE otherwise.
 497  */
 498 gboolean
 499 gst_toc_entry_get_start_stop_times (const GstTocEntry * entry, gint64 * start,
 500     gint64 * stop)
 501 {
 502   gboolean ret = TRUE;
 503
 504   g_return_val_if_fail (entry != NULL, FALSE);
 505
 506   if (start != NULL)
 507     *start = entry->start;
 508   if (stop != NULL)
 509     *stop = entry->stop;
 510
 511   return ret;
 512 }
 513
 514 /**
 515  * gst_toc_entry_type_get_nick:
 516  * @type: a #GstTocEntryType.
 517  *
 518  * Converts @type to a string representation.
 519  *
 520  * Returns: Returns a human-readable string for @type. This string is
 521  *    only for debugging purpose and should not be displayed in a user
 522  *    interface.
 523  */
 524 const gchar *
 525 gst_toc_entry_type_get_nick (GstTocEntryType type)
 526 {
 527   switch (type) {
 528     case GST_TOC_ENTRY_TYPE_ANGLE:
 529       return "angle";
 530     case GST_TOC_ENTRY_TYPE_VERSION:
 531       return "version";
 532     case GST_TOC_ENTRY_TYPE_EDITION:
 533       return "edition";
 534     case GST_TOC_ENTRY_TYPE_TITLE:
 535       return "title";
 536     case GST_TOC_ENTRY_TYPE_TRACK:
 537       return "track";
 538     case GST_TOC_ENTRY_TYPE_CHAPTER:
 539       return "chapter";
 540     default:
 541       break;
 542   }
 543   return "invalid";
 544 }
 545
 546 /**
 547  * gst_toc_entry_get_entry_type:
 548  * @entry: a #GstTocEntry
 549  *
 550  * Returns: @entry's entry type
 551  */
 552 GstTocEntryType
 553 gst_toc_entry_get_entry_type (const GstTocEntry * entry)
 554 {
 555   g_return_val_if_fail (entry != NULL, GST_TOC_ENTRY_TYPE_INVALID);
 556
 557   return entry->type;
 558 }
 559
 560 /**
 561  * gst_toc_entry_is_alternative:
 562  * @entry: a #GstTocEntry
 563  *
 564  * Returns: %TRUE if @entry's type is an alternative type, otherwise %FALSE
 565  */
 566 gboolean
 567 gst_toc_entry_is_alternative (const GstTocEntry * entry)
 568 {
 569   g_return_val_if_fail (entry != NULL, FALSE);
 570
 571   return GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE (entry->type);
 572 }
 573
 574 /**
 575  * gst_toc_entry_is_sequence:
 576  * @entry: a #GstTocEntry
 577  *
 578  * Returns: %TRUE if @entry's type is a sequence type, otherwise %FALSE
 579  */
 580 gboolean
 581 gst_toc_entry_is_sequence (const GstTocEntry * entry)
 582 {
 583   g_return_val_if_fail (entry != NULL, FALSE);
 584
 585   return GST_TOC_ENTRY_TYPE_IS_SEQUENCE (entry->type);
 586 }
 587
 588 /**
 589  * gst_toc_entry_get_uid:
 590  * @entry: A #GstTocEntry instance
 591  *
 592  * Gets the UID of @entry.
 593  *
 594  * Returns: (transfer none): The UID of @entry
 595  */
 596 const gchar *
 597 gst_toc_entry_get_uid (const GstTocEntry * entry)
 598 {
 599   g_return_val_if_fail (entry != NULL, NULL);
 600
 601   return entry->uid;
 602 }
 603
 604 /**
 605  * gst_toc_entry_append_sub_entry:
 606  * @entry: A #GstTocEntry instance
 607  * @subentry: (transfer full): A #GstTocEntry
 608  *
 609  * Appends the #GstTocEntry @subentry to @entry.
 610  */
 611 void
 612 gst_toc_entry_append_sub_entry (GstTocEntry * entry, GstTocEntry * subentry)
 613 {
 614   g_return_if_fail (entry != NULL);
 615   g_return_if_fail (subentry != NULL);
 616   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 617   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST
 618           (subentry)));
 619   g_return_if_fail (subentry->toc == NULL);
 620   g_return_if_fail (subentry->parent == NULL);
 621
 622   entry->subentries = g_list_append (entry->subentries, subentry);
 623   subentry->toc = entry->toc;
 624   subentry->parent = entry;
 625
 626   GST_LOG ("appended %s subentry with uid %s to entry %s",
 627       gst_toc_entry_type_get_nick (subentry->type), subentry->uid, entry->uid);
 628 }
 629
 630 /**
 631  * gst_toc_entry_get_sub_entries:
 632  * @entry: A #GstTocEntry instance
 633  *
 634  * Gets the sub-entries of @entry.
 635  *
 636  * Returns: (transfer none) (element-type Gst.TocEntry): A #GList of #GstTocEntry of @entry
 637  */
 638 GList *
 639 gst_toc_entry_get_sub_entries (const GstTocEntry * entry)
 640 {
 641   g_return_val_if_fail (entry != NULL, NULL);
 642
 643   return entry->subentries;
 644 }
 645
 646 /**
 647  * gst_toc_entry_set_tags:
 648  * @entry: A #GstTocEntry instance
 649  * @tags: (allow-none) (transfer full): A #GstTagList or %NULL
 650  *
 651  * Set a #GstTagList with tags for the complete @entry.
 652  */
 653 void
 654 gst_toc_entry_set_tags (GstTocEntry * entry, GstTagList * tags)
 655 {
 656   g_return_if_fail (entry != NULL);
 657   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 658
 659   if (entry->tags)
 660     gst_tag_list_unref (entry->tags);
 661   entry->tags = tags;
 662 }
 663
 664 /**
 665  * gst_toc_entry_merge_tags:
 666  * @entry: A #GstTocEntry instance
 667  * @tags: (allow-none): A #GstTagList or %NULL
 668  * @mode: A #GstTagMergeMode
 669  *
 670  * Merge @tags into the existing tags of @entry using @mode.
 671  */
 672 void
 673 gst_toc_entry_merge_tags (GstTocEntry * entry, GstTagList * tags,
 674     GstTagMergeMode mode)
 675 {
 676   g_return_if_fail (entry != NULL);
 677   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 678
 679   if (!entry->tags) {
 680     entry->tags = gst_tag_list_ref (tags);
 681   } else {
 682     GstTagList *tmp = gst_tag_list_merge (entry->tags, tags, mode);
 683     gst_tag_list_unref (entry->tags);
 684     entry->tags = tmp;
 685   }
 686 }
 687
 688 /**
 689  * gst_toc_entry_get_tags:
 690  * @entry: A #GstTocEntry instance
 691  *
 692  * Gets the tags for @entry.
 693  *
 694  * Returns: (transfer none): A #GstTagList for @entry
 695  */
 696 GstTagList *
 697 gst_toc_entry_get_tags (const GstTocEntry * entry)
 698 {
 699   g_return_val_if_fail (entry != NULL, NULL);
 700
 701   return entry->tags;
 702 }
 703
 704 /**
 705  * gst_toc_entry_get_toc:
 706  * @entry: A #GstTocEntry instance
 707  *
 708  * Gets the parent #GstToc of @entry.
 709  *
 710  * Returns: (transfer none): The parent #GstToc of @entry
 711  */
 712 GstToc *
 713 gst_toc_entry_get_toc (GstTocEntry * entry)
 714 {
 715   g_return_val_if_fail (entry != NULL, NULL);
 716
 717   return entry->toc;
 718 }
 719
 720 /**
 721  * gst_toc_entry_get_parent:
 722  * @entry: A #GstTocEntry instance
 723  *
 724  * Gets the parent #GstTocEntry of @entry.
 725  *
 726  * Returns: (transfer none): The parent #GstTocEntry of @entry
 727  */
 728 GstTocEntry *
 729 gst_toc_entry_get_parent (GstTocEntry * entry)
 730 {
 731   g_return_val_if_fail (entry != NULL, NULL);
 732
 733   return entry->parent;
 734 }
 735
 736 #ifndef GST_DISABLE_GST_DEBUG
 737 static void
 738 gst_toc_dump_entries (GList * entries, guint depth)
 739 {
 740   GList *e;
 741   gchar *indent;
 742
 743   indent = g_malloc0 (depth + 1);
 744   memset (indent, ' ', depth);
 745   for (e = entries; e != NULL; e = e->next) {
 746     GstTocEntry *entry = e->data;
 747
 748     GST_TRACE ("%s+ %s (%s), %" GST_TIME_FORMAT " - %" GST_TIME_FORMAT ", "
 749         "tags: %" GST_PTR_FORMAT, indent, entry->uid,
 750         gst_toc_entry_type_get_nick (entry->type),
 751         GST_TIME_ARGS (entry->start), GST_TIME_ARGS (entry->stop), entry->tags);
 752
 753     if (entry->subentries != NULL)
 754       gst_toc_dump_entries (entry->subentries, depth + 2);
 755   }
 756   g_free (indent);
 757 }
 758 #endif
 759
 760 void
 761 gst_toc_dump (GstToc * toc)
 762 {
 763 #ifndef GST_DISABLE_GST_DEBUG
 764   GST_TRACE ("        Toc %p, scope: %s, tags: %" GST_PTR_FORMAT, toc,
 765       (toc->scope == GST_TOC_SCOPE_GLOBAL) ? "global" : "current", toc->tags);
 766   gst_toc_dump_entries (toc->entries, 2);
 767 #endif
 768 }