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