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., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, 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 #GstToc.entries #GstTocEntry.subentries
  39  * lists. You should use GST_TOC_ENTRY_TYPE_CHAPTER for generic TOC entry and
  40  * GST_TOC_ENTRY_TYPE_EDITION for the entries which are considered to be alternatives
  41  * (like DVD angles, Matroska editions and so on).
  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  * Please, use #GstToc.info and #GstTocEntry.info fields in that way: create a #GstStructure,
  49  * put all info related to your element there and put this structure into the info field under
  50  * the name of your element. Some fields in the info structure can be used for internal purposes,
  51  * so you should use it in the way described above to not to overwrite already existent fields.
  52  *
  53  * Use gst_event_new_toc() to create a new TOC #GstEvent, and gst_event_parse_toc() to
  54  * parse received TOC event. Use gst_event_new_toc_select() to create a new TOC select #GstEvent,
  55  * and gst_event_parse_toc_select() to parse received TOC select event. The same rule for
  56  * the #GstMessage: gst_message_new_toc() to create new TOC #GstMessage, and
  57  * gst_message_parse_toc() to parse received TOC message. Also you can create a new TOC query
  58  * with gst_query_new_toc(), set it with gst_query_set_toc() and parse it with
  59  * gst_query_parse_toc().
  60  */
  61
  62 #ifdef HAVE_CONFIG_H
  63 #  include "config.h"
  64 #endif
  65
  66 #include "gst_private.h"
  67 #include "gstenumtypes.h"
  68 #include "gsttaglist.h"
  69 #include "gststructure.h"
  70 #include "gstvalue.h"
  71 #include "gsttoc.h"
  72 #include "gstpad.h"
  73 #include "gstquark.h"
  74
  75 struct _GstTocEntry
  76 {
  77   GstMiniObject mini_object;
  78
  79   gchar *uid;
  80   GstTocEntryType type;
  81   GstClockTime start, stop;
  82   GList *subentries;
  83   GstTagList *tags;
  84 };
  85
  86 struct _GstToc
  87 {
  88   GstMiniObject mini_object;
  89
  90   GList *entries;
  91   GstTagList *tags;
  92 };
  93
  94 #undef gst_toc_copy
  95 static GstToc *gst_toc_copy (const GstToc * toc);
  96 static void gst_toc_free (GstToc * toc);
  97 #undef gst_toc_entry_copy
  98 static GstTocEntry *gst_toc_entry_copy (const GstTocEntry * toc);
  99 static void gst_toc_entry_free (GstTocEntry * toc);
 100
 101 GST_DEFINE_MINI_OBJECT_TYPE (GstToc, gst_toc);
 102 GST_DEFINE_MINI_OBJECT_TYPE (GstTocEntry, gst_toc_entry);
 103
 104 /**
 105  * gst_toc_new:
 106  *
 107  * Create a new #GstToc structure.
 108  *
 109  * Returns: (transfer full): newly allocated #GstToc structure, free it
 110  *     with gst_toc_unref().
 111  */
 112 GstToc *
 113 gst_toc_new (void)
 114 {
 115   GstToc *toc;
 116
 117   toc = g_slice_new0 (GstToc);
 118
 119   gst_mini_object_init (GST_MINI_OBJECT_CAST (toc), 0, GST_TYPE_TOC,
 120       (GstMiniObjectCopyFunction) gst_toc_copy, NULL,
 121       (GstMiniObjectFreeFunction) gst_toc_free);
 122
 123   toc->tags = gst_tag_list_new_empty ();
 124
 125   return toc;
 126 }
 127
 128 /**
 129  * gst_toc_set_tags:
 130  * @toc: A #GstToc instance
 131  * @tags: (allow-none) (transfer full): A #GstTagList or %NULL
 132  *
 133  * Set a #GstTagList with tags for the complete @toc.
 134  */
 135 void
 136 gst_toc_set_tags (GstToc * toc, GstTagList * tags)
 137 {
 138   g_return_if_fail (toc != NULL);
 139   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 140
 141   if (toc->tags)
 142     gst_tag_list_unref (toc->tags);
 143   toc->tags = tags;
 144 }
 145
 146 /**
 147  * gst_toc_merge_tags:
 148  * @toc: A #GstToc instance
 149  * @tags: (allow-none): A #GstTagList or %NULL
 150  * @mode: A #GstTagMergeMode
 151  *
 152  * Merge @tags into the existing tags of @toc using @mode.
 153  */
 154 void
 155 gst_toc_merge_tags (GstToc * toc, GstTagList * tags, GstTagMergeMode mode)
 156 {
 157   g_return_if_fail (toc != NULL);
 158   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 159
 160   if (!toc->tags) {
 161     toc->tags = gst_tag_list_ref (tags);
 162   } else {
 163     GstTagList *tmp = gst_tag_list_merge (toc->tags, tags, mode);
 164     gst_tag_list_unref (toc->tags);
 165     toc->tags = tmp;
 166   }
 167 }
 168
 169 /**
 170  * gst_toc_get_tags:
 171  * @toc: A #GstToc instance
 172  *
 173  * Gets the tags for @toc.
 174  *
 175  * Returns: (transfer none): A #GstTagList for @entry
 176  */
 177 GstTagList *
 178 gst_toc_get_tags (const GstToc * toc)
 179 {
 180   g_return_val_if_fail (toc != NULL, NULL);
 181
 182   return toc->tags;
 183 }
 184
 185 /**
 186  * gst_toc_append_entry:
 187  * @toc: A #GstToc instance
 188  * @entry: (transfer full): A #GstTocEntry
 189  *
 190  * Appends the #GstTocEntry @entry to @toc.
 191  */
 192 void
 193 gst_toc_append_entry (GstToc * toc, GstTocEntry * entry)
 194 {
 195   g_return_if_fail (toc != NULL);
 196   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (toc)));
 197
 198   toc->entries = g_list_append (toc->entries, entry);
 199
 200   GST_LOG ("appended %s entry with uid %s to toc %p",
 201       gst_toc_entry_type_get_nick (entry->type), entry->uid, toc);
 202
 203   gst_toc_dump (toc);
 204 }
 205
 206 /**
 207  * gst_toc_get_entries:
 208  * @toc: A #GstToc instance
 209  *
 210  * Gets the list of #GstTocEntry of @toc.
 211  *
 212  * Returns: (transfer none) (element-type Gst.TocEntry): A #GList of #GstTocEntry for @entry
 213  */
 214 GList *
 215 gst_toc_get_entries (const GstToc * toc)
 216 {
 217   g_return_val_if_fail (toc != NULL, NULL);
 218
 219   return toc->entries;
 220 }
 221
 222 static GstTocEntry *
 223 gst_toc_entry_new_internal (GstTocEntryType type, const gchar * uid)
 224 {
 225   GstTocEntry *entry;
 226
 227   entry = g_slice_new0 (GstTocEntry);
 228
 229   gst_mini_object_init (GST_MINI_OBJECT_CAST (entry), 0, GST_TYPE_TOC_ENTRY,
 230       (GstMiniObjectCopyFunction) gst_toc_entry_copy, NULL,
 231       (GstMiniObjectFreeFunction) gst_toc_entry_free);
 232
 233   entry->uid = g_strdup (uid);
 234   entry->type = type;
 235   entry->tags = NULL;
 236   entry->start = entry->stop = GST_CLOCK_TIME_NONE;
 237
 238   return entry;
 239 }
 240
 241 /**
 242  * gst_toc_entry_new:
 243  * @type: entry type.
 244  * @uid: unique ID (UID) in the whole TOC.
 245  *
 246  * Create new #GstTocEntry structure.
 247  *
 248  * Returns: newly allocated #GstTocEntry structure, free it with gst_toc_entry_unref().
 249  */
 250 GstTocEntry *
 251 gst_toc_entry_new (GstTocEntryType type, const gchar * uid)
 252 {
 253   g_return_val_if_fail (uid != NULL, NULL);
 254
 255   return gst_toc_entry_new_internal (type, uid);
 256 }
 257
 258 static void
 259 gst_toc_free (GstToc * toc)
 260 {
 261   g_list_foreach (toc->entries, (GFunc) gst_mini_object_unref, NULL);
 262   g_list_free (toc->entries);
 263
 264   if (toc->tags != NULL)
 265     gst_tag_list_unref (toc->tags);
 266
 267   g_slice_free (GstToc, toc);
 268 }
 269
 270 static void
 271 gst_toc_entry_free (GstTocEntry * entry)
 272 {
 273   g_return_if_fail (entry != NULL);
 274
 275   g_list_foreach (entry->subentries, (GFunc) gst_mini_object_unref, NULL);
 276   g_list_free (entry->subentries);
 277
 278   g_free (entry->uid);
 279
 280   if (entry->tags != NULL)
 281     gst_tag_list_unref (entry->tags);
 282
 283   g_slice_free (GstTocEntry, entry);
 284 }
 285
 286 static gboolean
 287 gst_toc_check_entry_for_uid (const GstTocEntry * entry, const gchar * uid)
 288 {
 289   GList *cur;
 290
 291   g_return_val_if_fail (entry != NULL, FALSE);
 292   g_return_val_if_fail (uid != NULL, FALSE);
 293
 294   if (g_strcmp0 (entry->uid, uid) == 0)
 295     return TRUE;
 296
 297   cur = entry->subentries;
 298   while (cur != NULL) {
 299     if (gst_toc_check_entry_for_uid (cur->data, uid))
 300       return TRUE;
 301     cur = cur->next;
 302   }
 303
 304   return FALSE;
 305 }
 306
 307 /**
 308  * gst_toc_find_entry:
 309  * @toc: #GstToc to search in.
 310  * @uid: UID to find #GstTocEntry with.
 311  *
 312  * Find #GstTocEntry with given @uid in the @toc.
 313  *
 314  * Returns: #GstTocEntry with specified @uid from the @toc, or NULL if not found.
 315  */
 316 GstTocEntry *
 317 gst_toc_find_entry (const GstToc * toc, const gchar * uid)
 318 {
 319   GList *cur;
 320
 321   g_return_val_if_fail (toc != NULL, NULL);
 322   g_return_val_if_fail (uid != NULL, NULL);
 323
 324   cur = toc->entries;
 325   while (cur != NULL) {
 326     if (gst_toc_check_entry_for_uid (cur->data, uid))
 327       return cur->data;
 328     cur = cur->next;
 329   }
 330
 331   return NULL;
 332 }
 333
 334 /**
 335  * gst_toc_entry_copy:
 336  * @entry: #GstTocEntry to copy.
 337  *
 338  * Copy #GstTocEntry with all subentries (deep copy).
 339  *
 340  * Returns: newly allocated #GstTocEntry in case of success, NULL otherwise;
 341  * free it when done with gst_toc_entry_unref().
 342  */
 343 static GstTocEntry *
 344 gst_toc_entry_copy (const GstTocEntry * entry)
 345 {
 346   GstTocEntry *ret, *sub;
 347   GstTagList *list;
 348   GList *cur;
 349
 350   g_return_val_if_fail (entry != NULL, NULL);
 351
 352   ret = gst_toc_entry_new (entry->type, entry->uid);
 353
 354   ret->start = entry->start;
 355   ret->stop = entry->stop;
 356
 357   if (GST_IS_TAG_LIST (entry->tags)) {
 358     list = gst_tag_list_copy (entry->tags);
 359     if (ret->tags)
 360       gst_tag_list_unref (ret->tags);
 361     ret->tags = list;
 362   }
 363
 364   cur = entry->subentries;
 365   while (cur != NULL) {
 366     sub = gst_toc_entry_copy (cur->data);
 367
 368     if (sub != NULL)
 369       ret->subentries = g_list_prepend (ret->subentries, sub);
 370
 371     cur = cur->next;
 372   }
 373   ret->subentries = g_list_reverse (ret->subentries);
 374
 375   return ret;
 376 }
 377
 378 /**
 379  * gst_toc_copy:
 380  * @toc: #GstToc to copy.
 381  *
 382  * Copy #GstToc with all subentries (deep copy).
 383  *
 384  * Returns: newly allocated #GstToc in case of success, NULL otherwise;
 385  * free it when done with gst_toc_free().
 386  */
 387 static GstToc *
 388 gst_toc_copy (const GstToc * toc)
 389 {
 390   GstToc *ret;
 391   GstTocEntry *entry;
 392   GList *cur;
 393   GstTagList *list;
 394
 395   g_return_val_if_fail (toc != NULL, NULL);
 396
 397   ret = gst_toc_new ();
 398
 399   if (GST_IS_TAG_LIST (toc->tags)) {
 400     list = gst_tag_list_copy (toc->tags);
 401     gst_tag_list_unref (ret->tags);
 402     ret->tags = list;
 403   }
 404
 405   cur = toc->entries;
 406   while (cur != NULL) {
 407     entry = gst_toc_entry_copy (cur->data);
 408
 409     if (entry != NULL)
 410       ret->entries = g_list_prepend (ret->entries, entry);
 411
 412     cur = cur->next;
 413   }
 414   ret->entries = g_list_reverse (ret->entries);
 415
 416   return ret;
 417 }
 418
 419 /**
 420  * gst_toc_entry_set_start_stop_times:
 421  * @entry: #GstTocEntry to set values.
 422  * @start: start value to set.
 423  * @stop: stop value to set.
 424  *
 425  * Set @start and @stop values for the @entry.
 426  */
 427 void
 428 gst_toc_entry_set_start_stop_times (GstTocEntry * entry, gint64 start,
 429     gint64 stop)
 430 {
 431   g_return_if_fail (entry != NULL);
 432
 433   entry->start = start;
 434   entry->stop = stop;
 435 }
 436
 437 /**
 438  * gst_toc_entry_get_start_stop_times:
 439  * @entry: #GstTocEntry to get values from.
 440  * @start: (out): the storage for the start value, leave #NULL if not need.
 441  * @stop: (out): the storage for the stop value, leave #NULL if not need.
 442  *
 443  * Get start and stop values from the @entry and write them into appropriate storages.
 444  *
 445  * Returns: TRUE if all non-NULL storage pointers were filled with appropriate values,
 446  * FALSE otherwise.
 447  */
 448 gboolean
 449 gst_toc_entry_get_start_stop_times (const GstTocEntry * entry, gint64 * start,
 450     gint64 * stop)
 451 {
 452   gboolean ret = TRUE;
 453
 454   g_return_val_if_fail (entry != NULL, FALSE);
 455
 456   if (start != NULL)
 457     *start = entry->start;
 458   if (stop != NULL)
 459     *stop = entry->stop;
 460
 461   return ret;
 462 }
 463
 464 /**
 465  * gst_toc_entry_type_get_nick:
 466  * @type: a #GstTocEntryType.
 467  *
 468  * Converts @type to a string representation.
 469  *
 470  * Returns: Returns a human-readable string for @type. This string is
 471  *    only for debugging purpose and should not be displayed in a user
 472  *    interface.
 473  */
 474 const gchar *
 475 gst_toc_entry_type_get_nick (GstTocEntryType type)
 476 {
 477   switch (type) {
 478     case GST_TOC_ENTRY_TYPE_ANGLE:
 479       return "angle";
 480     case GST_TOC_ENTRY_TYPE_VERSION:
 481       return "version";
 482     case GST_TOC_ENTRY_TYPE_EDITION:
 483       return "edition";
 484     case GST_TOC_ENTRY_TYPE_TITLE:
 485       return "title";
 486     case GST_TOC_ENTRY_TYPE_TRACK:
 487       return "track";
 488     case GST_TOC_ENTRY_TYPE_CHAPTER:
 489       return "chapter";
 490     default:
 491       break;
 492   }
 493   return "invalid";
 494 }
 495
 496 /**
 497  * gst_toc_entry_get_entry_type:
 498  * @entry: a #GstTocEntry
 499  *
 500  * Returns: @entry's entry type
 501  */
 502 GstTocEntryType
 503 gst_toc_entry_get_entry_type (const GstTocEntry * entry)
 504 {
 505   g_return_val_if_fail (entry != NULL, GST_TOC_ENTRY_TYPE_INVALID);
 506
 507   return entry->type;
 508 }
 509
 510 /**
 511  * gst_toc_entry_is_alternative:
 512  * @entry: a #GstTocEntry
 513  *
 514  * Returns: %TRUE if @entry's type is an alternative type, otherwise %FALSE
 515  */
 516 gboolean
 517 gst_toc_entry_is_alternative (const GstTocEntry * entry)
 518 {
 519   g_return_val_if_fail (entry != NULL, FALSE);
 520
 521   return GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE (entry->type);
 522 }
 523
 524 /**
 525  * gst_toc_entry_is_sequence:
 526  * @entry: a #GstTocEntry
 527  *
 528  * Returns: %TRUE if @entry's type is a sequence type, otherwise %FALSE
 529  */
 530 gboolean
 531 gst_toc_entry_is_sequence (const GstTocEntry * entry)
 532 {
 533   g_return_val_if_fail (entry != NULL, FALSE);
 534
 535   return GST_TOC_ENTRY_TYPE_IS_SEQUENCE (entry->type);
 536 }
 537
 538 /**
 539  * gst_toc_entry_get_uid:
 540  * @entry: A #GstTocEntry instance
 541  *
 542  * Gets the UID of @entry.
 543  *
 544  * Returns: (transfer none): The UID of @entry
 545  */
 546 const gchar *
 547 gst_toc_entry_get_uid (const GstTocEntry * entry)
 548 {
 549   g_return_val_if_fail (entry != NULL, NULL);
 550
 551   return entry->uid;
 552 }
 553
 554 /**
 555  * gst_toc_entry_append_sub_entry:
 556  * @entry: A #GstTocEntry instance
 557  * @subentry: (transfer full): A #GstTocEntry
 558  *
 559  * Appends the #GstTocEntry @subentry to @entry.
 560  */
 561 void
 562 gst_toc_entry_append_sub_entry (GstTocEntry * entry, GstTocEntry * subentry)
 563 {
 564   g_return_if_fail (entry != NULL);
 565   g_return_if_fail (subentry != NULL);
 566   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 567
 568   entry->subentries = g_list_append (entry->subentries, subentry);
 569
 570   GST_LOG ("appended %s subentry with uid %s to entry %s",
 571       gst_toc_entry_type_get_nick (subentry->type), subentry->uid, entry->uid);
 572 }
 573
 574 /**
 575  * gst_toc_entry_get_uid:
 576  * @entry: A #GstTocEntry instance
 577  *
 578  * Gets the sub-entries of @entry.
 579  *
 580  * Returns: (transfer none) (element-type Gst.TocEntry): A #GList of #GstTocEntry of @entry
 581  */
 582 GList *
 583 gst_toc_entry_get_sub_entries (const GstTocEntry * entry)
 584 {
 585   g_return_val_if_fail (entry != NULL, NULL);
 586
 587   return entry->subentries;
 588 }
 589
 590 /**
 591  * gst_toc_entry_set_tags:
 592  * @entry: A #GstTocEntry instance
 593  * @tags: (allow-none) (transfer full): A #GstTagList or %NULL
 594  *
 595  * Set a #GstTagList with tags for the complete @entry.
 596  */
 597 void
 598 gst_toc_entry_set_tags (GstTocEntry * entry, GstTagList * tags)
 599 {
 600   g_return_if_fail (entry != NULL);
 601   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 602
 603   if (entry->tags)
 604     gst_tag_list_unref (entry->tags);
 605   entry->tags = tags;
 606 }
 607
 608 /**
 609  * gst_toc_entry_merge_tags:
 610  * @entry: A #GstTocEntry instance
 611  * @tags: (allow-none): A #GstTagList or %NULL
 612  * @mode: A #GstTagMergeMode
 613  *
 614  * Merge @tags into the existing tags of @entry using @mode.
 615  */
 616 void
 617 gst_toc_entry_merge_tags (GstTocEntry * entry, GstTagList * tags,
 618     GstTagMergeMode mode)
 619 {
 620   g_return_if_fail (entry != NULL);
 621   g_return_if_fail (gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (entry)));
 622
 623   if (!entry->tags) {
 624     entry->tags = gst_tag_list_ref (tags);
 625   } else {
 626     GstTagList *tmp = gst_tag_list_merge (entry->tags, tags, mode);
 627     gst_tag_list_unref (entry->tags);
 628     entry->tags = tmp;
 629   }
 630 }
 631
 632 /**
 633  * gst_toc_entry_get_tags:
 634  * @entry: A #GstTocEntry instance
 635  *
 636  * Gets the tags for @entry.
 637  *
 638  * Returns: (transfer none): A #GstTagList for @entry
 639  */
 640 GstTagList *
 641 gst_toc_entry_get_tags (const GstTocEntry * entry)
 642 {
 643   g_return_val_if_fail (entry != NULL, NULL);
 644
 645   return entry->tags;
 646 }
 647
 648 #ifndef GST_DISABLE_GST_DEBUG
 649 static void
 650 gst_toc_dump_entries (GList * entries, guint depth)
 651 {
 652   GList *e;
 653   gchar *indent;
 654
 655   indent = g_malloc0 (depth + 1);
 656   memset (indent, ' ', depth);
 657   for (e = entries; e != NULL; e = e->next) {
 658     GstTocEntry *entry = e->data;
 659
 660     GST_TRACE ("%s+ %s (%s), %" GST_TIME_FORMAT " - %" GST_TIME_FORMAT ", "
 661         "tags: %" GST_PTR_FORMAT, indent, entry->uid,
 662         gst_toc_entry_type_get_nick (entry->type),
 663         GST_TIME_ARGS (entry->start), GST_TIME_ARGS (entry->stop), entry->tags);
 664
 665     if (entry->subentries != NULL)
 666       gst_toc_dump_entries (entry->subentries, depth + 2);
 667   }
 668   g_free (indent);
 669 }
 670 #endif
 671
 672 void
 673 gst_toc_dump (GstToc * toc)
 674 {
 675 #ifndef GST_DISABLE_GST_DEBUG
 676   GST_TRACE ("        Toc %p, tags: %" GST_PTR_FORMAT, toc, toc->tags);
 677   gst_toc_dump_entries (toc->entries, 2);
 678 #endif
 679 }