2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gsturi.c: register URI handlers
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
27 #include "gst_private.h"
30 #include "gstregistrypool.h"
31 #include "gstmarshal.h"
35 GST_DEBUG_CATEGORY_STATIC (gst_uri_handler_debug);
36 #define GST_CAT_DEFAULT gst_uri_handler_debug
38 static void gst_uri_handler_base_init (gpointer g_class);
41 gst_uri_handler_get_type (void)
43 static GType urihandler_type = 0;
45 if (!urihandler_type) {
46 static const GTypeInfo urihandler_info = {
47 sizeof (GstURIHandlerInterface),
48 gst_uri_handler_base_init,
59 urihandler_type = g_type_register_static (G_TYPE_INTERFACE,
60 "GstURIHandler", &urihandler_info, 0);
62 GST_DEBUG_CATEGORY_INIT (gst_uri_handler_debug, "GST_URI", GST_DEBUG_BOLD,
65 return urihandler_type;
68 gst_uri_handler_base_init (gpointer g_class)
70 static gboolean initialized = FALSE;
73 g_signal_new ("new-uri", GST_TYPE_URI_HANDLER, G_SIGNAL_RUN_LAST,
74 G_STRUCT_OFFSET (GstURIHandlerInterface, new_uri), NULL, NULL,
75 gst_marshal_VOID__STRING, G_TYPE_NONE, 1, G_TYPE_STRING);
80 static const guchar acceptable[96] = { /* X0 X1 X2 X3 X4 X5 X6 X7 X8 X9 XA XB XC XD XE XF */
81 0x00, 0x3F, 0x20, 0x20, 0x20, 0x00, 0x2C, 0x3F, 0x3F, 0x3F, 0x3F, 0x22, 0x20, 0x3F, 0x3F, 0x1C, /* 2X !"#$%&'()*+,-./ */
82 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x38, 0x20, 0x20, 0x2C, 0x20, 0x2C, /* 3X 0123456789:;<=>? */
83 0x30, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, /* 4X @ABCDEFGHIJKLMNO */
84 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x20, 0x20, 0x20, 0x20, 0x3F, /* 5X PQRSTUVWXYZ[\]^_ */
85 0x20, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, /* 6X `abcdefghijklmno */
86 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x20, 0x20, 0x20, 0x3F, 0x20 /* 7X pqrstuvwxyz{|}~DEL */
91 UNSAFE_ALL = 0x1, /* Escape all unsafe characters */
92 UNSAFE_ALLOW_PLUS = 0x2, /* Allows '+' */
93 UNSAFE_PATH = 0x4, /* Allows '/' and '?' and '&' and '=' */
94 UNSAFE_DOS_PATH = 0x8, /* Allows '/' and '?' and '&' and '=' and ':' */
95 UNSAFE_HOST = 0x10, /* Allows '/' and ':' and '@' */
96 UNSAFE_SLASHES = 0x20 /* Allows all characters except for '/' and '%' */
99 #define HEX_ESCAPE '%'
101 /* Escape undesirable characters using %
102 * -------------------------------------
104 * This function takes a pointer to a string in which
105 * some characters may be unacceptable unescaped.
106 * It returns a string which has these characters
107 * represented by a '%' character followed by two hex digits.
109 * This routine returns a g_malloced string.
112 static const gchar hex[16] = "0123456789ABCDEF";
115 escape_string_internal (const gchar * string, UnsafeCharacterSet mask)
117 #define ACCEPTABLE_CHAR(a) ((a)>=32 && (a)<128 && (acceptable[(a)-32] & use_mask))
124 UnsafeCharacterSet use_mask;
126 g_return_val_if_fail (mask == UNSAFE_ALL
127 || mask == UNSAFE_ALLOW_PLUS
128 || mask == UNSAFE_PATH
129 || mask == UNSAFE_DOS_PATH
130 || mask == UNSAFE_HOST || mask == UNSAFE_SLASHES, NULL);
132 if (string == NULL) {
138 for (p = string; *p != '\0'; p++) {
140 if (!ACCEPTABLE_CHAR (c)) {
143 if ((use_mask == UNSAFE_HOST) && (unacceptable || (c == '/'))) {
144 /* when escaping a host, if we hit something that needs to be escaped, or we finally
145 * hit a path separator, revert to path mode (the host segment of the url is over).
147 use_mask = UNSAFE_PATH;
151 result = g_malloc (p - string + unacceptable * 2 + 1);
154 for (q = result, p = string; *p != '\0'; p++) {
157 if (!ACCEPTABLE_CHAR (c)) {
158 *q++ = HEX_ESCAPE; /* means hex coming */
164 if ((use_mask == UNSAFE_HOST) && (!ACCEPTABLE_CHAR (c) || (c == '/'))) {
165 use_mask = UNSAFE_PATH;
176 * @string: string to be escaped
178 * Escapes @string, replacing any and all special characters
179 * with equivalent escape sequences.
181 * Return value: a newly allocated string equivalent to @string
182 * but with all special characters escaped
185 escape_string (const gchar * string)
187 return escape_string_internal (string, UNSAFE_ALL);
193 return c >= '0' && c <= '9' ? c - '0'
194 : c >= 'A' && c <= 'F' ? c - 'A' + 10
195 : c >= 'a' && c <= 'f' ? c - 'a' + 10 : -1;
199 unescape_character (const char *scanner)
204 first_digit = hex_to_int (*scanner++);
205 if (first_digit < 0) {
209 second_digit = hex_to_int (*scanner++);
210 if (second_digit < 0) {
214 return (first_digit << 4) | second_digit;
219 * @escaped_string: an escaped URI, path, or other string
220 * @illegal_characters: a string containing a sequence of characters
221 * considered "illegal", '\0' is automatically in this list.
223 * Decodes escaped characters (i.e. PERCENTxx sequences) in @escaped_string.
224 * Characters are encoded in PERCENTxy form, where xy is the ASCII hex code
225 * for character 16x+y.
227 * Return value: a newly allocated string with the unescaped equivalents,
228 * or %NULL if @escaped_string contained one of the characters
229 * in @illegal_characters.
232 unescape_string (const gchar * escaped_string, const gchar * illegal_characters)
238 if (escaped_string == NULL) {
242 result = g_malloc (strlen (escaped_string) + 1);
245 for (in = escaped_string; *in != '\0'; in++) {
247 if (*in == HEX_ESCAPE) {
248 character = unescape_character (in + 1);
250 /* Check for an illegal character. We consider '\0' illegal here. */
252 || (illegal_characters != NULL
253 && strchr (illegal_characters, (char) character) != NULL)) {
259 *out++ = (char) character;
263 g_assert (out - result <= strlen (escaped_string));
270 gst_uri_protocol_check_internal (const gchar * uri, gchar ** endptr)
272 gchar *check = (gchar *) uri;
274 g_assert (uri != NULL);
275 g_assert (endptr != NULL);
277 if (g_ascii_isalpha (*check)) {
279 while (g_ascii_isalnum (*check))
287 * gst_uri_protocol_is_valid:
288 * @protocol: string to check
290 * Tests if the given string is a valid protocol identifier. Protocols
291 * must consist of alphanumeric characters and not start with a number.
293 * Returns: TRUE if the string is a valid protocol identifier
296 gst_uri_protocol_is_valid (const gchar * protocol)
300 g_return_val_if_fail (protocol != NULL, FALSE);
302 gst_uri_protocol_check_internal (protocol, &endptr);
304 return *endptr == '\0' && endptr != protocol;
309 * @uri: string to check
311 * Tests if the given string is a valid URI identifier. URIs start with a valid
312 * protocol followed by "://" and a string identifying the location.
314 * Returns: TRUE if the string is a valid URI
317 gst_uri_is_valid (const gchar * uri)
321 g_return_val_if_fail (uri != NULL, FALSE);
323 gst_uri_protocol_check_internal (uri, &endptr);
325 return (*endptr == ':' && *(endptr + 1) == '/' && *(endptr + 2) == '/');
329 * gst_uri_get_protocol:
330 * @uri: URI to get protocol from
332 * Extracts the protocol out of a given valid URI. The returned string must be
333 * freed using g_free().
335 * Returns: The protocol for this URI.
338 gst_uri_get_protocol (const gchar * uri)
342 g_return_val_if_fail (uri != NULL, NULL);
343 g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
345 colon = strstr (uri, "://");
347 return g_strndup (uri, colon - uri);
351 * gst_uri_get_location:
352 * @uri: URI to get the location from
354 * Extracts the location out of a given valid URI. So the protocol and "://"
355 * are stripped from the URI. The returned string must be freed using
358 * Returns: The location for this URI.
361 gst_uri_get_location (const gchar * uri)
364 gchar *location, *unescaped;
366 g_return_val_if_fail (uri != NULL, NULL);
367 g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
369 colon = strstr (uri, "://");
371 location = g_strdup (colon + 3);
373 unescaped = unescape_string (location, "/");
381 * @protocol: protocol for URI
382 * @location: location for URI
384 * Constructs a URI for a given valid protocol and location.
386 * Returns: a new string for this URI
389 gst_uri_construct (const gchar * protocol, const gchar * location)
394 g_return_val_if_fail (gst_uri_protocol_is_valid (protocol), NULL);
395 g_return_val_if_fail (location != NULL, NULL);
397 escaped = escape_string (location);
398 retval = g_strdup_printf ("%s://%s", protocol, escaped);
412 search_by_entry (GstPluginFeature * feature, gpointer search_entry)
415 GstElementFactory *factory;
416 SearchEntry *entry = (SearchEntry *) search_entry;
418 if (!GST_IS_ELEMENT_FACTORY (feature))
420 factory = GST_ELEMENT_FACTORY (feature);
422 if (gst_element_factory_get_uri_type (factory) != entry->type)
425 protocols = gst_element_factory_get_uri_protocols (factory);
426 /* must be set when uri type is valid */
427 g_assert (protocols);
428 while (*protocols != NULL) {
429 if (strcmp (*protocols, entry->protocol) == 0)
437 sort_by_rank (gconstpointer a, gconstpointer b)
439 GstPluginFeature *first = GST_PLUGIN_FEATURE (a);
440 GstPluginFeature *second = GST_PLUGIN_FEATURE (b);
442 return gst_plugin_feature_get_rank (second) -
443 gst_plugin_feature_get_rank (first);
447 * gst_element_make_from_uri:
448 * @type: wether to create a source or a sink
449 * @uri: URI to create element for
450 * @elementname: optional name of created element
452 * Creates an element for handling the given URI.
454 * Returns: a new element or NULL if none could be created
457 gst_element_make_from_uri (const GstURIType type, const gchar * uri,
458 const gchar * elementname)
460 GList *possibilities, *walk;
462 GstElement *ret = NULL;
464 g_return_val_if_fail (GST_URI_TYPE_IS_VALID (type), NULL);
465 g_return_val_if_fail (gst_uri_is_valid (uri), NULL);
468 entry.protocol = gst_uri_get_protocol (uri);
470 gst_registry_pool_feature_filter (search_by_entry, FALSE, &entry);
471 g_free (entry.protocol);
473 if (!possibilities) {
474 GST_DEBUG ("No %s for URI '%s'", type == GST_URI_SINK ? "sink" : "source",
479 possibilities = g_list_sort (possibilities, sort_by_rank);
480 walk = possibilities;
482 if ((ret = gst_element_factory_create (GST_ELEMENT_FACTORY (walk->data),
483 elementname)) != NULL) {
484 GstURIHandler *handler = GST_URI_HANDLER (ret);
486 if (gst_uri_handler_set_uri (handler, uri))
488 gst_object_unref (GST_OBJECT (ret));
493 g_list_free (possibilities);
495 GST_LOG_OBJECT (ret, "created %s for URL '%s'",
496 type == GST_URI_SINK ? "sink" : "source", uri);
501 * gst_uri_handler_get_uri_type:
502 * @handler: Handler to query type of
504 * Gets the type of a URI handler
506 * Returns: the type of the URI handler
509 gst_uri_handler_get_uri_type (GstURIHandler * handler)
511 GstURIHandlerInterface *iface;
514 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), GST_URI_UNKNOWN);
516 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
517 g_return_val_if_fail (iface != NULL, GST_URI_UNKNOWN);
518 g_return_val_if_fail (iface->get_type != NULL, GST_URI_UNKNOWN);
519 ret = iface->get_type ();
520 g_return_val_if_fail (GST_URI_TYPE_IS_VALID (ret), GST_URI_UNKNOWN);
526 * gst_uri_handler_get_protocols:
527 * @handler: Handler to get protocols for
529 * Gets the list of supported protocols for this handler. This list may not be
532 * Returns: the supported protocols
535 gst_uri_handler_get_protocols (GstURIHandler * handler)
537 GstURIHandlerInterface *iface;
540 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), NULL);
542 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
543 g_return_val_if_fail (iface != NULL, NULL);
544 g_return_val_if_fail (iface->get_protocols != NULL, NULL);
545 ret = iface->get_protocols ();
546 g_return_val_if_fail (ret != NULL, NULL);
552 * gst_uri_handler_get_uri:
553 * @handler: handler to query URI of
555 * Gets the currently handled URI of the handler or NULL, if none is set.
559 G_CONST_RETURN gchar *
560 gst_uri_handler_get_uri (GstURIHandler * handler)
562 GstURIHandlerInterface *iface;
565 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), NULL);
567 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
568 g_return_val_if_fail (iface != NULL, NULL);
569 g_return_val_if_fail (iface->get_uri != NULL, NULL);
570 ret = iface->get_uri (handler);
572 g_return_val_if_fail (gst_uri_is_valid (ret), NULL);
578 * gst_uri_handler_set_uri:
579 * @handler: handler to set URI of
582 * Tries to set the URI of the given handler and returns TRUE if it succeeded.
584 * Returns: TRUE, if the URI was set successfully
587 gst_uri_handler_set_uri (GstURIHandler * handler, const gchar * uri)
589 GstURIHandlerInterface *iface;
591 g_return_val_if_fail (GST_IS_URI_HANDLER (handler), FALSE);
592 g_return_val_if_fail (gst_uri_is_valid (uri), FALSE);
594 iface = GST_URI_HANDLER_GET_INTERFACE (handler);
595 g_return_val_if_fail (iface != NULL, FALSE);
596 g_return_val_if_fail (iface->set_uri != NULL, FALSE);
597 return iface->set_uri (handler, uri);
601 * gst_uri_handler_new_uri:
602 * @handler: handler with a new URI
603 * @uri: new URI or NULL if it was unset
605 * Emits the new-uri event for a given handler, when that handler has a new URI.
606 * This function should only be called by URI handlers themselves.
609 gst_uri_handler_new_uri (GstURIHandler * handler, const gchar * uri)
611 g_return_if_fail (GST_IS_URI_HANDLER (handler));
613 g_signal_emit_by_name (handler, "new-uri", uri);