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