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>
6 * gsturi.c: register URI handlers
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.
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.
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.
25 * SECTION:gsturihandler
26 * @short_description: Interface to ease URI handling in plugins.
28 * The URIHandler is an interface that is implemented by Source and Sink
29 * #GstElement to simplify then handling of URI.
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()).
35 * Source and Sink plugins should implement this interface when possible.
37 * Last reviewed on 2005-11-09 (0.9.4)
44 #include "gst_private.h"
47 #include "gstregistry.h"
49 #include "gst-i18n-lib.h"
53 GST_DEBUG_CATEGORY_STATIC (gst_uri_handler_debug);
54 #define GST_CAT_DEFAULT gst_uri_handler_debug
57 gst_uri_handler_get_type (void)
59 static volatile gsize urihandler_type = 0;
61 if (g_once_init_enter (&urihandler_type)) {
63 static const GTypeInfo urihandler_info = {
64 sizeof (GstURIHandlerInterface),
76 _type = g_type_register_static (G_TYPE_INTERFACE,
77 "GstURIHandler", &urihandler_info, 0);
79 GST_DEBUG_CATEGORY_INIT (gst_uri_handler_debug, "GST_URI", GST_DEBUG_BOLD,
81 g_once_init_leave (&urihandler_type, _type);
83 return urihandler_type;
87 gst_uri_error_quark (void)
89 return g_quark_from_static_string ("gst-uri-error-quark");
92 static const guchar acceptable[96] = { /* X0 X1 X2 X3 X4 X5 X6 X7 X8 X9 XA XB XC XD XE XF */
93 0x00, 0x3F, 0x20, 0x20, 0x20, 0x00, 0x2C, 0x3F, 0x3F, 0x3F, 0x3F, 0x22, 0x20, 0x3F, 0x3F, 0x1C, /* 2X !"#$%&'()*+,-./ */
94 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x38, 0x20, 0x20, 0x2C, 0x20, 0x2C, /* 3X 0123456789:;<=>? */
95 0x30, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, /* 4X @ABCDEFGHIJKLMNO */
96 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x20, 0x20, 0x20, 0x20, 0x3F, /* 5X PQRSTUVWXYZ[\]^_ */
97 0x20, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, /* 6X `abcdefghijklmno */
98 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x20, 0x20, 0x20, 0x3F, 0x20 /* 7X pqrstuvwxyz{|}~DEL */
103 UNSAFE_ALL = 0x1, /* Escape all unsafe characters */
104 UNSAFE_ALLOW_PLUS = 0x2, /* Allows '+' */
105 UNSAFE_PATH = 0x4, /* Allows '/' and '?' and '&' and '=' */
106 UNSAFE_DOS_PATH = 0x8, /* Allows '/' and '?' and '&' and '=' and ':' */
107 UNSAFE_HOST = 0x10, /* Allows '/' and ':' and '@' */
108 UNSAFE_SLASHES = 0x20 /* Allows all characters except for '/' and '%' */
109 } UnsafeCharacterSet;
111 #define HEX_ESCAPE '%'
113 /* Escape undesirable characters using %
114 * -------------------------------------
116 * This function takes a pointer to a string in which
117 * some characters may be unacceptable unescaped.
118 * It returns a string which has these characters
119 * represented by a '%' character followed by two hex digits.
121 * This routine returns a g_malloced string.
124 static const gchar hex[16] = "0123456789ABCDEF";
127 escape_string_internal (const gchar * string, UnsafeCharacterSet mask)
129 #define ACCEPTABLE_CHAR(a) ((a)>=32 && (a)<128 && (acceptable[(a)-32] & use_mask))
136 UnsafeCharacterSet use_mask;
138 g_return_val_if_fail (mask == UNSAFE_ALL
139 || mask == UNSAFE_ALLOW_PLUS
140 || mask == UNSAFE_PATH
141 || mask == UNSAFE_DOS_PATH
142 || mask == UNSAFE_HOST || mask == UNSAFE_SLASHES, NULL);
144 if (string == NULL) {
150 for (p = string; *p != '\0'; p++) {
152 if (!ACCEPTABLE_CHAR (c)) {
155 if ((use_mask == UNSAFE_HOST) && (unacceptable || (c == '/'))) {
156 /* when escaping a host, if we hit something that needs to be escaped, or we finally
157 * hit a path separator, revert to path mode (the host segment of the url is over).
159 use_mask = UNSAFE_PATH;
163 result = g_malloc (p - string + unacceptable * 2 + 1);
166 for (q = result, p = string; *p != '\0'; p++) {
169 if (!ACCEPTABLE_CHAR (c)) {
170 *q++ = HEX_ESCAPE; /* means hex coming */
176 if ((use_mask == UNSAFE_HOST) && (!ACCEPTABLE_CHAR (c) || (c == '/'))) {
177 use_mask = UNSAFE_PATH;
187 * @string: string to be escaped
189 * Escapes @string, replacing any and all special characters
190 * with equivalent escape sequences.
192 * Return value: a newly allocated string equivalent to @string
193 * but with all special characters escaped
196 escape_string (const gchar * string)
198 return escape_string_internal (string, UNSAFE_ALL);
204 return c >= '0' && c <= '9' ? c - '0'
205 : c >= 'A' && c <= 'F' ? c - 'A' + 10
206 : c >= 'a' && c <= 'f' ? c - 'a' + 10 : -1;
210 unescape_character (const char *scanner)
215 first_digit = hex_to_int (*scanner++);
216 if (first_digit < 0) {
220 second_digit = hex_to_int (*scanner);
221 if (second_digit < 0) {
225 return (first_digit << 4) | second_digit;
229 * @escaped_string: an escaped URI, path, or other string
230 * @illegal_characters: a string containing a sequence of characters
231 * considered "illegal", '\0' is automatically in this list.
233 * Decodes escaped characters (i.e. PERCENTxx sequences) in @escaped_string.
234 * Characters are encoded in PERCENTxy form, where xy is the ASCII hex code
235 * for character 16x+y.
237 * Return value: a newly allocated string with the unescaped equivalents,
238 * or %NULL if @escaped_string contained one of the characters
239 * in @illegal_characters.
242 unescape_string (const gchar * escaped_string, const gchar * illegal_characters)
248 if (escaped_string == NULL) {
252 result = g_malloc (strlen (escaped_string) + 1);
255 for (in = escaped_string; *in != '\0'; in++) {
257 if (*in == HEX_ESCAPE) {
258 character = unescape_character (in + 1);
260 /* Check for an illegal character. We consider '\0' illegal here. */
262 || (illegal_characters != NULL
263 && strchr (illegal_characters, (char) character) != NULL)) {
269 *out++ = (char) character;
273 g_assert ((gsize) (out - result) <= strlen (escaped_string));
280 gst_uri_protocol_check_internal (const gchar * uri, gchar ** endptr)
282 gchar *check = (gchar *) uri;
284 g_assert (uri != NULL);
285 g_assert (endptr != NULL);
287 if (g_ascii_isalpha (*check)) {
289 while (g_ascii_isalnum (*check) || *check == '+'
290 || *check == '-' || *check == '.')
298 * gst_uri_protocol_is_valid:
299 * @protocol: A string
301 * Tests if the given string is a valid protocol identifier. Protocols
302 * must consist of alphanumeric characters, '+', '-' and '.' and must
303 * start with a alphabetic character. See RFC 3986 Section 3.1.
305 * Returns: TRUE if the string is a valid protocol identifier, FALSE otherwise.
308 gst_uri_protocol_is_valid (const gchar * protocol)
312 g_return_val_if_fail (protocol != NULL, FALSE);
314 gst_uri_protocol_check_internal (protocol, &endptr);
316 return *endptr == '\0' && endptr != protocol;
323 * Tests if the given string is a valid URI identifier. URIs start with a valid
324 * scheme followed by ":" and maybe a string identifying the location.
326 * Returns: TRUE if the string is a valid URI
329 gst_uri_is_valid (const gchar * uri)
333 g_return_val_if_fail (uri != NULL, FALSE);
335 gst_uri_protocol_check_internal (uri, &endptr);
337 return *endptr == ':';
341 * gst_uri_get_protocol:
344 * Extracts the protocol out of a given valid URI. The returned string must be
345 * freed using g_free().
347 * Returns: The protocol for this URI.
350 gst_uri_get_protocol (const gchar * uri)
354 g_return_val_if_fail (uri != NULL, NULL);
355 g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
357 colon = strstr (uri, ":");
359 return g_ascii_strdown (uri, colon - uri);
363 * gst_uri_has_protocol:
365 * @protocol: a protocol string (e.g. "http")
367 * Checks if the protocol of a given valid URI matches @protocol.
369 * Returns: %TRUE if the protocol matches.
374 gst_uri_has_protocol (const gchar * uri, const gchar * protocol)
378 g_return_val_if_fail (uri != NULL, FALSE);
379 g_return_val_if_fail (protocol != NULL, FALSE);
380 g_return_val_if_fail (gst_uri_is_valid (uri), FALSE);
382 colon = strstr (uri, ":");
387 return (g_ascii_strncasecmp (uri, protocol, (gsize) (colon - uri)) == 0);
391 * gst_uri_get_location:
394 * Extracts the location out of a given valid URI, ie. the protocol and "://"
395 * are stripped from the URI, which means that the location returned includes
396 * the hostname if one is specified. The returned string must be freed using
399 * Free-function: g_free
401 * Returns: (transfer full) (array zero-terminated=1): the location for this
402 * URI. Returns NULL if the URI isn't valid. If the URI does not contain
403 * a location, an empty string is returned.
406 gst_uri_get_location (const gchar * uri)
409 gchar *unescaped = NULL;
411 g_return_val_if_fail (uri != NULL, NULL);
412 g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
414 colon = strstr (uri, "://");
418 unescaped = unescape_string (colon + 3, "/");
420 /* On Windows an URI might look like file:///c:/foo/bar.txt or
421 * file:///c|/foo/bar.txt (some Netscape versions) and we want to
422 * return c:/foo/bar.txt as location rather than /c:/foo/bar.txt.
423 * Can't use g_filename_from_uri() here because it will only handle the
424 * file:// protocol */
426 if (unescaped != NULL && unescaped[0] == '/' &&
427 g_ascii_isalpha (unescaped[1]) &&
428 (unescaped[2] == ':' || unescaped[2] == '|')) {
430 g_memmove (unescaped, unescaped + 1, strlen (unescaped + 1) + 1);
434 GST_LOG ("extracted location '%s' from URI '%s'", GST_STR_NULL (unescaped),
441 * @protocol: Protocol for URI
442 * @location: (array zero-terminated=1) (transfer none): Location for URI
444 * Constructs a URI for a given valid protocol and location.
446 * Free-function: g_free
448 * Returns: (transfer full) (array zero-terminated=1): a new string for this
449 * URI. Returns NULL if the given URI protocol is not valid, or the given
453 gst_uri_construct (const gchar * protocol, const gchar * location)
455 char *escaped, *proto_lowercase;
458 g_return_val_if_fail (gst_uri_protocol_is_valid (protocol), NULL);
459 g_return_val_if_fail (location != NULL, NULL);
461 proto_lowercase = g_ascii_strdown (protocol, -1);
462 escaped = escape_string (location);
463 retval = g_strdup_printf ("%s://%s", proto_lowercase, escaped);
465 g_free (proto_lowercase);
473 const gchar *protocol;
478 search_by_entry (GstPluginFeature * feature, gpointer search_entry)
480 const gchar *const *protocols;
481 GstElementFactory *factory;
482 SearchEntry *entry = (SearchEntry *) search_entry;
484 if (!GST_IS_ELEMENT_FACTORY (feature))
486 factory = GST_ELEMENT_FACTORY_CAST (feature);
488 if (factory->uri_type != entry->type)
491 protocols = gst_element_factory_get_uri_protocols (factory);
493 if (protocols == NULL) {
494 g_warning ("Factory '%s' implements GstUriHandler interface but returned "
495 "no supported protocols!", gst_plugin_feature_get_name (feature));
499 while (*protocols != NULL) {
500 if (g_ascii_strcasecmp (*protocols, entry->protocol) == 0)
508 sort_by_rank (GstPluginFeature * first, GstPluginFeature * second)
510 return gst_plugin_feature_get_rank (second) -
511 gst_plugin_feature_get_rank (first);
515 get_element_factories_from_uri_protocol (const GstURIType type,
516 const gchar * protocol)
518 GList *possibilities;
521 g_return_val_if_fail (protocol, NULL);
524 entry.protocol = protocol;
525 possibilities = gst_registry_feature_filter (gst_registry_get (),
526 search_by_entry, FALSE, &entry);
528 return possibilities;
532 * gst_uri_protocol_is_supported:
533 * @type: Whether to check for a source or a sink
534 * @protocol: Protocol that should be checked for (e.g. "http" or "smb")
536 * Checks if an element exists that supports the given URI protocol. Note
537 * that a positive return value does not imply that a subsequent call to
538 * gst_element_make_from_uri() is guaranteed to work.
545 gst_uri_protocol_is_supported (const GstURIType type, const gchar * protocol)
547 GList *possibilities;
549 g_return_val_if_fail (protocol, FALSE);
551 possibilities = get_element_factories_from_uri_protocol (type, protocol);
554 g_list_free (possibilities);
561 * gst_element_make_from_uri:
562 * @type: Whether to create a source or a sink
563 * @uri: URI to create an element for
564 * @elementname: (allow-none): Name of created element, can be NULL.
566 * Creates an element for handling the given URI.
568 * Returns: (transfer full): a new element or NULL if none could be created
571 gst_element_make_from_uri (const GstURIType type, const gchar * uri,
572 const gchar * elementname)
574 GList *possibilities, *walk;
576 GstElement *ret = NULL;
578 g_return_val_if_fail (GST_URI_TYPE_IS_VALID (type), NULL);
579 g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
581 protocol = gst_uri_get_protocol (uri);
582 possibilities = get_element_factories_from_uri_protocol (type, protocol);
585 if (!possibilities) {
586 GST_DEBUG ("No %s for URI '%s'", type == GST_URI_SINK ? "sink" : "source",
591 possibilities = g_list_sort (possibilities, (GCompareFunc) sort_by_rank);
592 walk = possibilities;
595 gst_element_factory_create (GST_ELEMENT_FACTORY_CAST (walk->data),
596 elementname)) != NULL) {
597 GstURIHandler *handler = GST_URI_HANDLER (ret);
599 if (gst_uri_handler_set_uri (handler, uri, NULL))
601 gst_object_unref (ret);
606 gst_plugin_feature_list_free (possibilities);
608 GST_LOG_OBJECT (ret, "created %s for URL '%s'",
609 type == GST_URI_SINK ? "sink" : "source", uri);
614 * gst_uri_handler_get_uri_type:
615 * @handler: A #GstURIHandler.
617 * Gets the type of the given URI handler
619 * Returns: the #GstURIType of the URI handler.
620 * Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly.
623 gst_uri_handler_get_uri_type (GstURIHandler * handler)
625 GstURIHandlerInterface *iface;
628 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), GST_URI_UNKNOWN);
630 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
631 g_return_val_if_fail (iface != NULL, GST_URI_UNKNOWN);
632 g_return_val_if_fail (iface->get_type != NULL, GST_URI_UNKNOWN);
634 ret = iface->get_type (G_OBJECT_TYPE (handler));
635 g_return_val_if_fail (GST_URI_TYPE_IS_VALID (ret), GST_URI_UNKNOWN);
641 * gst_uri_handler_get_protocols:
642 * @handler: A #GstURIHandler.
644 * Gets the list of protocols supported by @handler. This list may not be
647 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): the
648 * supported protocols. Returns NULL if the @handler isn't implemented
649 * properly, or the @handler doesn't support any protocols.
652 gst_uri_handler_get_protocols (GstURIHandler * handler)
654 GstURIHandlerInterface *iface;
655 const gchar *const *ret;
657 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), NULL);
659 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
660 g_return_val_if_fail (iface != NULL, NULL);
661 g_return_val_if_fail (iface->get_protocols != NULL, NULL);
663 ret = iface->get_protocols (G_OBJECT_TYPE (handler));
664 g_return_val_if_fail (ret != NULL, NULL);
670 * gst_uri_handler_get_uri:
671 * @handler: A #GstURIHandler
673 * Gets the currently handled URI.
675 * Returns: (transfer full): the URI currently handled by the @handler.
676 * Returns NULL if there are no URI currently handled. The
677 * returned string must be freed with g_free() when no longer needed.
680 gst_uri_handler_get_uri (GstURIHandler * handler)
682 GstURIHandlerInterface *iface;
685 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), NULL);
687 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
688 g_return_val_if_fail (iface != NULL, NULL);
689 g_return_val_if_fail (iface->get_uri != NULL, NULL);
690 ret = iface->get_uri (handler);
692 g_return_val_if_fail (gst_uri_is_valid (ret), NULL);
698 * gst_uri_handler_set_uri:
699 * @handler: A #GstURIHandler
701 * @error: (allow-none): address where to store a #GError in case of
704 * Tries to set the URI of the given handler.
706 * Returns: TRUE if the URI was set successfully, else FALSE.
709 gst_uri_handler_set_uri (GstURIHandler * handler, const gchar * uri,
712 GstURIHandlerInterface *iface;
714 gchar *new_uri, *protocol, *location, *colon;
716 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), FALSE);
717 g_return_val_if_fail (gst_uri_is_valid (uri), FALSE);
718 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
720 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
721 g_return_val_if_fail (iface != NULL, FALSE);
722 g_return_val_if_fail (iface->set_uri != NULL, FALSE);
724 protocol = gst_uri_get_protocol (uri);
726 if (iface->get_protocols) {
727 const gchar *const *protocols;
728 const gchar *const *p;
729 gboolean found_protocol = FALSE;
731 protocols = iface->get_protocols (G_OBJECT_TYPE (handler));
732 if (protocols != NULL) {
733 for (p = protocols; *p != NULL; ++p) {
734 if (g_ascii_strcasecmp (protocol, *p) == 0) {
735 found_protocol = TRUE;
740 if (!found_protocol) {
741 g_set_error (error, GST_URI_ERROR, GST_URI_ERROR_BAD_PROTOCOL,
742 _("URI scheme '%s' not supported"), protocol);
749 colon = strstr (uri, ":");
750 location = g_strdup (colon);
752 new_uri = g_strdup_printf ("%s%s", protocol, location);
754 ret = iface->set_uri (handler, uri, error);
764 gst_file_utils_canonicalise_path (const gchar * path)
766 gchar **parts, **p, *clean_path;
770 GST_WARNING ("FIXME: canonicalise win32 path");
771 return g_strdup (path);
775 parts = g_strsplit (path, "/", -1);
779 if (strcmp (*p, ".") == 0) {
780 /* just move all following parts on top of this, incl. NUL terminator */
782 g_memmove (p, p + 1, (g_strv_length (p + 1) + 1) * sizeof (gchar *));
783 /* re-check the new current part again in the next iteration */
785 } else if (strcmp (*p, "..") == 0 && p > parts) {
786 /* just move all following parts on top of the previous part, incl.
790 g_memmove (p - 1, p + 1, (g_strv_length (p + 1) + 1) * sizeof (gchar *));
791 /* re-check the new current part again in the next iteration */
800 num_parts = g_strv_length (parts) + 1; /* incl. terminator */
801 parts = g_renew (gchar *, parts, num_parts + 1);
802 g_memmove (parts + 1, parts, num_parts * sizeof (gchar *));
803 parts[0] = g_strdup ("/");
806 clean_path = g_build_filenamev (parts);
812 file_path_contains_relatives (const gchar * path)
814 return (strstr (path, "/./") != NULL || strstr (path, "/../") != NULL ||
815 strstr (path, G_DIR_SEPARATOR_S "." G_DIR_SEPARATOR_S) != NULL ||
816 strstr (path, G_DIR_SEPARATOR_S ".." G_DIR_SEPARATOR_S) != NULL);
820 * gst_filename_to_uri:
821 * @filename: absolute or relative file name path
822 * @error: pointer to error, or NULL
824 * Similar to g_filename_to_uri(), but attempts to handle relative file paths
825 * as well. Before converting @filename into an URI, it will be prefixed by
826 * the current working directory if it is a relative path, and then the path
827 * will be canonicalised so that it doesn't contain any './' or '../' segments.
829 * On Windows #filename should be in UTF-8 encoding.
834 gst_filename_to_uri (const gchar * filename, GError ** error)
836 gchar *abs_location = NULL;
837 gchar *uri, *abs_clean;
839 g_return_val_if_fail (filename != NULL, NULL);
840 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
842 if (g_path_is_absolute (filename)) {
843 if (!file_path_contains_relatives (filename)) {
844 uri = g_filename_to_uri (filename, NULL, error);
848 abs_location = g_strdup (filename);
852 cwd = g_get_current_dir ();
853 abs_location = g_build_filename (cwd, filename, NULL);
856 if (!file_path_contains_relatives (abs_location)) {
857 uri = g_filename_to_uri (abs_location, NULL, error);
862 /* path is now absolute, but contains '.' or '..' */
863 abs_clean = gst_file_utils_canonicalise_path (abs_location);
864 GST_LOG ("'%s' -> '%s' -> '%s'", filename, abs_location, abs_clean);
865 uri = g_filename_to_uri (abs_clean, NULL, error);
870 g_free (abs_location);
871 GST_DEBUG ("'%s' -> '%s'", filename, uri);