URI Functions

URI Functions — URI Functions

Synopsis

#include <glib.h>

#define             G_URI_RESERVED_CHARS_ALLOWED_IN_PATH
#define             G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT
#define             G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO
#define             G_URI_RESERVED_CHARS_GENERIC_DELIMITERS
#define             G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS
char *              g_uri_parse_scheme                  (const char *uri);
char *              g_uri_escape_string                 (const char *unescaped,
                                                         const char *reserved_chars_allowed,
                                                         gboolean allow_utf8);
char *              g_uri_unescape_string               (const char *escaped_string,
                                                         const char *illegal_characters);
char *              g_uri_unescape_segment              (const char *escaped_string,
                                                         const char *escaped_string_end,
                                                         const char *illegal_characters);
gchar **            g_uri_list_extract_uris             (const gchar *uri_list);
#define             g_filename_from_uri
#define             g_filename_to_uri

Description

Functions for manipulating Universal Resource Identifiers (URIs) as defined by RFC 3986. It is highly recommended that you have read and understand RFC 3986 for understanding this API.

Details

G_URI_RESERVED_CHARS_ALLOWED_IN_PATH

#define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT "/"

Allowed characters in a path. Includes "!$&'()*+,;=:@/".

G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT

#define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":@"

Allowed characters in path elements. Includes "!$&'()*+,;=:@".

G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO

#define G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":"

Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:".

G_URI_RESERVED_CHARS_GENERIC_DELIMITERS

#define G_URI_RESERVED_CHARS_GENERIC_DELIMITERS ":/?#[]@"

Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@".

G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS

#define G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS "!$&'()*+,;="

Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=".

g_uri_parse_scheme ()

char *              g_uri_parse_scheme                  (const char *uri);

Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Common schemes include "file", "http", "svn+ssh", etc.

`uri` :	a valid URI.
Returns :	The "Scheme" component of the URI, or `NULL` on error. The returned string should be freed when no longer needed.

Since 2.16

g_uri_escape_string ()

char *              g_uri_escape_string                 (const char *unescaped,
                                                         const char *reserved_chars_allowed,
                                                         gboolean allow_utf8);

Escapes a string for use in a URI.

Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical characters plus dash, dot, underscore and tilde) are escaped. But if you specify characters in reserved_chars_allowed they are not escaped. This is useful for the "reserved" characters in the URI specification, since those are allowed unescaped in some portions of a URI.

`unescaped` :	the unescaped input string.
`reserved_chars_allowed` :	a string of reserved characters that are allowed to be used, or `NULL`.
`allow_utf8` :	`TRUE` if the result can include UTF-8 characters.
Returns :	an escaped version of `unescaped`. The returned string should be freed when no longer needed.

Since 2.16

g_uri_unescape_string ()

char *              g_uri_unescape_string               (const char *escaped_string,
                                                         const char *illegal_characters);

Unescapes a whole escaped string.

If any of the characters in illegal_characters or the character zero appears as an escaped character in escaped_string then that is an error and NULL will be returned. This is useful it you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling.

`escaped_string` :	an escaped string to be unescaped.
`illegal_characters` :	an optional string of illegal characters not to be allowed.
Returns :	an unescaped version of `escaped_string`. The returned string should be freed when no longer needed.

Since 2.16

g_uri_unescape_segment ()

char *              g_uri_unescape_segment              (const char *escaped_string,
                                                         const char *escaped_string_end,
                                                         const char *illegal_characters);

Unescapes a segment of an escaped string.

`escaped_string` :	a string.
`escaped_string_end` :	a string.
`illegal_characters` :	an optional string of illegal characters not to be allowed.
Returns :	an unescaped version of `escaped_string` or `NULL` on error. The returned string should be freed when no longer needed.

Since 2.16

g_uri_list_extract_uris ()

gchar **            g_uri_list_extract_uris             (const gchar *uri_list);

Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments. The URIs are not validated.

`uri_list` :	an URI list
Returns :	a newly allocated `NULL`-terminated list of strings holding the individual URIs. The array should be freed with `g_strfreev()`.

Since 2.6

g_filename_from_uri

#define             g_filename_from_uri

Converts an escaped ASCII-encoded URI to a local filename in the encoding used for filenames.

`uri` :	a uri describing a filename (escaped, encoded in ASCII).
`hostname` :	Location to store hostname for the URI, or `NULL`. If there is no hostname in the URI, `NULL` will be stored in this location.
`error` :	location to store the error occuring, or `NULL` to ignore errors. Any of the errors in GConvertError may occur.
Returns :	a newly-allocated string holding the resulting filename, or `NULL` on an error.

g_filename_to_uri

#define             g_filename_to_uri

Converts an absolute filename to an escaped ASCII-encoded URI, with the path component following Section 3.3. of RFC 2396.

`filename` :	an absolute filename specified in the GLib file name encoding, which is the on-disk file name bytes on Unix, and UTF-8 on Windows
`hostname` :	A UTF-8 encoded hostname, or `NULL` for none.
`error` :	location to store the error occuring, or `NULL` to ignore errors. Any of the errors in GConvertError may occur.
Returns :	a newly-allocated string holding the resulting URI, or `NULL` on an error.

			GLib Reference Manual
Top \| Description