1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: Alexander Larsson <alexl@redhat.com>
23 #include "gurifuncs.h"
25 #include <glib/gstrfuncs.h>
26 #include <glib/gmessages.h>
27 #include <glib/gstring.h>
28 #include <glib/gmem.h>
36 * @title: URI Functions
37 * @short_description: manipulating URIs
39 * Functions for manipulating Universal Resource Identifiers (URIs) as
40 * defined by <ulink url="http://www.ietf.org/rfc/rfc3986.txt">
41 * RFC 3986</ulink>. It is highly recommended that you have read and
42 * understand RFC 3986 for understanding this API.
46 unescape_character (const char *scanner)
51 first_digit = g_ascii_xdigit_value (*scanner++);
55 second_digit = g_ascii_xdigit_value (*scanner++);
59 return (first_digit << 4) | second_digit;
63 * g_uri_unescape_segment:
64 * @escaped_string: (allow-none): A string, may be %NULL
65 * @escaped_string_end: (allow-none): Pointer to end of @escaped_string, may be %NULL
66 * @illegal_characters: (allow-none): An optional string of illegal characters not to be allowed, may be %NULL
68 * Unescapes a segment of an escaped string.
70 * If any of the characters in @illegal_characters or the character zero appears
71 * as an escaped character in @escaped_string then that is an error and %NULL
72 * will be returned. This is useful it you want to avoid for instance having a
73 * slash being expanded in an escaped path element, which might confuse pathname
76 * Returns: an unescaped version of @escaped_string or %NULL on error.
77 * The returned string should be freed when no longer needed. As a
78 * special case if %NULL is given for @escaped_string, this function
84 g_uri_unescape_segment (const char *escaped_string,
85 const char *escaped_string_end,
86 const char *illegal_characters)
92 if (escaped_string == NULL)
95 if (escaped_string_end == NULL)
96 escaped_string_end = escaped_string + strlen (escaped_string);
98 result = g_malloc (escaped_string_end - escaped_string + 1);
101 for (in = escaped_string; in < escaped_string_end; in++)
109 if (escaped_string_end - in < 2)
111 /* Invalid escaped char (to short) */
116 character = unescape_character (in);
118 /* Check for an illegal character. We consider '\0' illegal here. */
119 if (character <= 0 ||
120 (illegal_characters != NULL &&
121 strchr (illegal_characters, (char)character) != NULL))
127 in++; /* The other char will be eaten in the loop header */
129 *out++ = (char)character;
138 * g_uri_unescape_string:
139 * @escaped_string: an escaped string to be unescaped.
140 * @illegal_characters: (allow-none): a string of illegal characters not to be
143 * Unescapes a whole escaped string.
145 * If any of the characters in @illegal_characters or the character zero appears
146 * as an escaped character in @escaped_string then that is an error and %NULL
147 * will be returned. This is useful it you want to avoid for instance having a
148 * slash being expanded in an escaped path element, which might confuse pathname
151 * Returns: an unescaped version of @escaped_string. The returned string
152 * should be freed when no longer needed.
157 g_uri_unescape_string (const char *escaped_string,
158 const char *illegal_characters)
160 return g_uri_unescape_segment (escaped_string, NULL, illegal_characters);
164 * g_uri_parse_scheme:
167 * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
169 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
171 * Common schemes include "file", "http", "svn+ssh", etc.
173 * Returns: The "Scheme" component of the URI, or %NULL on error.
174 * The returned string should be freed when no longer needed.
179 g_uri_parse_scheme (const char *uri)
184 g_return_val_if_fail (uri != NULL, NULL);
186 /* From RFC 3986 Decodes:
187 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
193 scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
196 if (!g_ascii_isalpha (*p))
206 if (!(g_ascii_isalnum(c) ||
213 return g_strndup (uri, p - uri - 1);
217 * g_uri_escape_string:
218 * @unescaped: the unescaped input string.
219 * @reserved_chars_allowed: (allow-none): a string of reserved characters that
220 * are allowed to be used, or %NULL.
221 * @allow_utf8: %TRUE if the result can include UTF-8 characters.
223 * Escapes a string for use in a URI.
225 * Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical
226 * characters plus dash, dot, underscore and tilde) are escaped.
227 * But if you specify characters in @reserved_chars_allowed they are not
228 * escaped. This is useful for the "reserved" characters in the URI
229 * specification, since those are allowed unescaped in some portions of
232 * Returns: an escaped version of @unescaped. The returned string should be
233 * freed when no longer needed.
238 g_uri_escape_string (const char *unescaped,
239 const char *reserved_chars_allowed,
244 g_return_val_if_fail (unescaped != NULL, NULL);
246 s = g_string_sized_new (strlen (unescaped) + 10);
248 g_string_append_uri_escaped (s, unescaped, reserved_chars_allowed, allow_utf8);
250 return g_string_free (s, FALSE);