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