GLib Reference Manual: URI Functions

## URI Functions URI Functions — manipulating URIs |

## Functions

char * | g_uri_parse_scheme ()
char * | g_uri_escape_string ()
char * | g_uri_unescape_string ()
char * | g_uri_unescape_segment ()
gchar ** | g_uri_list_extract_uris ()
gchar * | g_filename_from_uri ()
gchar * | g_filename_to_uri ()

## Types and Values

#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

## Object Hierarchy

## Includes

    #include <glib.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`. | [allow-none]
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`. | [allow-none]

#### 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`. | [allow-none]
escaped_string_end | Pointer to end of `escaped_string` , may be `NULL`. | [allow-none]
illegal_characters | An optional string of illegal characters not to be allowed, may be `NULL`. | [allow-none]

#### 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, or `NULL`. If there is no hostname in the URI, `NULL` will be stored in this location. | [out][allow-none]
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 |
hostname | A UTF-8 encoded hostname, or `NULL` for none. | [allow-none]
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 "!$&'()*+,;=".