URI Functions

URI Functions — manipulating URIs

Functions

Types and Values

Includes

#include <glib.h>
#include <glib/gi18n.h>

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.

Functions

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:

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

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

Parameters

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.

Parameters

unescaped

the unescaped input string.

 

reserved_chars_allowed

a string of reserved characters that are allowed to be used, or NULL.

[nullable]

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.

Parameters

escaped_string

an escaped string to be unescaped.

 

illegal_characters

a string of illegal characters not to be allowed, or NULL.

[nullable]

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.

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.

Parameters

escaped_string

A string, may be NULL.

[nullable]

escaped_string_end

Pointer to end of escaped_string , may be NULL.

[nullable]

illegal_characters

An optional string of illegal characters not to be allowed, may be NULL.

[nullable]

Returns

an unescaped version of escaped_string or NULL on error. The returned string should be freed when no longer needed. As a special case if NULL is given for escaped_string , this function will return NULL.

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.

Parameters

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().

[transfer full]

Since: 2.6


g_filename_from_uri ()

gchar *
g_filename_from_uri (const gchar *uri,
                     gchar **hostname,
                     GError **error);

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

Parameters

uri

a uri describing a filename (escaped, encoded in ASCII).

 

hostname

Location to store hostname for the URI. If there is no hostname in the URI, NULL will be stored in this location.

[out][optional][nullable]

error

location to store the error occurring, 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.

[type filename]


g_filename_to_uri ()

gchar *
g_filename_to_uri (const gchar *filename,
                   const gchar *hostname,
                   GError **error);

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

Parameters

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.

[type filename]

hostname

A UTF-8 encoded hostname, or NULL for none.

[nullable]

error

location to store the error occurring, 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.

Types and Values

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 "!$&'()*+,;=".