subprojects/gstreamer/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  * @title: GstTypeFindHelper
  27  * @short_description: Utility functions for typefinding
  28  *
  29  * Utility functions for elements doing typefinding:
  30  * gst_type_find_helper() does typefinding in pull mode, while
  31  * gst_type_find_helper_for_buffer() is useful for elements needing to do
  32  * typefinding in push mode from a chain function.
  33  */
  34
  35 #ifdef HAVE_CONFIG_H
  36 #  include "config.h"
  37 #endif
  38
  39 #include <stdlib.h>
  40 #include <string.h>
  41
  42 #include "gsttypefindhelper.h"
  43
  44 /* ********************** typefinding in pull mode ************************ */
  45
  46 static void
  47 helper_find_suggest (gpointer data, guint probability, 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   GstFlowReturn flow_ret;
  67 } GstTypeFindHelper;
  68
  69 /*
  70  * helper_find_peek:
  71  * @data: helper data struct
  72  * @off: stream offset
  73  * @size: block size
  74  *
  75  * Get data pointer within a stream. Keeps a cache of read buffers (partly
  76  * for performance reasons, but mostly because pointers returned by us need
  77  * to stay valid until typefinding has finished)
  78  *
  79  * Returns: (nullable): address of the data or %NULL if buffer does not cover
  80  * the requested range.
  81  */
  82 static const guint8 *
  83 helper_find_peek (gpointer data, gint64 offset, guint size)
  84 {
  85   GstTypeFindHelper *helper;
  86   GstBuffer *buffer;
  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, "Typefind factory called peek (%" G_GINT64_FORMAT
  98       ", %u)", 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   helper->flow_ret =
 144       helper->func (helper->obj, helper->parent, offset, MAX (size, 4096),
 145       &buffer);
 146
 147   if (helper->flow_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_size < size) {
 171     GST_DEBUG ("dropping short buffer of size %" G_GSIZE_FORMAT ","
 172         "requested size was %u", buf_size, size);
 173     gst_buffer_unref (buffer);
 174     return NULL;
 175   }
 176
 177   if (buf_offset != -1 && buf_offset != offset) {
 178     GST_DEBUG ("dropping buffer with unexpected offset %" G_GUINT64_FORMAT ", "
 179         "expected offset was %" G_GUINT64_FORMAT, buf_offset, offset);
 180     gst_buffer_unref (buffer);
 181     return NULL;
 182   }
 183
 184   bmap = g_slice_new0 (GstMappedBuffer);
 185
 186   if (!gst_buffer_map (buffer, &bmap->map, GST_MAP_READ))
 187     goto map_failed;
 188
 189   bmap->buffer = buffer;
 190
 191   if (insert_pos) {
 192     helper->buffers = g_slist_insert_before (helper->buffers, insert_pos, bmap);
 193   } else {
 194     /* if insert_pos is not set, our offset is bigger than the largest offset
 195      * we have so far; since we keep the list sorted with highest offsets
 196      * first, we need to prepend the buffer to the list */
 197     helper->last_offset = GST_BUFFER_OFFSET (buffer) + buf_size;
 198     helper->buffers = g_slist_prepend (helper->buffers, bmap);
 199   }
 200
 201   return bmap->map.data;
 202
 203 error:
 204   {
 205     GST_INFO ("typefind function returned: %s",
 206         gst_flow_get_name (helper->flow_ret));
 207     return NULL;
 208   }
 209 map_failed:
 210   {
 211     GST_ERROR ("map failed");
 212     gst_buffer_unref (buffer);
 213     g_slice_free (GstMappedBuffer, bmap);
 214     return NULL;
 215   }
 216 }
 217
 218 /*
 219  * helper_find_suggest:
 220  * @data: helper data struct
 221  * @probability: probability of the match
 222  * @caps: caps of the type
 223  *
 224  * If given @probability is higher, replace previously store caps.
 225  */
 226 static void
 227 helper_find_suggest (gpointer data, guint probability, GstCaps * caps)
 228 {
 229   GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
 230
 231   GST_LOG_OBJECT (helper->obj,
 232       "Typefind factory called suggest (%u, %" GST_PTR_FORMAT ")",
 233       probability, caps);
 234
 235   if (probability > helper->best_probability) {
 236     gst_caps_replace (&helper->caps, caps);
 237     helper->best_probability = probability;
 238   }
 239 }
 240
 241 static guint64
 242 helper_find_get_length (gpointer data)
 243 {
 244   GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
 245
 246   GST_LOG_OBJECT (helper->obj, "Typefind factory called get_length, returning %"
 247       G_GUINT64_FORMAT, helper->size);
 248
 249   return helper->size;
 250 }
 251
 252 static GList *
 253 prioritize_extension (GstObject * obj, GList * type_list,
 254     const gchar * extension)
 255 {
 256   gint pos = 0;
 257   GList *next, *l;
 258
 259   if (!extension)
 260     return type_list;
 261
 262   /* move the typefinders for the extension first in the list. The idea is that
 263    * when one of them returns MAX we don't need to search further as there is a
 264    * very high chance we got the right type. */
 265
 266   GST_LOG_OBJECT (obj, "sorting typefind for extension %s to head", extension);
 267
 268   for (l = type_list; l; l = next) {
 269     const gchar *const *ext;
 270     GstTypeFindFactory *factory;
 271
 272     next = l->next;
 273
 274     factory = GST_TYPE_FIND_FACTORY (l->data);
 275
 276     ext = gst_type_find_factory_get_extensions (factory);
 277     if (ext == NULL)
 278       continue;
 279
 280     GST_LOG_OBJECT (obj, "testing factory %s for extension %s",
 281         GST_OBJECT_NAME (factory), extension);
 282
 283     while (*ext != NULL) {
 284       if (strcmp (*ext, extension) == 0) {
 285         /* found extension, move in front */
 286         GST_LOG_OBJECT (obj, "moving typefind for extension %s to head",
 287             extension);
 288         /* remove entry from list */
 289         type_list = g_list_delete_link (type_list, l);
 290         /* insert at the position */
 291         type_list = g_list_insert (type_list, factory, pos);
 292         /* next element will be inserted after this one */
 293         pos++;
 294         break;
 295       }
 296       ++ext;
 297     }
 298   }
 299
 300   return type_list;
 301 }
 302
 303 /**
 304  * gst_type_find_helper_get_range:
 305  * @obj: A #GstObject that will be passed as first argument to @func
 306  * @parent: (nullable): the parent of @obj or %NULL
 307  * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
 308  *        be used to access data at random offsets when doing the typefinding
 309  * @size: The length in bytes
 310  * @extension: (nullable): extension of the media, or %NULL
 311  * @prob: (out) (optional): location to store the probability of the found
 312  *     caps, or %NULL
 313  *
 314  * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
 315  * however, this function will use the specified function @func to obtain the
 316  * data needed by the typefind functions, rather than operating on a given
 317  * source pad. This is useful mostly for elements like tag demuxers which
 318  * strip off data at the beginning and/or end of a file and want to typefind
 319  * the stripped data stream before adding their own source pad (the specified
 320  * callback can then call the upstream peer pad with offsets adjusted for the
 321  * tag size, for example).
 322  *
 323  * When @extension is not %NULL, this function will first try the typefind
 324  * functions for the given extension, which might speed up the typefinding
 325  * in many cases.
 326  *
 327  * Free-function: gst_caps_unref
 328  *
 329  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data
 330  *     stream.  Returns %NULL if no #GstCaps matches the data stream.
 331  */
 332 GstCaps *
 333 gst_type_find_helper_get_range (GstObject * obj, GstObject * parent,
 334     GstTypeFindHelperGetRangeFunction func, guint64 size,
 335     const gchar * extension, GstTypeFindProbability * prob)
 336 {
 337   GstCaps *caps = NULL;
 338
 339   gst_type_find_helper_get_range_full (obj, parent, func, size, extension,
 340       &caps, prob);
 341
 342   return caps;
 343 }
 344
 345 /**
 346  * gst_type_find_helper_get_range_full:
 347  * @obj: A #GstObject that will be passed as first argument to @func
 348  * @parent: (nullable): the parent of @obj or %NULL
 349  * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
 350  *        be used to access data at random offsets when doing the typefinding
 351  * @size: The length in bytes
 352  * @extension: (nullable): extension of the media, or %NULL
 353  * @caps: (out) (transfer full): returned caps
 354  * @prob: (out) (optional): location to store the probability of the found
 355  *     caps, or %NULL
 356  *
 357  * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
 358  * however, this function will use the specified function @func to obtain the
 359  * data needed by the typefind functions, rather than operating on a given
 360  * source pad. This is useful mostly for elements like tag demuxers which
 361  * strip off data at the beginning and/or end of a file and want to typefind
 362  * the stripped data stream before adding their own source pad (the specified
 363  * callback can then call the upstream peer pad with offsets adjusted for the
 364  * tag size, for example).
 365  *
 366  * When @extension is not %NULL, this function will first try the typefind
 367  * functions for the given extension, which might speed up the typefinding
 368  * in many cases.
 369  *
 370  * Returns: the last %GstFlowReturn from pulling a buffer or %GST_FLOW_OK if
 371  *          typefinding was successful.
 372  *
 373  * Since: 1.14.3
 374  */
 375 GstFlowReturn
 376 gst_type_find_helper_get_range_full (GstObject * obj, GstObject * parent,
 377     GstTypeFindHelperGetRangeFunction func, guint64 size,
 378     const gchar * extension, GstCaps ** caps, GstTypeFindProbability * prob)
 379 {
 380   GstTypeFindHelper helper;
 381   GstTypeFind find;
 382   GSList *walk;
 383   GList *l, *type_list;
 384   GstCaps *result = NULL;
 385
 386   g_return_val_if_fail (GST_IS_OBJECT (obj), GST_FLOW_ERROR);
 387   g_return_val_if_fail (func != NULL, GST_FLOW_ERROR);
 388   g_return_val_if_fail (caps != NULL, GST_FLOW_ERROR);
 389
 390   *caps = NULL;
 391
 392   helper.buffers = NULL;
 393   helper.size = size;
 394   helper.last_offset = 0;
 395   helper.func = func;
 396   helper.best_probability = GST_TYPE_FIND_NONE;
 397   helper.caps = NULL;
 398   helper.obj = obj;
 399   helper.parent = parent;
 400   helper.flow_ret = GST_FLOW_OK;
 401
 402   find.data = &helper;
 403   find.peek = helper_find_peek;
 404   find.suggest = helper_find_suggest;
 405
 406   if (size == 0 || size == (guint64) - 1) {
 407     find.get_length = NULL;
 408   } else {
 409     find.get_length = helper_find_get_length;
 410   }
 411
 412   type_list = gst_type_find_factory_get_list ();
 413   type_list = prioritize_extension (obj, type_list, extension);
 414
 415   for (l = type_list; l; l = l->next) {
 416     helper.factory = GST_TYPE_FIND_FACTORY (l->data);
 417     gst_type_find_factory_call_function (helper.factory, &find);
 418     if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM) {
 419       /* Any other flow return can be ignored here, we found
 420        * something before any error with highest probability */
 421       helper.flow_ret = GST_FLOW_OK;
 422       break;
 423     } else if (helper.flow_ret != GST_FLOW_OK
 424         && helper.flow_ret != GST_FLOW_EOS) {
 425       /* We had less than maximum probability and an error, don't return
 426        * any caps as they might be with a lower probability than what
 427        * we would've gotten when continuing if there was no error */
 428       gst_caps_replace (&helper.caps, NULL);
 429       break;
 430     }
 431   }
 432   gst_plugin_feature_list_free (type_list);
 433
 434   for (walk = helper.buffers; walk; walk = walk->next) {
 435     GstMappedBuffer *bmap = (GstMappedBuffer *) walk->data;
 436
 437     gst_buffer_unmap (bmap->buffer, &bmap->map);
 438     gst_buffer_unref (bmap->buffer);
 439     g_slice_free (GstMappedBuffer, bmap);
 440   }
 441   g_slist_free (helper.buffers);
 442
 443   if (helper.best_probability > 0)
 444     result = helper.caps;
 445
 446   if (prob)
 447     *prob = helper.best_probability;
 448
 449   *caps = result;
 450   if (helper.flow_ret == GST_FLOW_EOS) {
 451     /* Some typefinder might've tried to read too much, if we
 452      * didn't get any meaningful caps because of that this is
 453      * just a normal error */
 454     helper.flow_ret = GST_FLOW_ERROR;
 455   }
 456
 457   GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
 458       result, (guint) helper.best_probability);
 459
 460   return helper.flow_ret;
 461 }
 462
 463 /**
 464  * gst_type_find_helper:
 465  * @src: A source #GstPad
 466  * @size: The length in bytes
 467  *
 468  * Tries to find what type of data is flowing from the given source #GstPad.
 469  *
 470  * Free-function: gst_caps_unref
 471  *
 472  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data
 473  *     stream.  Returns %NULL if no #GstCaps matches the data stream.
 474  */
 475
 476 GstCaps *
 477 gst_type_find_helper (GstPad * src, guint64 size)
 478 {
 479   GstTypeFindHelperGetRangeFunction func;
 480
 481   g_return_val_if_fail (GST_IS_OBJECT (src), NULL);
 482   g_return_val_if_fail (GST_PAD_GETRANGEFUNC (src) != NULL, NULL);
 483
 484   func = (GstTypeFindHelperGetRangeFunction) (GST_PAD_GETRANGEFUNC (src));
 485
 486   return gst_type_find_helper_get_range (GST_OBJECT (src),
 487       GST_OBJECT_PARENT (src), func, size, NULL, NULL);
 488 }
 489
 490 /* ********************** typefinding for buffers ************************* */
 491
 492 typedef struct
 493 {
 494   const guint8 *data;           /* buffer data */
 495   gsize size;
 496   GstTypeFindProbability best_probability;
 497   GstCaps *caps;
 498   GstObject *obj;               /* for logging */
 499 } GstTypeFindBufHelper;
 500
 501 /**
 502  * GstTypeFindData:
 503  *
 504  * The opaque #GstTypeFindData structure.
 505  *
 506  * Since: 1.22
 507  *
 508  */
 509 struct _GstTypeFindData
 510 {
 511   GstTypeFind find;
 512   GstTypeFindBufHelper helper;
 513 };
 514
 515 /*
 516  * buf_helper_find_peek:
 517  * @data: helper data struct
 518  * @off: stream offset
 519  * @size: block size
 520  *
 521  * Get data pointer within a buffer.
 522  *
 523  * Returns: (nullable): address inside the buffer or %NULL if buffer does not
 524  * cover the requested range.
 525  */
 526 static const guint8 *
 527 buf_helper_find_peek (gpointer data, gint64 off, guint size)
 528 {
 529   GstTypeFindBufHelper *helper;
 530
 531   helper = (GstTypeFindBufHelper *) data;
 532   GST_LOG_OBJECT (helper->obj,
 533       "Typefind factory called peek (%" G_GINT64_FORMAT ", %u)", off, size);
 534
 535   if (size == 0)
 536     return NULL;
 537
 538   if (off < 0) {
 539     GST_LOG_OBJECT (helper->obj,
 540         "Typefind factory wanted to peek at end; not supported");
 541     return NULL;
 542   }
 543
 544   /* If we request beyond the available size, we're sure we can't return
 545    * anything regardless of the requested offset */
 546   if (size > helper->size)
 547     return NULL;
 548
 549   /* Only return data if there's enough room left for the given offset.
 550    * This is the same as "if (off + size <= helper->size)" except that
 551    * it doesn't exceed type limits */
 552   if (off <= helper->size - size)
 553     return helper->data + off;
 554
 555   return NULL;
 556 }
 557
 558 /*
 559  * buf_helper_find_suggest:
 560  * @data: helper data struct
 561  * @probability: probability of the match
 562  * @caps: caps of the type
 563  *
 564  * If given @probability is higher, replace previously store caps.
 565  */
 566 static void
 567 buf_helper_find_suggest (gpointer data, guint probability, GstCaps * caps)
 568 {
 569   GstTypeFindBufHelper *helper = (GstTypeFindBufHelper *) data;
 570
 571   GST_LOG_OBJECT (helper->obj,
 572       "Typefind factory called suggest (%u, %" GST_PTR_FORMAT ")",
 573       probability, caps);
 574
 575   /* Note: not >= as we call typefinders in order of rank, highest first */
 576   if (probability > helper->best_probability) {
 577     gst_caps_replace (&helper->caps, caps);
 578     helper->best_probability = probability;
 579   }
 580 }
 581
 582 /**
 583  * gst_type_find_helper_for_data:
 584  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 585  * @data: (transfer none) (array length=size): * a pointer with data to typefind
 586  * @size: the size of @data
 587  * @prob: (out) (optional): location to store the probability of the found
 588  *     caps, or %NULL
 589  *
 590  * Tries to find what type of data is contained in the given @data, the
 591  * assumption being that the data represents the beginning of the stream or
 592  * file.
 593  *
 594  * All available typefinders will be called on the data in order of rank. If
 595  * a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM,
 596  * typefinding is stopped immediately and the found caps will be returned
 597  * right away. Otherwise, all available typefind functions will the tried,
 598  * and the caps with the highest probability will be returned, or %NULL if
 599  * the content of @data could not be identified.
 600  *
 601  * Free-function: gst_caps_unref
 602  *
 603  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
 604  *     or %NULL if no type could be found. The caller should free the caps
 605  *     returned with gst_caps_unref().
 606  */
 607 GstCaps *
 608 gst_type_find_helper_for_data (GstObject * obj, const guint8 * data, gsize size,
 609     GstTypeFindProbability * prob)
 610 {
 611   return gst_type_find_helper_for_data_with_extension (obj, data, size, NULL,
 612       prob);
 613 }
 614
 615 /**
 616  * gst_type_find_helper_for_data_with_extension:
 617  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 618  * @data: (transfer none) (array length=size): * a pointer with data to typefind
 619  * @size: the size of @data
 620  * @extension: (nullable): extension of the media, or %NULL
 621  * @prob: (out) (optional): location to store the probability of the found
 622  *     caps, or %NULL
 623  *
 624  * Tries to find what type of data is contained in the given @data, the
 625  * assumption being that the data represents the beginning of the stream or
 626  * file.
 627  *
 628  * All available typefinders will be called on the data in order of rank. If
 629  * a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM,
 630  * typefinding is stopped immediately and the found caps will be returned
 631  * right away. Otherwise, all available typefind functions will the tried,
 632  * and the caps with the highest probability will be returned, or %NULL if
 633  * the content of @data could not be identified.
 634  *
 635  * When @extension is not %NULL, this function will first try the typefind
 636  * functions for the given extension, which might speed up the typefinding
 637  * in many cases.
 638  *
 639  * Free-function: gst_caps_unref
 640  *
 641  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
 642  *     or %NULL if no type could be found. The caller should free the caps
 643  *     returned with gst_caps_unref().
 644  *
 645  * Since: 1.16
 646  *
 647  */
 648 GstCaps *
 649 gst_type_find_helper_for_data_with_extension (GstObject * obj,
 650     const guint8 * data, gsize size, const gchar * extension,
 651     GstTypeFindProbability * prob)
 652 {
 653   GstTypeFindBufHelper helper;
 654   GstTypeFindFactory *factory;
 655   GstTypeFind find;
 656   GList *l, *type_list;
 657   GstCaps *result = NULL;
 658
 659   g_return_val_if_fail (data != NULL, NULL);
 660
 661   helper.data = data;
 662   helper.size = size;
 663   helper.best_probability = GST_TYPE_FIND_NONE;
 664   helper.caps = NULL;
 665   helper.obj = obj;
 666
 667   if (helper.data == NULL || helper.size == 0)
 668     return NULL;
 669
 670   find.data = &helper;
 671   find.peek = buf_helper_find_peek;
 672   find.suggest = buf_helper_find_suggest;
 673   find.get_length = NULL;
 674
 675   type_list = gst_type_find_factory_get_list ();
 676   type_list = prioritize_extension (obj, type_list, extension);
 677
 678   for (l = type_list; l; l = l->next) {
 679     factory = GST_TYPE_FIND_FACTORY (l->data);
 680     gst_type_find_factory_call_function (factory, &find);
 681     if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
 682       break;
 683   }
 684   gst_plugin_feature_list_free (type_list);
 685
 686   if (helper.best_probability > 0)
 687     result = helper.caps;
 688
 689   if (prob)
 690     *prob = helper.best_probability;
 691
 692   GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
 693       result, (guint) helper.best_probability);
 694
 695   return result;
 696 }
 697
 698 /**
 699  * gst_type_find_helper_for_data_with_caps:
 700  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 701  * @data: (transfer none) (array length=size): a pointer with data to typefind
 702  * @size: the size of @data
 703  * @caps: caps of the media
 704  * @prob: (out) (optional): location to store the probability of the found
 705  *     caps, or %NULL
 706  *
 707  * Tries to find if type of media contained in the given @data, matches the
 708  * @caps specified, assumption being that the data represents the beginning
 709  * of the stream or file.
 710  *
 711  * Only the typefinder matching the given caps will be called, if found. The
 712  * caps with the highest probability will be returned, or %NULL if the content
 713  * of the @data could not be identified.
 714  *
 715  * Free-function: gst_caps_unref
 716  *
 717  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
 718  *     or %NULL if no type could be found. The caller should free the caps
 719  *     returned with gst_caps_unref().
 720  *
 721  * Since: 1.22
 722  *
 723  */
 724 GstCaps *
 725 gst_type_find_helper_for_data_with_caps (GstObject * obj,
 726     const guint8 * data, gsize size, GstCaps * caps,
 727     GstTypeFindProbability * prob)
 728 {
 729   GstTypeFind *find;
 730   GstTypeFindData *find_data;
 731   GstTypeFindFactory *factory;
 732   GList *l, *factories = NULL;
 733   GstCaps *result = NULL;
 734   GstTypeFindProbability found_probability, last_found_probability;
 735
 736   g_return_val_if_fail (data != NULL, NULL);
 737   g_return_val_if_fail (caps != NULL, NULL);
 738   g_return_val_if_fail (size != 0, NULL);
 739
 740   find_data = gst_type_find_data_new (obj, data, size);
 741   find = gst_type_find_data_get_typefind (find_data);
 742
 743   factories = gst_type_find_list_factories_for_caps (obj, caps);
 744   if (!factories) {
 745     GST_ERROR_OBJECT (obj, "Failed to typefind for caps: %" GST_PTR_FORMAT,
 746         caps);
 747     goto out;
 748   }
 749
 750   found_probability = GST_TYPE_FIND_NONE;
 751   last_found_probability = GST_TYPE_FIND_NONE;
 752
 753   for (l = factories; l; l = l->next) {
 754     factory = GST_TYPE_FIND_FACTORY (l->data);
 755
 756     gst_type_find_factory_call_function (factory, find);
 757
 758     found_probability = gst_type_find_data_get_probability (find_data);
 759
 760     if (found_probability > last_found_probability) {
 761       last_found_probability = found_probability;
 762       result = gst_type_find_data_get_caps (find_data);
 763
 764       GST_DEBUG_OBJECT (obj, "Found %" GST_PTR_FORMAT " (probability = %u)",
 765           result, (guint) last_found_probability);
 766       if (last_found_probability >= GST_TYPE_FIND_MAXIMUM)
 767         break;
 768     }
 769   }
 770
 771   if (prob)
 772     *prob = last_found_probability;
 773
 774   GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
 775       result, (guint) last_found_probability);
 776
 777 out:
 778   g_list_free_full (factories, (GDestroyNotify) gst_object_unref);
 779
 780   gst_type_find_data_free (find_data);
 781
 782   return result;
 783 }
 784
 785 /**
 786  * gst_type_find_helper_for_buffer:
 787  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 788  * @buf: (in) (transfer none): a #GstBuffer with data to typefind
 789  * @prob: (out) (optional): location to store the probability of the found
 790  *     caps, or %NULL
 791  *
 792  * Tries to find what type of data is contained in the given #GstBuffer, the
 793  * assumption being that the buffer represents the beginning of the stream or
 794  * file.
 795  *
 796  * All available typefinders will be called on the data in order of rank. If
 797  * a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM,
 798  * typefinding is stopped immediately and the found caps will be returned
 799  * right away. Otherwise, all available typefind functions will the tried,
 800  * and the caps with the highest probability will be returned, or %NULL if
 801  * the content of the buffer could not be identified.
 802  *
 803  * Free-function: gst_caps_unref
 804  *
 805  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
 806  *     or %NULL if no type could be found. The caller should free the caps
 807  *     returned with gst_caps_unref().
 808  */
 809 GstCaps *
 810 gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
 811     GstTypeFindProbability * prob)
 812 {
 813   return gst_type_find_helper_for_buffer_with_extension (obj, buf, NULL, prob);
 814 }
 815
 816 /**
 817  * gst_type_find_helper_for_buffer_with_extension:
 818  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 819  * @buf: (in) (transfer none): a #GstBuffer with data to typefind
 820  * @extension: (nullable): extension of the media, or %NULL
 821  * @prob: (out) (optional): location to store the probability of the found
 822  *     caps, or %NULL
 823  *
 824  * Tries to find what type of data is contained in the given #GstBuffer, the
 825  * assumption being that the buffer represents the beginning of the stream or
 826  * file.
 827  *
 828  * All available typefinders will be called on the data in order of rank. If
 829  * a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM,
 830  * typefinding is stopped immediately and the found caps will be returned
 831  * right away. Otherwise, all available typefind functions will the tried,
 832  * and the caps with the highest probability will be returned, or %NULL if
 833  * the content of the buffer could not be identified.
 834  *
 835  * When @extension is not %NULL, this function will first try the typefind
 836  * functions for the given extension, which might speed up the typefinding
 837  * in many cases.
 838  *
 839  * Free-function: gst_caps_unref
 840  *
 841  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
 842  *     or %NULL if no type could be found. The caller should free the caps
 843  *     returned with gst_caps_unref().
 844  *
 845  * Since: 1.16
 846  *
 847  */
 848 GstCaps *
 849 gst_type_find_helper_for_buffer_with_extension (GstObject * obj,
 850     GstBuffer * buf, const gchar * extension, GstTypeFindProbability * prob)
 851 {
 852   GstCaps *result;
 853   GstMapInfo info;
 854
 855   g_return_val_if_fail (buf != NULL, NULL);
 856   g_return_val_if_fail (GST_IS_BUFFER (buf), NULL);
 857   g_return_val_if_fail (GST_BUFFER_OFFSET (buf) == 0 ||
 858       GST_BUFFER_OFFSET (buf) == GST_BUFFER_OFFSET_NONE, NULL);
 859
 860   if (!gst_buffer_map (buf, &info, GST_MAP_READ))
 861     return NULL;
 862   result =
 863       gst_type_find_helper_for_data_with_extension (obj, info.data, info.size,
 864       extension, prob);
 865   gst_buffer_unmap (buf, &info);
 866
 867   return result;
 868 }
 869
 870 /**
 871  * gst_type_find_helper_for_buffer_with_caps:
 872  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 873  * @buf: (transfer none): a #GstBuffer with data to typefind
 874  * @caps: caps of the media
 875  * @prob: (out) (optional): location to store the probability of the found
 876  *     caps, or %NULL
 877  *
 878  * Tries to find if type of media contained in the given #GstBuffer, matches
 879  * @caps specified, assumption being that the buffer represents the beginning
 880  * of the stream or file.
 881  *
 882  * Tries to find what type of data is contained in the given @data, the
 883  * assumption being that the data represents the beginning of the stream or
 884  * file.
 885  *
 886  * Only the typefinder matching the given caps will be called, if found. The
 887  * caps with the highest probability will be returned, or %NULL if the content
 888  * of the @data could not be identified.
 889  *
 890  * Free-function: gst_caps_unref
 891  *
 892  * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
 893  *     or %NULL if no type could be found. The caller should free the caps
 894  *     returned with gst_caps_unref().
 895  *
 896  * Since: 1.22
 897  *
 898  */
 899 GstCaps *
 900 gst_type_find_helper_for_buffer_with_caps (GstObject * obj,
 901     GstBuffer * buf, GstCaps * caps, GstTypeFindProbability * prob)
 902 {
 903   GstCaps *result;
 904   GstMapInfo info;
 905
 906   g_return_val_if_fail (caps != NULL, NULL);
 907   g_return_val_if_fail (buf != NULL, NULL);
 908   g_return_val_if_fail (GST_IS_BUFFER (buf), NULL);
 909   g_return_val_if_fail (GST_BUFFER_OFFSET (buf) == 0 ||
 910       GST_BUFFER_OFFSET (buf) == GST_BUFFER_OFFSET_NONE, NULL);
 911
 912   if (!gst_buffer_map (buf, &info, GST_MAP_READ))
 913     return NULL;
 914
 915   result =
 916       gst_type_find_helper_for_data_with_caps (obj, info.data, info.size,
 917       caps, prob);
 918
 919   gst_buffer_unmap (buf, &info);
 920
 921   return result;
 922 }
 923
 924 /**
 925  * gst_type_find_helper_for_extension:
 926  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 927  * @extension: an extension
 928  *
 929  * Tries to find the best #GstCaps associated with @extension.
 930  *
 931  * All available typefinders will be checked against the extension in order
 932  * of rank. The caps of the first typefinder that can handle @extension will be
 933  * returned.
 934  *
 935  * Free-function: gst_caps_unref
 936  *
 937  * Returns: (transfer full) (nullable): the #GstCaps corresponding to
 938  *     @extension, or %NULL if no type could be found. The caller should free
 939  *     the caps returned with gst_caps_unref().
 940  */
 941 GstCaps *
 942 gst_type_find_helper_for_extension (GstObject * obj, const gchar * extension)
 943 {
 944   GList *l, *type_list;
 945   GstCaps *result = NULL;
 946
 947   g_return_val_if_fail (extension != NULL, NULL);
 948
 949   GST_LOG_OBJECT (obj, "finding caps for extension %s", extension);
 950
 951   type_list = gst_type_find_factory_get_list ();
 952
 953   for (l = type_list; l; l = g_list_next (l)) {
 954     GstTypeFindFactory *factory;
 955     const gchar *const *ext;
 956
 957     factory = GST_TYPE_FIND_FACTORY (l->data);
 958
 959     /* we only want to check those factories without a function */
 960     if (gst_type_find_factory_has_function (factory))
 961       continue;
 962
 963     /* get the extension that this typefind factory can handle */
 964     ext = gst_type_find_factory_get_extensions (factory);
 965     if (ext == NULL)
 966       continue;
 967
 968     /* there are extension, see if one of them matches the requested
 969      * extension */
 970     while (*ext != NULL) {
 971       if (strcmp (*ext, extension) == 0) {
 972         /* we found a matching extension, take the caps */
 973         if ((result = gst_type_find_factory_get_caps (factory))) {
 974           gst_caps_ref (result);
 975           goto done;
 976         }
 977       }
 978       ++ext;
 979     }
 980   }
 981 done:
 982   gst_plugin_feature_list_free (type_list);
 983
 984   GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT, result);
 985
 986   return result;
 987 }
 988
 989 /**
 990  * gst_type_find_list_factories_for_caps:
 991  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
 992  * @caps: caps of the media
 993  *
 994  * Tries to find the best #GstTypeFindFactory associated with @caps.
 995  *
 996  * The typefinder that can handle @caps will be returned.
 997  *
 998  * Free-function: g_list_free
 999  *
1000  * Returns: (transfer full) (nullable) (element-type Gst.TypeFindFactory): the list of #GstTypeFindFactory
1001  *          corresponding to @caps, or %NULL if no typefinder could be
1002  *          found. Caller should free the returned list with g_list_free()
1003  *          and list elements with gst_object_unref().
1004  *
1005  * Since: 1.22
1006  *
1007  */
1008 GList *
1009 gst_type_find_list_factories_for_caps (GstObject * obj, GstCaps * caps)
1010 {
1011   GList *l, *type_list, *factories = NULL;
1012
1013   g_return_val_if_fail (caps != NULL, NULL);
1014
1015   GST_LOG_OBJECT (obj, "finding factory for caps %" GST_PTR_FORMAT, caps);
1016
1017   type_list = gst_type_find_factory_get_list ();
1018
1019   for (l = type_list; l; l = g_list_next (l)) {
1020     GstTypeFindFactory *factory;
1021     GstCaps *factory_caps;
1022
1023     factory = GST_TYPE_FIND_FACTORY (l->data);
1024
1025     /* We only want to check those factories without a function */
1026     if (gst_type_find_factory_has_function (factory))
1027       continue;
1028
1029     /* Get the caps that this typefind factory can handle */
1030     factory_caps = gst_type_find_factory_get_caps (factory);
1031     if (!factory_caps)
1032       continue;
1033
1034     if (gst_caps_can_intersect (factory_caps, caps)) {
1035       factory = gst_object_ref (factory);
1036       factories = g_list_prepend (factories, factory);
1037     }
1038   }
1039
1040   gst_plugin_feature_list_free (type_list);
1041
1042   return g_list_reverse (factories);
1043 }
1044
1045 /**
1046  * gst_type_find_data_new: (skip)
1047  * @obj: (nullable): object doing the typefinding, or %NULL (used for logging)
1048  * @data: (transfer none) (array length=size): a pointer with data to typefind
1049  * @size: the size of @data
1050  *
1051  * Free-function: gst_type_find_data_free
1052  *
1053  * Returns: (transfer full): the #GstTypeFindData. The caller should free
1054  *          the returned #GstTypeFindData with gst_type_find_data_free().
1055  *
1056  * Since: 1.22
1057  *
1058  */
1059 GstTypeFindData *
1060 gst_type_find_data_new (GstObject * obj, const guint8 * data, gsize size)
1061 {
1062   GstTypeFindData *find_data;
1063
1064   g_return_val_if_fail (data != NULL, NULL);
1065   g_return_val_if_fail (size != 0, NULL);
1066
1067   find_data = g_new0 (GstTypeFindData, 1);
1068
1069   find_data->helper.data = data;
1070   find_data->helper.size = size;
1071   find_data->helper.best_probability = GST_TYPE_FIND_NONE;
1072   find_data->helper.caps = NULL;
1073   find_data->helper.obj = obj;
1074
1075   find_data->find.data = (gpointer) (&find_data->helper);
1076   find_data->find.peek = buf_helper_find_peek;
1077   find_data->find.suggest = buf_helper_find_suggest;
1078   find_data->find.get_length = NULL;
1079
1080   return find_data;
1081 }
1082
1083 /**
1084  * gst_type_find_data_get_caps: (skip)
1085  * @data: GstTypeFindData *
1086  *
1087  * Returns #GstCaps associated with #GstTypeFindData
1088  *
1089  * Returns: (transfer full) (nullable): #GstCaps.
1090  *
1091  * Since: 1.22
1092  *
1093  */
1094 GstCaps *
1095 gst_type_find_data_get_caps (GstTypeFindData * data)
1096 {
1097   g_return_val_if_fail (data != NULL, NULL);
1098
1099   return gst_caps_ref (data->helper.caps);
1100 }
1101
1102 /**
1103  * gst_type_find_data_get_probability: (skip)
1104  * @data: GstTypeFindData *
1105  *
1106  * Returns #GstTypeFindProbability associated with #GstTypeFindData
1107  *
1108  * Returns: #GstTypeFindProbability.
1109  *
1110  * Since: 1.22
1111  *
1112  */
1113 GstTypeFindProbability
1114 gst_type_find_data_get_probability (GstTypeFindData * data)
1115 {
1116   g_return_val_if_fail (data != NULL, GST_TYPE_FIND_NONE);
1117
1118   return data->helper.best_probability;
1119 }
1120
1121 /**
1122  * gst_type_find_data_get_typefind: (skip)
1123  * @data: GstTypeFindData *
1124  *
1125  * Returns #GstTypeFind associated with #GstTypeFindData
1126  *
1127  * Returns: #GstTypeFind.
1128  *
1129  * Since: 1.22
1130  *
1131  */
1132 GstTypeFind *
1133 gst_type_find_data_get_typefind (GstTypeFindData * data)
1134 {
1135   g_return_val_if_fail (data != NULL, NULL);
1136
1137   return &data->find;
1138 }
1139
1140 /**
1141  * gst_type_find_data_free: (skip)
1142  * @data: GstTypeFindData * to free
1143  *
1144  * Since: 1.22
1145  *
1146  */
1147 void
1148 gst_type_find_data_free (GstTypeFindData * data)
1149 {
1150   if (data && data->helper.caps)
1151     gst_caps_unref (data->helper.caps);
1152
1153   g_free (data);
1154 }