URI Functions

## 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);

## 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. A copy of RFC 3986 can be found at http://www.ietf.org/rfc/rfc3986.txt.

## 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.
`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.

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` : | 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