gst/gsturi.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  * Copyright (C) 2011 Tim-Philipp Müller <tim centricular net>
   5  *
   6  * gsturi.c: register URI handlers
   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:gsturihandler
  26  * @short_description: Interface to ease URI handling in plugins.
  27  *
  28  * The URIHandler is an interface that is implemented by Source and Sink
  29  * #GstElement to simplify then handling of URI.
  30  *
  31  * An application can use the following functions to quickly get an element
  32  * that handles the given URI for reading or writing
  33  * (gst_element_make_from_uri()).
  34  *
  35  * Source and Sink plugins should implement this interface when possible.
  36  *
  37  * Last reviewed on 2005-11-09 (0.9.4)
  38  */
  39
  40 #ifdef HAVE_CONFIG_H
  41 #  include "config.h"
  42 #endif
  43
  44 #include "gst_private.h"
  45 #include "gst.h"
  46 #include "gsturi.h"
  47 #include "gstinfo.h"
  48 #include "gstregistry.h"
  49
  50 #include "gst-i18n-lib.h"
  51
  52 #include <string.h>
  53
  54 GST_DEBUG_CATEGORY_STATIC (gst_uri_handler_debug);
  55 #define GST_CAT_DEFAULT gst_uri_handler_debug
  56
  57 GType
  58 gst_uri_handler_get_type (void)
  59 {
  60   static volatile gsize urihandler_type = 0;
  61
  62   if (g_once_init_enter (&urihandler_type)) {
  63     GType _type;
  64     static const GTypeInfo urihandler_info = {
  65       sizeof (GstURIHandlerInterface),
  66       NULL,
  67       NULL,
  68       NULL,
  69       NULL,
  70       NULL,
  71       0,
  72       0,
  73       NULL,
  74       NULL
  75     };
  76
  77     _type = g_type_register_static (G_TYPE_INTERFACE,
  78         "GstURIHandler", &urihandler_info, 0);
  79
  80     GST_DEBUG_CATEGORY_INIT (gst_uri_handler_debug, "GST_URI", GST_DEBUG_BOLD,
  81         "handling of URIs");
  82     g_once_init_leave (&urihandler_type, _type);
  83   }
  84   return urihandler_type;
  85 }
  86
  87 GQuark
  88 gst_uri_error_quark (void)
  89 {
  90   return g_quark_from_static_string ("gst-uri-error-quark");
  91 }
  92
  93 static const guchar acceptable[96] = {  /* X0   X1   X2   X3   X4   X5   X6   X7   X8   X9   XA   XB   XC   XD   XE   XF */
  94   0x00, 0x3F, 0x20, 0x20, 0x20, 0x00, 0x2C, 0x3F, 0x3F, 0x3F, 0x3F, 0x22, 0x20, 0x3F, 0x3F, 0x1C,       /* 2X  !"#$%&'()*+,-./   */
  95   0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x38, 0x20, 0x20, 0x2C, 0x20, 0x2C,       /* 3X 0123456789:;<=>?   */
  96   0x30, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F,       /* 4X @ABCDEFGHIJKLMNO   */
  97   0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x20, 0x20, 0x20, 0x20, 0x3F,       /* 5X PQRSTUVWXYZ[\]^_   */
  98   0x20, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F,       /* 6X `abcdefghijklmno   */
  99   0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x20, 0x20, 0x20, 0x3F, 0x20        /* 7X pqrstuvwxyz{|}~DEL */
 100 };
 101
 102 typedef enum
 103 {
 104   UNSAFE_ALL = 0x1,             /* Escape all unsafe characters   */
 105   UNSAFE_ALLOW_PLUS = 0x2,      /* Allows '+'  */
 106   UNSAFE_PATH = 0x4,            /* Allows '/' and '?' and '&' and '='  */
 107   UNSAFE_DOS_PATH = 0x8,        /* Allows '/' and '?' and '&' and '=' and ':' */
 108   UNSAFE_HOST = 0x10,           /* Allows '/' and ':' and '@' */
 109   UNSAFE_SLASHES = 0x20         /* Allows all characters except for '/' and '%' */
 110 } UnsafeCharacterSet;
 111
 112 #define HEX_ESCAPE '%'
 113
 114 /*  Escape undesirable characters using %
 115  *  -------------------------------------
 116  *
 117  * This function takes a pointer to a string in which
 118  * some characters may be unacceptable unescaped.
 119  * It returns a string which has these characters
 120  * represented by a '%' character followed by two hex digits.
 121  *
 122  * This routine returns a g_malloced string.
 123  */
 124
 125 static const gchar hex[16] = "0123456789ABCDEF";
 126
 127 static gchar *
 128 escape_string_internal (const gchar * string, UnsafeCharacterSet mask)
 129 {
 130 #define ACCEPTABLE_CHAR(a) ((a)>=32 && (a)<128 && (acceptable[(a)-32] & use_mask))
 131
 132   const gchar *p;
 133   gchar *q;
 134   gchar *result;
 135   guchar c;
 136   gint unacceptable;
 137   UnsafeCharacterSet use_mask;
 138
 139   g_return_val_if_fail (mask == UNSAFE_ALL
 140       || mask == UNSAFE_ALLOW_PLUS
 141       || mask == UNSAFE_PATH
 142       || mask == UNSAFE_DOS_PATH
 143       || mask == UNSAFE_HOST || mask == UNSAFE_SLASHES, NULL);
 144
 145   if (string == NULL) {
 146     return NULL;
 147   }
 148
 149   unacceptable = 0;
 150   use_mask = mask;
 151   for (p = string; *p != '\0'; p++) {
 152     c = *p;
 153     if (!ACCEPTABLE_CHAR (c)) {
 154       unacceptable++;
 155     }
 156     if ((use_mask == UNSAFE_HOST) && (unacceptable || (c == '/'))) {
 157       /* when escaping a host, if we hit something that needs to be escaped, or we finally
 158        * hit a path separator, revert to path mode (the host segment of the url is over).
 159        */
 160       use_mask = UNSAFE_PATH;
 161     }
 162   }
 163
 164   result = g_malloc (p - string + unacceptable * 2 + 1);
 165
 166   use_mask = mask;
 167   for (q = result, p = string; *p != '\0'; p++) {
 168     c = *p;
 169
 170     if (!ACCEPTABLE_CHAR (c)) {
 171       *q++ = HEX_ESCAPE;        /* means hex coming */
 172       *q++ = hex[c >> 4];
 173       *q++ = hex[c & 15];
 174     } else {
 175       *q++ = c;
 176     }
 177     if ((use_mask == UNSAFE_HOST) && (!ACCEPTABLE_CHAR (c) || (c == '/'))) {
 178       use_mask = UNSAFE_PATH;
 179     }
 180   }
 181
 182   *q = '\0';
 183
 184   return result;
 185 }
 186
 187 /* escape_string:
 188  * @string: string to be escaped
 189  *
 190  * Escapes @string, replacing any and all special characters
 191  * with equivalent escape sequences.
 192  *
 193  * Return value: a newly allocated string equivalent to @string
 194  * but with all special characters escaped
 195  **/
 196 static gchar *
 197 escape_string (const gchar * string)
 198 {
 199   return escape_string_internal (string, UNSAFE_ALL);
 200 }
 201
 202 static int
 203 hex_to_int (gchar c)
 204 {
 205   return c >= '0' && c <= '9' ? c - '0'
 206       : c >= 'A' && c <= 'F' ? c - 'A' + 10
 207       : c >= 'a' && c <= 'f' ? c - 'a' + 10 : -1;
 208 }
 209
 210 static int
 211 unescape_character (const char *scanner)
 212 {
 213   int first_digit;
 214   int second_digit;
 215
 216   first_digit = hex_to_int (*scanner++);
 217   if (first_digit < 0) {
 218     return -1;
 219   }
 220
 221   second_digit = hex_to_int (*scanner);
 222   if (second_digit < 0) {
 223     return -1;
 224   }
 225
 226   return (first_digit << 4) | second_digit;
 227 }
 228
 229 /* unescape_string:
 230  * @escaped_string: an escaped URI, path, or other string
 231  * @illegal_characters: a string containing a sequence of characters
 232  * considered "illegal", '\0' is automatically in this list.
 233  *
 234  * Decodes escaped characters (i.e. PERCENTxx sequences) in @escaped_string.
 235  * Characters are encoded in PERCENTxy form, where xy is the ASCII hex code
 236  * for character 16x+y.
 237  *
 238  * Return value: a newly allocated string with the unescaped equivalents,
 239  * or %NULL if @escaped_string contained one of the characters
 240  * in @illegal_characters.
 241  **/
 242 static char *
 243 unescape_string (const gchar * escaped_string, const gchar * illegal_characters)
 244 {
 245   const gchar *in;
 246   gchar *out, *result;
 247   gint character;
 248
 249   if (escaped_string == NULL) {
 250     return NULL;
 251   }
 252
 253   result = g_malloc (strlen (escaped_string) + 1);
 254
 255   out = result;
 256   for (in = escaped_string; *in != '\0'; in++) {
 257     character = *in;
 258     if (*in == HEX_ESCAPE) {
 259       character = unescape_character (in + 1);
 260
 261       /* Check for an illegal character. We consider '\0' illegal here. */
 262       if (character <= 0
 263           || (illegal_characters != NULL
 264               && strchr (illegal_characters, (char) character) != NULL)) {
 265         g_free (result);
 266         return NULL;
 267       }
 268       in += 2;
 269     }
 270     *out++ = (char) character;
 271   }
 272
 273   *out = '\0';
 274   g_assert ((gsize) (out - result) <= strlen (escaped_string));
 275   return result;
 276
 277 }
 278
 279
 280 static void
 281 gst_uri_protocol_check_internal (const gchar * uri, gchar ** endptr)
 282 {
 283   gchar *check = (gchar *) uri;
 284
 285   g_assert (uri != NULL);
 286   g_assert (endptr != NULL);
 287
 288   if (g_ascii_isalpha (*check)) {
 289     check++;
 290     while (g_ascii_isalnum (*check) || *check == '+'
 291         || *check == '-' || *check == '.')
 292       check++;
 293   }
 294
 295   *endptr = check;
 296 }
 297
 298 /**
 299  * gst_uri_protocol_is_valid:
 300  * @protocol: A string
 301  *
 302  * Tests if the given string is a valid protocol identifier. Protocols
 303  * must consist of alphanumeric characters, '+', '-' and '.' and must
 304  * start with a alphabetic character. See RFC 3986 Section 3.1.
 305  *
 306  * Returns: TRUE if the string is a valid protocol identifier, FALSE otherwise.
 307  */
 308 gboolean
 309 gst_uri_protocol_is_valid (const gchar * protocol)
 310 {
 311   gchar *endptr;
 312
 313   g_return_val_if_fail (protocol != NULL, FALSE);
 314
 315   gst_uri_protocol_check_internal (protocol, &endptr);
 316
 317   return *endptr == '\0' && ((gsize) (endptr - protocol)) >= 3;
 318 }
 319
 320 /**
 321  * gst_uri_is_valid:
 322  * @uri: A URI string
 323  *
 324  * Tests if the given string is a valid URI identifier. URIs start with a valid
 325  * scheme followed by ":" and maybe a string identifying the location.
 326  *
 327  * Returns: TRUE if the string is a valid URI
 328  */
 329 gboolean
 330 gst_uri_is_valid (const gchar * uri)
 331 {
 332   gchar *endptr;
 333
 334   g_return_val_if_fail (uri != NULL, FALSE);
 335
 336   gst_uri_protocol_check_internal (uri, &endptr);
 337
 338   return *endptr == ':' && ((gsize) (endptr - uri)) >= 3;
 339 }
 340
 341 /**
 342  * gst_uri_get_protocol:
 343  * @uri: A URI string
 344  *
 345  * Extracts the protocol out of a given valid URI. The returned string must be
 346  * freed using g_free().
 347  *
 348  * Returns: The protocol for this URI.
 349  */
 350 gchar *
 351 gst_uri_get_protocol (const gchar * uri)
 352 {
 353   gchar *colon;
 354
 355   g_return_val_if_fail (uri != NULL, NULL);
 356   g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
 357
 358   colon = strstr (uri, ":");
 359
 360   return g_ascii_strdown (uri, colon - uri);
 361 }
 362
 363 /**
 364  * gst_uri_has_protocol:
 365  * @uri: a URI string
 366  * @protocol: a protocol string (e.g. "http")
 367  *
 368  * Checks if the protocol of a given valid URI matches @protocol.
 369  *
 370  * Returns: %TRUE if the protocol matches.
 371  *
 372  * Since: 0.10.4
 373  */
 374 gboolean
 375 gst_uri_has_protocol (const gchar * uri, const gchar * protocol)
 376 {
 377   gchar *colon;
 378
 379   g_return_val_if_fail (uri != NULL, FALSE);
 380   g_return_val_if_fail (protocol != NULL, FALSE);
 381   g_return_val_if_fail (gst_uri_is_valid (uri), FALSE);
 382
 383   colon = strstr (uri, ":");
 384
 385   if (colon == NULL)
 386     return FALSE;
 387
 388   return (g_ascii_strncasecmp (uri, protocol, (gsize) (colon - uri)) == 0);
 389 }
 390
 391 /**
 392  * gst_uri_get_location:
 393  * @uri: A URI string
 394  *
 395  * Extracts the location out of a given valid URI, ie. the protocol and "://"
 396  * are stripped from the URI, which means that the location returned includes
 397  * the hostname if one is specified. The returned string must be freed using
 398  * g_free().
 399  *
 400  * Free-function: g_free
 401  *
 402  * Returns: (transfer full) (array zero-terminated=1): the location for this
 403  *     URI. Returns NULL if the URI isn't valid. If the URI does not contain
 404  *     a location, an empty string is returned.
 405  */
 406 gchar *
 407 gst_uri_get_location (const gchar * uri)
 408 {
 409   const gchar *colon;
 410   gchar *unescaped = NULL;
 411
 412   g_return_val_if_fail (uri != NULL, NULL);
 413   g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
 414
 415   colon = strstr (uri, "://");
 416   if (!colon)
 417     return NULL;
 418
 419   unescaped = unescape_string (colon + 3, "/");
 420
 421   /* On Windows an URI might look like file:///c:/foo/bar.txt or
 422    * file:///c|/foo/bar.txt (some Netscape versions) and we want to
 423    * return c:/foo/bar.txt as location rather than /c:/foo/bar.txt.
 424    * Can't use g_filename_from_uri() here because it will only handle the
 425    * file:// protocol */
 426 #ifdef G_OS_WIN32
 427   if (unescaped != NULL && unescaped[0] == '/' &&
 428       g_ascii_isalpha (unescaped[1]) &&
 429       (unescaped[2] == ':' || unescaped[2] == '|')) {
 430     unescaped[2] = ':';
 431     g_memmove (unescaped, unescaped + 1, strlen (unescaped + 1) + 1);
 432   }
 433 #endif
 434
 435   GST_LOG ("extracted location '%s' from URI '%s'", GST_STR_NULL (unescaped),
 436       uri);
 437   return unescaped;
 438 }
 439
 440 /**
 441  * gst_uri_construct:
 442  * @protocol: Protocol for URI
 443  * @location: (array zero-terminated=1) (transfer none): Location for URI
 444  *
 445  * Constructs a URI for a given valid protocol and location.
 446  *
 447  * Free-function: g_free
 448  *
 449  * Returns: (transfer full) (array zero-terminated=1): a new string for this
 450  *     URI. Returns NULL if the given URI protocol is not valid, or the given
 451  *     location is NULL.
 452  */
 453 gchar *
 454 gst_uri_construct (const gchar * protocol, const gchar * location)
 455 {
 456   char *escaped, *proto_lowercase;
 457   char *retval;
 458
 459   g_return_val_if_fail (gst_uri_protocol_is_valid (protocol), NULL);
 460   g_return_val_if_fail (location != NULL, NULL);
 461
 462   proto_lowercase = g_ascii_strdown (protocol, -1);
 463   escaped = escape_string (location);
 464   retval = g_strdup_printf ("%s://%s", proto_lowercase, escaped);
 465   g_free (escaped);
 466   g_free (proto_lowercase);
 467
 468   return retval;
 469 }
 470
 471 typedef struct
 472 {
 473   GstURIType type;
 474   const gchar *protocol;
 475 }
 476 SearchEntry;
 477
 478 static gboolean
 479 search_by_entry (GstPluginFeature * feature, gpointer search_entry)
 480 {
 481   const gchar *const *protocols;
 482   GstElementFactory *factory;
 483   SearchEntry *entry = (SearchEntry *) search_entry;
 484
 485   if (!GST_IS_ELEMENT_FACTORY (feature))
 486     return FALSE;
 487   factory = GST_ELEMENT_FACTORY_CAST (feature);
 488
 489   if (factory->uri_type != entry->type)
 490     return FALSE;
 491
 492   protocols = gst_element_factory_get_uri_protocols (factory);
 493
 494   if (protocols == NULL) {
 495     g_warning ("Factory '%s' implements GstUriHandler interface but returned "
 496         "no supported protocols!", gst_plugin_feature_get_name (feature));
 497     return FALSE;
 498   }
 499
 500   while (*protocols != NULL) {
 501     if (g_ascii_strcasecmp (*protocols, entry->protocol) == 0)
 502       return TRUE;
 503     protocols++;
 504   }
 505   return FALSE;
 506 }
 507
 508 static gint
 509 sort_by_rank (GstPluginFeature * first, GstPluginFeature * second)
 510 {
 511   return gst_plugin_feature_get_rank (second) -
 512       gst_plugin_feature_get_rank (first);
 513 }
 514
 515 static GList *
 516 get_element_factories_from_uri_protocol (const GstURIType type,
 517     const gchar * protocol)
 518 {
 519   GList *possibilities;
 520   SearchEntry entry;
 521
 522   g_return_val_if_fail (protocol, NULL);
 523
 524   entry.type = type;
 525   entry.protocol = protocol;
 526   possibilities = gst_registry_feature_filter (gst_registry_get (),
 527       search_by_entry, FALSE, &entry);
 528
 529   return possibilities;
 530 }
 531
 532 /**
 533  * gst_uri_protocol_is_supported:
 534  * @type: Whether to check for a source or a sink
 535  * @protocol: Protocol that should be checked for (e.g. "http" or "smb")
 536  *
 537  * Checks if an element exists that supports the given URI protocol. Note
 538  * that a positive return value does not imply that a subsequent call to
 539  * gst_element_make_from_uri() is guaranteed to work.
 540  *
 541  * Returns: TRUE
 542  *
 543  * Since: 0.10.13
 544 */
 545 gboolean
 546 gst_uri_protocol_is_supported (const GstURIType type, const gchar * protocol)
 547 {
 548   GList *possibilities;
 549
 550   g_return_val_if_fail (protocol, FALSE);
 551
 552   possibilities = get_element_factories_from_uri_protocol (type, protocol);
 553
 554   if (possibilities) {
 555     g_list_free (possibilities);
 556     return TRUE;
 557   } else
 558     return FALSE;
 559 }
 560
 561 /**
 562  * gst_element_make_from_uri:
 563  * @type: Whether to create a source or a sink
 564  * @uri: URI to create an element for
 565  * @elementname: (allow-none): Name of created element, can be NULL.
 566  * @error: (allow-none): address where to store error information, or NULL.
 567  *
 568  * Creates an element for handling the given URI.
 569  *
 570  * Returns: (transfer full): a new element or NULL if none could be created
 571  */
 572 GstElement *
 573 gst_element_make_from_uri (const GstURIType type, const gchar * uri,
 574     const gchar * elementname, GError ** error)
 575 {
 576   GList *possibilities, *walk;
 577   gchar *protocol;
 578   GstElement *ret = NULL;
 579
 580   g_return_val_if_fail (gst_is_initialized (), NULL);
 581   g_return_val_if_fail (GST_URI_TYPE_IS_VALID (type), NULL);
 582   g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
 583   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 584
 585   GST_DEBUG ("type:%d, uri:%s, elementname:%s", type, uri, elementname);
 586
 587   protocol = gst_uri_get_protocol (uri);
 588   possibilities = get_element_factories_from_uri_protocol (type, protocol);
 589
 590   if (!possibilities) {
 591     GST_DEBUG ("No %s for URI '%s'", type == GST_URI_SINK ? "sink" : "source",
 592         uri);
 593     /* The error message isn't great, but we don't expect applications to
 594      * show that error to users, but call the missing plugins functions */
 595     g_set_error (error, GST_URI_ERROR, GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
 596         _("No URI handler for the %s protocol found"), protocol);
 597     g_free (protocol);
 598     return NULL;
 599   }
 600   g_free (protocol);
 601
 602   possibilities = g_list_sort (possibilities, (GCompareFunc) sort_by_rank);
 603   walk = possibilities;
 604   while (walk) {
 605     GstElementFactory *factory = walk->data;
 606     GError *uri_err = NULL;
 607
 608     ret = gst_element_factory_create (factory, elementname);
 609     if (ret != NULL) {
 610       GstURIHandler *handler = GST_URI_HANDLER (ret);
 611
 612       if (gst_uri_handler_set_uri (handler, uri, &uri_err))
 613         break;
 614
 615       GST_WARNING ("%s didn't accept URI '%s': %s", GST_OBJECT_NAME (ret), uri,
 616           uri_err->message);
 617
 618       if (error != NULL && *error == NULL)
 619         g_propagate_error (error, uri_err);
 620       else
 621         g_error_free (uri_err);
 622
 623       gst_object_unref (ret);
 624       ret = NULL;
 625     }
 626     walk = walk->next;
 627   }
 628   gst_plugin_feature_list_free (possibilities);
 629
 630   GST_LOG_OBJECT (ret, "created %s for URL '%s'",
 631       type == GST_URI_SINK ? "sink" : "source", uri);
 632
 633   /* if the first handler didn't work, but we found another one that works */
 634   if (ret != NULL)
 635     g_clear_error (error);
 636
 637   return ret;
 638 }
 639
 640 /**
 641  * gst_uri_handler_get_uri_type:
 642  * @handler: A #GstURIHandler.
 643  *
 644  * Gets the type of the given URI handler
 645  *
 646  * Returns: the #GstURIType of the URI handler.
 647  * Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly.
 648  */
 649 guint
 650 gst_uri_handler_get_uri_type (GstURIHandler * handler)
 651 {
 652   GstURIHandlerInterface *iface;
 653   guint ret;
 654
 655   g_return_val_if_fail (GST_IS_URI_HANDLER (handler), GST_URI_UNKNOWN);
 656
 657   iface = GST_URI_HANDLER_GET_INTERFACE (handler);
 658   g_return_val_if_fail (iface != NULL, GST_URI_UNKNOWN);
 659   g_return_val_if_fail (iface->get_type != NULL, GST_URI_UNKNOWN);
 660
 661   ret = iface->get_type (G_OBJECT_TYPE (handler));
 662   g_return_val_if_fail (GST_URI_TYPE_IS_VALID (ret), GST_URI_UNKNOWN);
 663
 664   return ret;
 665 }
 666
 667 /**
 668  * gst_uri_handler_get_protocols:
 669  * @handler: A #GstURIHandler.
 670  *
 671  * Gets the list of protocols supported by @handler. This list may not be
 672  * modified.
 673  *
 674  * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): the
 675  *     supported protocols. Returns NULL if the @handler isn't implemented
 676  *     properly, or the @handler doesn't support any protocols.
 677  */
 678 const gchar *const *
 679 gst_uri_handler_get_protocols (GstURIHandler * handler)
 680 {
 681   GstURIHandlerInterface *iface;
 682   const gchar *const *ret;
 683
 684   g_return_val_if_fail (GST_IS_URI_HANDLER (handler), NULL);
 685
 686   iface = GST_URI_HANDLER_GET_INTERFACE (handler);
 687   g_return_val_if_fail (iface != NULL, NULL);
 688   g_return_val_if_fail (iface->get_protocols != NULL, NULL);
 689
 690   ret = iface->get_protocols (G_OBJECT_TYPE (handler));
 691   g_return_val_if_fail (ret != NULL, NULL);
 692
 693   return ret;
 694 }
 695
 696 /**
 697  * gst_uri_handler_get_uri:
 698  * @handler: A #GstURIHandler
 699  *
 700  * Gets the currently handled URI.
 701  *
 702  * Returns: (transfer full): the URI currently handled by the @handler.
 703  *   Returns NULL if there are no URI currently handled. The
 704  *   returned string must be freed with g_free() when no longer needed.
 705  */
 706 gchar *
 707 gst_uri_handler_get_uri (GstURIHandler * handler)
 708 {
 709   GstURIHandlerInterface *iface;
 710   gchar *ret;
 711
 712   g_return_val_if_fail (GST_IS_URI_HANDLER (handler), NULL);
 713
 714   iface = GST_URI_HANDLER_GET_INTERFACE (handler);
 715   g_return_val_if_fail (iface != NULL, NULL);
 716   g_return_val_if_fail (iface->get_uri != NULL, NULL);
 717   ret = iface->get_uri (handler);
 718   if (ret != NULL)
 719     g_return_val_if_fail (gst_uri_is_valid (ret), NULL);
 720
 721   return ret;
 722 }
 723
 724 /**
 725  * gst_uri_handler_set_uri:
 726  * @handler: A #GstURIHandler
 727  * @uri: URI to set
 728  * @error: (allow-none): address where to store a #GError in case of
 729  *    an error, or NULL
 730  *
 731  * Tries to set the URI of the given handler.
 732  *
 733  * Returns: TRUE if the URI was set successfully, else FALSE.
 734  */
 735 gboolean
 736 gst_uri_handler_set_uri (GstURIHandler * handler, const gchar * uri,
 737     GError ** error)
 738 {
 739   GstURIHandlerInterface *iface;
 740   gboolean ret;
 741   gchar *new_uri, *protocol, *location, *colon;
 742
 743   g_return_val_if_fail (GST_IS_URI_HANDLER (handler), FALSE);
 744   g_return_val_if_fail (gst_uri_is_valid (uri), FALSE);
 745   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 746
 747   iface = GST_URI_HANDLER_GET_INTERFACE (handler);
 748   g_return_val_if_fail (iface != NULL, FALSE);
 749   g_return_val_if_fail (iface->set_uri != NULL, FALSE);
 750
 751   protocol = gst_uri_get_protocol (uri);
 752
 753   if (iface->get_protocols) {
 754     const gchar *const *protocols;
 755     const gchar *const *p;
 756     gboolean found_protocol = FALSE;
 757
 758     protocols = iface->get_protocols (G_OBJECT_TYPE (handler));
 759     if (protocols != NULL) {
 760       for (p = protocols; *p != NULL; ++p) {
 761         if (g_ascii_strcasecmp (protocol, *p) == 0) {
 762           found_protocol = TRUE;
 763           break;
 764         }
 765       }
 766
 767       if (!found_protocol) {
 768         g_set_error (error, GST_URI_ERROR, GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
 769             _("URI scheme '%s' not supported"), protocol);
 770         g_free (protocol);
 771         return FALSE;
 772       }
 773     }
 774   }
 775
 776   colon = strstr (uri, ":");
 777   location = g_strdup (colon);
 778
 779   new_uri = g_strdup_printf ("%s%s", protocol, location);
 780
 781   ret = iface->set_uri (handler, uri, error);
 782
 783   g_free (new_uri);
 784   g_free (location);
 785   g_free (protocol);
 786
 787   return ret;
 788 }
 789
 790 static gchar *
 791 gst_file_utils_canonicalise_path (const gchar * path)
 792 {
 793   gchar **parts, **p, *clean_path;
 794
 795 #ifdef G_OS_WIN32
 796   {
 797     GST_WARNING ("FIXME: canonicalise win32 path");
 798     return g_strdup (path);
 799   }
 800 #endif
 801
 802   parts = g_strsplit (path, "/", -1);
 803
 804   p = parts;
 805   while (*p != NULL) {
 806     if (strcmp (*p, ".") == 0) {
 807       /* just move all following parts on top of this, incl. NUL terminator */
 808       g_free (*p);
 809       g_memmove (p, p + 1, (g_strv_length (p + 1) + 1) * sizeof (gchar *));
 810       /* re-check the new current part again in the next iteration */
 811       continue;
 812     } else if (strcmp (*p, "..") == 0 && p > parts) {
 813       /* just move all following parts on top of the previous part, incl.
 814        * NUL terminator */
 815       g_free (*(p - 1));
 816       g_free (*p);
 817       g_memmove (p - 1, p + 1, (g_strv_length (p + 1) + 1) * sizeof (gchar *));
 818       /* re-check the new current part again in the next iteration */
 819       --p;
 820       continue;
 821     }
 822     ++p;
 823   }
 824   if (*path == '/') {
 825     guint num_parts;
 826
 827     num_parts = g_strv_length (parts) + 1;      /* incl. terminator */
 828     parts = g_renew (gchar *, parts, num_parts + 1);
 829     g_memmove (parts + 1, parts, num_parts * sizeof (gchar *));
 830     parts[0] = g_strdup ("/");
 831   }
 832
 833   clean_path = g_build_filenamev (parts);
 834   g_strfreev (parts);
 835   return clean_path;
 836 }
 837
 838 static gboolean
 839 file_path_contains_relatives (const gchar * path)
 840 {
 841   return (strstr (path, "/./") != NULL || strstr (path, "/../") != NULL ||
 842       strstr (path, G_DIR_SEPARATOR_S "." G_DIR_SEPARATOR_S) != NULL ||
 843       strstr (path, G_DIR_SEPARATOR_S ".." G_DIR_SEPARATOR_S) != NULL);
 844 }
 845
 846 /**
 847  * gst_filename_to_uri:
 848  * @filename: absolute or relative file name path
 849  * @error: pointer to error, or NULL
 850  *
 851  * Similar to g_filename_to_uri(), but attempts to handle relative file paths
 852  * as well. Before converting @filename into an URI, it will be prefixed by
 853  * the current working directory if it is a relative path, and then the path
 854  * will be canonicalised so that it doesn't contain any './' or '../' segments.
 855  *
 856  * On Windows #filename should be in UTF-8 encoding.
 857  *
 858  * Since: 0.10.33
 859  */
 860 gchar *
 861 gst_filename_to_uri (const gchar * filename, GError ** error)
 862 {
 863   gchar *abs_location = NULL;
 864   gchar *uri, *abs_clean;
 865
 866   g_return_val_if_fail (filename != NULL, NULL);
 867   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 868
 869   if (g_path_is_absolute (filename)) {
 870     if (!file_path_contains_relatives (filename)) {
 871       uri = g_filename_to_uri (filename, NULL, error);
 872       goto beach;
 873     }
 874
 875     abs_location = g_strdup (filename);
 876   } else {
 877     gchar *cwd;
 878
 879     cwd = g_get_current_dir ();
 880     abs_location = g_build_filename (cwd, filename, NULL);
 881     g_free (cwd);
 882
 883     if (!file_path_contains_relatives (abs_location)) {
 884       uri = g_filename_to_uri (abs_location, NULL, error);
 885       goto beach;
 886     }
 887   }
 888
 889   /* path is now absolute, but contains '.' or '..' */
 890   abs_clean = gst_file_utils_canonicalise_path (abs_location);
 891   GST_LOG ("'%s' -> '%s' -> '%s'", filename, abs_location, abs_clean);
 892   uri = g_filename_to_uri (abs_clean, NULL, error);
 893   g_free (abs_clean);
 894
 895 beach:
 896
 897   g_free (abs_location);
 898   GST_DEBUG ("'%s' -> '%s'", filename, uri);
 899   return uri;
 900 }