Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / libs / gst / base / gsttypefindhelper.c
1 /* GStreamer
2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3  * Copyright (C) 2000,2005 Wim Taymans <wim@fluendo.com>
4  * Copyright (C) 2006      Tim-Philipp Müller <tim centricular net>
5  *
6  * gsttypefindhelper.c:
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Library General Public
10  * License as published by the Free Software Foundation; either
11  * version 2 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * Library General Public License for more details.
17  *
18  * You should have received a copy of the GNU Library General Public
19  * License along with this library; if not, write to the
20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21  * Boston, MA 02111-1307, USA.
22  */
23
24 /**
25  * SECTION:gsttypefindhelper
26  * @short_description: Utility functions for typefinding 
27  *
28  * Utility functions for elements doing typefinding:
29  * gst_type_find_helper() does typefinding in pull mode, while
30  * gst_type_find_helper_for_buffer() is useful for elements needing to do
31  * typefinding in push mode from a chain function.
32  */
33
34 #ifdef HAVE_CONFIG_H
35 #  include "config.h"
36 #endif
37
38 #include <stdlib.h>
39 #include <string.h>
40
41 #include "gsttypefindhelper.h"
42
43 /* ********************** typefinding in pull mode ************************ */
44
45 static void
46 helper_find_suggest (gpointer data, guint probability, const GstCaps * caps);
47
48 typedef struct
49 {
50   GSList *buffers;              /* buffer cache */
51   guint64 size;
52   guint64 last_offset;
53   GstTypeFindHelperGetRangeFunction func;
54   GstTypeFindProbability best_probability;
55   GstCaps *caps;
56   GstTypeFindFactory *factory;  /* for logging */
57   GstObject *obj;               /* for logging */
58 } GstTypeFindHelper;
59
60 /*
61  * helper_find_peek:
62  * @data: helper data struct
63  * @off: stream offset
64  * @size: block size
65  *
66  * Get data pointer within a stream. Keeps a cache of read buffers (partly
67  * for performance reasons, but mostly because pointers returned by us need
68  * to stay valid until typefinding has finished)
69  *
70  * Returns: address of the data or %NULL if buffer does not cover the
71  * requested range.
72  */
73 static const guint8 *
74 helper_find_peek (gpointer data, gint64 offset, guint size)
75 {
76   GstTypeFindHelper *helper;
77   GstBuffer *buffer;
78   GstFlowReturn ret;
79   GSList *insert_pos = NULL;
80   gsize buf_size;
81   guint64 buf_offset;
82 #if 0
83   GstCaps *caps;
84 #endif
85
86   helper = (GstTypeFindHelper *) data;
87
88   GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT
89       ", %u)", GST_OBJECT_NAME (helper->factory), offset, size);
90
91   if (size == 0)
92     return NULL;
93
94   if (offset < 0) {
95     if (helper->size == -1 || helper->size < -offset)
96       return NULL;
97
98     offset += helper->size;
99   }
100
101   /* see if we have a matching buffer already in our list */
102   if (size > 0 && offset <= helper->last_offset) {
103     GSList *walk;
104
105     for (walk = helper->buffers; walk; walk = walk->next) {
106       GstBuffer *buf = GST_BUFFER_CAST (walk->data);
107       guint64 buf_offset = GST_BUFFER_OFFSET (buf);
108       guint buf_size = gst_buffer_get_size (buf);
109
110       /* buffers are kept sorted by end offset (highest first) in the list, so
111        * at this point we save the current position and stop searching if 
112        * we're after the searched end offset */
113       if (buf_offset <= offset) {
114         if ((offset + size) < (buf_offset + buf_size)) {
115           guint8 *data;
116
117           /* FIXME, unmap after usage */
118           data = gst_buffer_map (buf, NULL, NULL, GST_MAP_READ);
119
120           return data + (offset - buf_offset);
121         }
122       } else if (offset + size >= buf_offset + buf_size) {
123         insert_pos = walk;
124         break;
125       }
126     }
127   }
128
129   buffer = NULL;
130   /* some typefinders go in 1 byte steps over 1k of data and request
131    * small buffers. It is really inefficient to pull each time, and pulling
132    * a larger chunk is almost free. Trying to pull a larger chunk at the end
133    * of the file is also not a problem here, we'll just get a truncated buffer
134    * in that case (and we'll have to double-check the size we actually get
135    * anyway, see below) */
136   ret = helper->func (helper->obj, offset, MAX (size, 4096), &buffer);
137
138   if (ret != GST_FLOW_OK)
139     goto error;
140
141 #if 0
142   caps = GST_BUFFER_CAPS (buffer);
143
144   if (caps && !gst_caps_is_empty (caps) && !gst_caps_is_any (caps)) {
145     GST_DEBUG ("buffer has caps %" GST_PTR_FORMAT ", suggest max probability",
146         caps);
147
148     gst_caps_replace (&helper->caps, caps);
149     helper->best_probability = GST_TYPE_FIND_MAXIMUM;
150
151     gst_buffer_unref (buffer);
152     return NULL;
153   }
154 #endif
155
156   /* getrange might silently return shortened buffers at the end of a file,
157    * we must, however, always return either the full requested data or NULL */
158   buf_offset = GST_BUFFER_OFFSET (buffer);
159   buf_size = gst_buffer_get_size (buffer);
160
161   if ((buf_offset != -1 && buf_offset != offset) || buf_size < size) {
162     GST_DEBUG ("dropping short buffer: %" G_GUINT64_FORMAT "-%" G_GUINT64_FORMAT
163         " instead of %" G_GUINT64_FORMAT "-%" G_GUINT64_FORMAT,
164         buf_offset, buf_offset + buf_size - 1, offset, offset + size - 1);
165     gst_buffer_unref (buffer);
166     return NULL;
167   }
168
169   if (insert_pos) {
170     helper->buffers =
171         g_slist_insert_before (helper->buffers, insert_pos, buffer);
172   } else {
173     /* if insert_pos is not set, our offset is bigger than the largest offset
174      * we have so far; since we keep the list sorted with highest offsets
175      * first, we need to prepend the buffer to the list */
176     helper->last_offset = GST_BUFFER_OFFSET (buffer) + buf_size;
177     helper->buffers = g_slist_prepend (helper->buffers, buffer);
178   }
179
180   /* FIXME, unmap */
181   return gst_buffer_map (buffer, NULL, NULL, GST_MAP_READ);
182
183 error:
184   {
185     GST_INFO ("typefind function returned: %s", gst_flow_get_name (ret));
186     return NULL;
187   }
188 }
189
190 /*
191  * helper_find_suggest:
192  * @data: helper data struct
193  * @probability: probability of the match
194  * @caps: caps of the type
195  *
196  * If given @probability is higher, replace previously store caps.
197  */
198 static void
199 helper_find_suggest (gpointer data, GstTypeFindProbability probability,
200     const GstCaps * caps)
201 {
202   GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
203
204   GST_LOG_OBJECT (helper->obj,
205       "'%s' called suggest (%u, %" GST_PTR_FORMAT ")",
206       GST_OBJECT_NAME (helper->factory), probability, caps);
207
208   if (probability > helper->best_probability) {
209     GstCaps *copy = gst_caps_copy (caps);
210
211     gst_caps_replace (&helper->caps, copy);
212     gst_caps_unref (copy);
213     helper->best_probability = probability;
214   }
215 }
216
217 static guint64
218 helper_find_get_length (gpointer data)
219 {
220   GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
221
222   GST_LOG_OBJECT (helper->obj, "'%s' called get_length, returning %"
223       G_GUINT64_FORMAT, GST_OBJECT_NAME (helper->factory), helper->size);
224
225   return helper->size;
226 }
227
228 /**
229  * gst_type_find_helper_get_range_ext:
230  * @obj: A #GstObject that will be passed as first argument to @func
231  * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
232  *        be used to access data at random offsets when doing the typefinding
233  * @size: The length in bytes
234  * @extension: extension of the media
235  * @prob: (out) (allow-none): location to store the probability of the found
236  *     caps, or #NULL
237  *
238  * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
239  * however, this function will use the specified function @func to obtain the
240  * data needed by the typefind functions, rather than operating on a given
241  * source pad. This is useful mostly for elements like tag demuxers which
242  * strip off data at the beginning and/or end of a file and want to typefind
243  * the stripped data stream before adding their own source pad (the specified
244  * callback can then call the upstream peer pad with offsets adjusted for the
245  * tag size, for example).
246  *
247  * When @extension is not NULL, this function will first try the typefind
248  * functions for the given extension, which might speed up the typefinding
249  * in many cases.
250  *
251  * Free-function: gst_caps_unref
252  *
253  * Returns: (transfer full): the #GstCaps corresponding to the data stream.
254  *     Returns #NULL if no #GstCaps matches the data stream.
255  *
256  * Since: 0.10.26
257  */
258 GstCaps *
259 gst_type_find_helper_get_range_ext (GstObject * obj,
260     GstTypeFindHelperGetRangeFunction func, guint64 size,
261     const gchar * extension, GstTypeFindProbability * prob)
262 {
263   GstTypeFindHelper helper;
264   GstTypeFind find;
265   GSList *walk;
266   GList *l, *type_list;
267   GstCaps *result = NULL;
268   gint pos = 0;
269
270   g_return_val_if_fail (GST_IS_OBJECT (obj), NULL);
271   g_return_val_if_fail (func != NULL, NULL);
272
273   helper.buffers = NULL;
274   helper.size = size;
275   helper.last_offset = 0;
276   helper.func = func;
277   helper.best_probability = GST_TYPE_FIND_NONE;
278   helper.caps = NULL;
279   helper.obj = obj;
280
281   find.data = &helper;
282   find.peek = helper_find_peek;
283   find.suggest = helper_find_suggest;
284
285   if (size == 0 || size == (guint64) - 1) {
286     find.get_length = NULL;
287   } else {
288     find.get_length = helper_find_get_length;
289   }
290
291   type_list = gst_type_find_factory_get_list ();
292
293   /* move the typefinders for the extension first in the list. The idea is that
294    * when one of them returns MAX we don't need to search further as there is a
295    * very high chance we got the right type. */
296   if (extension) {
297     GList *next;
298
299     GST_LOG_OBJECT (obj, "sorting typefind for extension %s to head",
300         extension);
301
302     for (l = type_list; l; l = next) {
303       GstTypeFindFactory *factory;
304       gint i;
305       gchar **ext;
306
307       next = l->next;
308
309       factory = GST_TYPE_FIND_FACTORY (l->data);
310
311       ext = gst_type_find_factory_get_extensions (factory);
312       if (ext == NULL)
313         continue;
314
315       GST_LOG_OBJECT (obj, "testing factory %s for extension %s",
316           GST_OBJECT_NAME (factory), extension);
317
318       for (i = 0; ext[i]; i++) {
319         if (strcmp (ext[i], extension) == 0) {
320           /* found extension, move in front */
321           GST_LOG_OBJECT (obj, "moving typefind for extension %s to head",
322               extension);
323           /* remove entry from list */
324           type_list = g_list_delete_link (type_list, l);
325           /* insert at the position */
326           type_list = g_list_insert (type_list, factory, pos);
327           /* next element will be inserted after this one */
328           pos++;
329           break;
330         }
331       }
332     }
333   }
334
335   for (l = type_list; l; l = l->next) {
336     helper.factory = GST_TYPE_FIND_FACTORY (l->data);
337     gst_type_find_factory_call_function (helper.factory, &find);
338     if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
339       break;
340   }
341   gst_plugin_feature_list_free (type_list);
342
343   for (walk = helper.buffers; walk; walk = walk->next)
344     gst_buffer_unref (GST_BUFFER_CAST (walk->data));
345   g_slist_free (helper.buffers);
346
347   if (helper.best_probability > 0)
348     result = helper.caps;
349
350   if (prob)
351     *prob = helper.best_probability;
352
353   GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
354       result, (guint) helper.best_probability);
355
356   return result;
357 }
358
359 /**
360  * gst_type_find_helper_get_range:
361  * @obj: A #GstObject that will be passed as first argument to @func
362  * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
363  *        be used to access data at random offsets when doing the typefinding
364  * @size: The length in bytes
365  * @prob: (out) (allow-none): location to store the probability of the found
366  *     caps, or #NULL
367  *
368  * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
369  * however, this function will use the specified function @func to obtain the
370  * data needed by the typefind functions, rather than operating on a given
371  * source pad. This is useful mostly for elements like tag demuxers which
372  * strip off data at the beginning and/or end of a file and want to typefind
373  * the stripped data stream before adding their own source pad (the specified
374  * callback can then call the upstream peer pad with offsets adjusted for the
375  * tag size, for example).
376  *
377  * Free-function: gst_caps_unref
378  *
379  * Returns: (transfer full): the #GstCaps corresponding to the data stream.
380  *     Returns #NULL if no #GstCaps matches the data stream.
381  */
382 GstCaps *
383 gst_type_find_helper_get_range (GstObject * obj,
384     GstTypeFindHelperGetRangeFunction func, guint64 size,
385     GstTypeFindProbability * prob)
386 {
387   return gst_type_find_helper_get_range_ext (obj, func, size, NULL, prob);
388 }
389
390 /**
391  * gst_type_find_helper:
392  * @src: A source #GstPad
393  * @size: The length in bytes
394  *
395  * Tries to find what type of data is flowing from the given source #GstPad.
396  *
397  * Free-function: gst_caps_unref
398  *
399  * Returns: (transfer full): the #GstCaps corresponding to the data stream.
400  *     Returns #NULL if no #GstCaps matches the data stream.
401  */
402
403 GstCaps *
404 gst_type_find_helper (GstPad * src, guint64 size)
405 {
406   GstTypeFindHelperGetRangeFunction func;
407
408   g_return_val_if_fail (GST_IS_OBJECT (src), NULL);
409   g_return_val_if_fail (GST_PAD_GETRANGEFUNC (src) != NULL, NULL);
410
411   func = (GstTypeFindHelperGetRangeFunction) (GST_PAD_GETRANGEFUNC (src));
412
413   return gst_type_find_helper_get_range (GST_OBJECT (src), func, size, NULL);
414 }
415
416 /* ********************** typefinding for buffers ************************* */
417
418 typedef struct
419 {
420   const guint8 *data;           /* buffer data */
421   gsize size;
422   GstTypeFindProbability best_probability;
423   GstCaps *caps;
424   GstTypeFindFactory *factory;  /* for logging */
425   GstObject *obj;               /* for logging */
426 } GstTypeFindBufHelper;
427
428 /*
429  * buf_helper_find_peek:
430  * @data: helper data struct
431  * @off: stream offset
432  * @size: block size
433  *
434  * Get data pointer within a buffer.
435  *
436  * Returns: address inside the buffer or %NULL if buffer does not cover the
437  * requested range.
438  */
439 static const guint8 *
440 buf_helper_find_peek (gpointer data, gint64 off, guint size)
441 {
442   GstTypeFindBufHelper *helper;
443
444   helper = (GstTypeFindBufHelper *) data;
445   GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT ", %u)",
446       GST_OBJECT_NAME (helper->factory), off, size);
447
448   if (size == 0)
449     return NULL;
450
451   if (off < 0) {
452     GST_LOG_OBJECT (helper->obj, "'%s' wanted to peek at end; not supported",
453         GST_OBJECT_NAME (helper->factory));
454     return NULL;
455   }
456
457   if ((off + size) <= helper->size)
458     return helper->data + off;
459
460   return NULL;
461 }
462
463 /*
464  * buf_helper_find_suggest:
465  * @data: helper data struct
466  * @probability: probability of the match
467  * @caps: caps of the type
468  *
469  * If given @probability is higher, replace previously store caps.
470  */
471 static void
472 buf_helper_find_suggest (gpointer data, GstTypeFindProbability probability,
473     const GstCaps * caps)
474 {
475   GstTypeFindBufHelper *helper = (GstTypeFindBufHelper *) data;
476
477   GST_LOG_OBJECT (helper->obj,
478       "'%s' called suggest (%u, %" GST_PTR_FORMAT ")",
479       GST_OBJECT_NAME (helper->factory), probability, caps);
480
481   /* Note: not >= as we call typefinders in order of rank, highest first */
482   if (probability > helper->best_probability) {
483     GstCaps *copy = gst_caps_copy (caps);
484
485     gst_caps_replace (&helper->caps, copy);
486     gst_caps_unref (copy);
487     helper->best_probability = probability;
488   }
489 }
490
491 /**
492  * gst_type_find_helper_for_data:
493  * @obj: object doing the typefinding, or NULL (used for logging)
494  * @data: (in) (transfer none): a pointer with data to typefind
495  * @size: (in) (transfer none): the size of @data
496  * @prob: (out) (allow-none): location to store the probability of the found
497  *     caps, or #NULL
498  *
499  * Tries to find what type of data is contained in the given @data, the
500  * assumption being that the data represents the beginning of the stream or
501  * file.
502  *
503  * All available typefinders will be called on the data in order of rank. If
504  * a typefinding function returns a probability of #GST_TYPE_FIND_MAXIMUM,
505  * typefinding is stopped immediately and the found caps will be returned
506  * right away. Otherwise, all available typefind functions will the tried,
507  * and the caps with the highest probability will be returned, or #NULL if
508  * the content of @data could not be identified.
509  *
510  * Free-function: gst_caps_unref
511  *
512  * Returns: (transfer full): the #GstCaps corresponding to the data, or #NULL
513  *     if no type could be found. The caller should free the caps returned
514  *     with gst_caps_unref().
515  */
516 GstCaps *
517 gst_type_find_helper_for_data (GstObject * obj, const guint8 * data, gsize size,
518     GstTypeFindProbability * prob)
519 {
520   GstTypeFindBufHelper helper;
521   GstTypeFind find;
522   GList *l, *type_list;
523   GstCaps *result = NULL;
524
525   g_return_val_if_fail (data != NULL, NULL);
526
527   helper.data = data;
528   helper.size = size;
529   helper.best_probability = GST_TYPE_FIND_NONE;
530   helper.caps = NULL;
531   helper.obj = obj;
532
533   if (helper.data == NULL || helper.size == 0)
534     return NULL;
535
536   find.data = &helper;
537   find.peek = buf_helper_find_peek;
538   find.suggest = buf_helper_find_suggest;
539   find.get_length = NULL;
540
541   type_list = gst_type_find_factory_get_list ();
542
543   for (l = type_list; l; l = l->next) {
544     helper.factory = GST_TYPE_FIND_FACTORY (l->data);
545     gst_type_find_factory_call_function (helper.factory, &find);
546     if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
547       break;
548   }
549   gst_plugin_feature_list_free (type_list);
550
551   if (helper.best_probability > 0)
552     result = helper.caps;
553
554   if (prob)
555     *prob = helper.best_probability;
556
557   GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
558       result, (guint) helper.best_probability);
559
560   return result;
561 }
562
563 /**
564  * gst_type_find_helper_for_buffer:
565  * @obj: object doing the typefinding, or NULL (used for logging)
566  * @buf: (in) (transfer none): a #GstBuffer with data to typefind
567  * @prob: (out) (allow-none): location to store the probability of the found
568  *     caps, or #NULL
569  *
570  * Tries to find what type of data is contained in the given #GstBuffer, the
571  * assumption being that the buffer represents the beginning of the stream or
572  * file.
573  *
574  * All available typefinders will be called on the data in order of rank. If
575  * a typefinding function returns a probability of #GST_TYPE_FIND_MAXIMUM,
576  * typefinding is stopped immediately and the found caps will be returned
577  * right away. Otherwise, all available typefind functions will the tried,
578  * and the caps with the highest probability will be returned, or #NULL if
579  * the content of the buffer could not be identified.
580  *
581  * Free-function: gst_caps_unref
582  *
583  * Returns: (transfer full): the #GstCaps corresponding to the data, or #NULL
584  *     if no type could be found. The caller should free the caps returned
585  *     with gst_caps_unref().
586  */
587 GstCaps *
588 gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
589     GstTypeFindProbability * prob)
590 {
591   GstCaps *result;
592   guint8 *data;
593   gsize size;
594
595   g_return_val_if_fail (buf != NULL, NULL);
596   g_return_val_if_fail (GST_IS_BUFFER (buf), NULL);
597   g_return_val_if_fail (GST_BUFFER_OFFSET (buf) == 0 ||
598       GST_BUFFER_OFFSET (buf) == GST_BUFFER_OFFSET_NONE, NULL);
599
600   data = gst_buffer_map (buf, &size, NULL, GST_MAP_READ);
601   result = gst_type_find_helper_for_data (obj, data, size, prob);
602   gst_buffer_unmap (buf, data, size);
603
604   return result;
605 }
606
607 /**
608  * gst_type_find_helper_for_extension:
609  * @obj: (allow-none): object doing the typefinding, or NULL (used for logging)
610  * @extension: an extension
611  *
612  * Tries to find the best #GstCaps associated with @extension.
613  *
614  * All available typefinders will be checked against the extension in order
615  * of rank. The caps of the first typefinder that can handle @extension will be
616  * returned.
617  *
618  * Free-function: gst_caps_unref
619  *
620  * Returns: (transfer full): the #GstCaps corresponding to @extension, or
621  *     #NULL if no type could be found. The caller should free the caps
622  *     returned with gst_caps_unref().
623  * 
624  * Since: 0.10.23
625  */
626 GstCaps *
627 gst_type_find_helper_for_extension (GstObject * obj, const gchar * extension)
628 {
629   GList *l, *type_list;
630   GstCaps *result = NULL;
631
632   g_return_val_if_fail (extension != NULL, NULL);
633
634   GST_LOG_OBJECT (obj, "finding caps for extension %s", extension);
635
636   type_list = gst_type_find_factory_get_list ();
637
638   for (l = type_list; l; l = g_list_next (l)) {
639     GstTypeFindFactory *factory;
640     gchar **ext;
641     gint i;
642
643     factory = GST_TYPE_FIND_FACTORY (l->data);
644
645     /* we only want to check those factories without a function */
646     if (factory->function != NULL)
647       continue;
648
649     /* get the extension that this typefind factory can handle */
650     ext = gst_type_find_factory_get_extensions (factory);
651     if (ext == NULL)
652       continue;
653
654     /* there are extension, see if one of them matches the requested
655      * extension */
656     for (i = 0; ext[i]; i++) {
657       if (strcmp (ext[i], extension) == 0) {
658         /* we found a matching extension, take the caps */
659         if ((result = gst_type_find_factory_get_caps (factory))) {
660           gst_caps_ref (result);
661           goto done;
662         }
663       }
664     }
665   }
666 done:
667   gst_plugin_feature_list_free (type_list);
668
669   GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT, result);
670
671   return result;
672 }