URI

## URI URI — Uniform Resource Identifier (URI) |

## Synopsis

    #include <gnet.h>

                        GURI;
    GURI*               gnet_uri_new                        (const gchar *uri);
    GURI*               gnet_uri_new_fields                 (const gchar *scheme,
                                                             const gchar *hostname,
                                                             const gint port,
                                                             const gchar *path);
    GURI*               gnet_uri_new_fields_all             (const gchar *scheme,
                                                             const gchar *userinfo,
                                                             const gchar *hostname,
                                                             const gint port,
                                                             const gchar *path,
                                                             const gchar *query,
                                                             const gchar *fragment);
    GURI*               gnet_uri_clone                      (const GURI *uri);
    void                gnet_uri_delete                     (GURI *uri);
    void                gnet_uri_escape                     (GURI *uri);
    void                gnet_uri_unescape                   (GURI *uri);
    gchar*              gnet_uri_get_string                 (const GURI *uri);
    void                gnet_uri_set_scheme                 (GURI *uri,
                                                             const gchar *scheme);
    void                gnet_uri_set_userinfo               (GURI *uri,
                                                             const gchar *userinfo);
    void                gnet_uri_set_hostname               (GURI *uri,
                                                             const gchar *hostname);
    void                gnet_uri_set_port                   (GURI *uri,
                                                             gint port);
    void                gnet_uri_set_path                   (GURI *uri,
                                                             const gchar *path);
    void                gnet_uri_set_query                  (GURI *uri,
                                                             const gchar *query);
    void                gnet_uri_set_fragment               (GURI *uri,
                                                             const gchar *fragment);
    guint               gnet_uri_hash                       (gconstpointer p);
    gboolean            gnet_uri_equal                      (gconstpointer p1,
                                                             gconstpointer p2);
    gboolean            gnet_uri_parse_inplace              (GURI *guri,
                                                             gchar *uri,
                                                             gchar *hostname,
                                                             gsize len);

## Description

A URI is a Uniform Resource Identifier, similar to a URL. This module provides functions for creating and manipulating URIs. A URI is represented by GURI. All fields in the GURI structure are publicly readable.

Create a URI from a string by calling `gnet_uri_new()`. To get the string representation back, call `gnet_uri_get_string()`. To escape a URI call `gnet_uri_escape()`, and to unescape it call `gnet_uri_unescape()`. Network protocols use escaped URIs. People use unescaped URIs.

## Details

### GURI

    typedef struct {
      gchar* scheme;
      gchar* userinfo;
      gchar* hostname;
      gint   port;
      gchar* path;
      gchar* query;
      gchar* fragment;
    } GURI;

The GURI structure represents a URI. All fields in this structure are publicly readable.

gchar *`scheme`; | Scheme (or protocol)
gchar *`userinfo`; | User info
gchar *`hostname`; | Host name
gint `port`; | Port number
gchar *`path`; | Path
gchar *`query`; | Query
gchar *`fragment`; | Fragment

### gnet_uri_new ()

    GURI*               gnet_uri_new                        (const gchar *uri);

Creates a GURI from a string. Empty fields are set to NULL. The parser does not validate the URI -- it will accept some malformed URI. URIs are usually in the form scheme://userinfo`hostname`:port/path?queryfragment

URIs created from user input are typically unescaped. URIs created from machine input (e.g. received over the internet) are typically escaped.

`uri` : | URI string
Returns : | a new GURI, or NULL if there was a failure.

### gnet_uri_new_fields ()

    GURI*               gnet_uri_new_fields                 (const gchar *scheme,
                                                             const gchar *hostname,
                                                             const gint port,
                                                             const gchar *path);

Creates a GURI from the fields. This function uses the most common fields. Use `gnet_uri_new_fields_all()` to specify all fields.

`scheme` : | scheme
`hostname` : | host name
`port` : | port
`path` : | path
Returns : | a new GURI.

### gnet_uri_new_fields_all ()

    GURI*               gnet_uri_new_fields_all             (const gchar *scheme,
                                                             const gchar *userinfo,
                                                             const gchar *hostname,
                                                             const gint port,
                                                             const gchar *path,
                                                             const gchar *query,
                                                             const gchar *fragment);

Creates a GURI from all fields.

`scheme` : | scheme
`userinfo` : | user info
`hostname` : | host name
`port` : | port
`path` : | path
`query` : | query
`fragment` : | fragment
Returns : | a new GURI.

### gnet_uri_clone ()

    GURI*               gnet_uri_clone                      (const GURI *uri);

Copies a GURI.

`uri` : | a GURI
Returns : | a copy of `uri`.

### gnet_uri_delete ()

    void                gnet_uri_delete                     (GURI *uri);

Deletes a GURI.

`uri` : | a GURI

### gnet_uri_escape ()

    void                gnet_uri_escape                     (GURI *uri);

Escapes the fields in a GURI. Network protocols use escaped URIs. People use unescaped URIs.

`uri` : | a GURI

### gnet_uri_unescape ()

    void                gnet_uri_unescape                   (GURI *uri);

Unescapes the fields in the URI. Network protocols use escaped URIs. People use unescaped URIs.

`uri` : | a GURI

### gnet_uri_get_string ()

    gchar*              gnet_uri_get_string                 (const GURI *uri);

Gets a string representation of a GURI. This function does not escape or unescape the fields first. Call `gnet_uri_escape()` or gnet_uri_unescape first if necessary.

`uri` : | a GURI
Returns : | a string.

### gnet_uri_set_scheme ()

    void                gnet_uri_set_scheme                 (GURI *uri,
                                                             const gchar *scheme);

Sets a GURI's scheme.

`uri` : | a GURI
`scheme` : | scheme

### gnet_uri_set_userinfo ()

    void                gnet_uri_set_userinfo               (GURI *uri,
                                                             const gchar *userinfo);

Sets a GURI's user info.

`uri` : | a GURI
`userinfo` : | user info

### gnet_uri_set_hostname ()

    void                gnet_uri_set_hostname               (GURI *uri,
                                                             const gchar *hostname);

Sets a GURI's host name.

`uri` : | a GURI
`hostname` : | host name

### gnet_uri_set_port ()

    void                gnet_uri_set_port                   (GURI *uri,
                                                             gint port);

Set a GURI's port.

`uri` : | a GURI
`port` : | port

### gnet_uri_set_path ()

    void                gnet_uri_set_path                   (GURI *uri,
                                                             const gchar *path);

Set a GURI's path.

`uri` : | a GURI
`path` : | path

### gnet_uri_set_query ()

    void                gnet_uri_set_query                  (GURI *uri,
                                                             const gchar *query);

Set a GURI's query.

`uri` : | a GURI
`query` : | query

### gnet_uri_set_fragment ()

    void                gnet_uri_set_fragment               (GURI *uri,
                                                             const gchar *fragment);

Set a GURI's fragment.

`uri` : | a GURI
`fragment` : | fragment

### gnet_uri_hash ()

    guint               gnet_uri_hash                       (gconstpointer p);

Creates a hash code for `p` for use with GHashTable.

`p` : | a GURI
Returns : | hash code for `p`.

### gnet_uri_equal ()

    gboolean            gnet_uri_equal                      (gconstpointer p1,
                                                             gconstpointer p2);

Compares two GURI's for equality.

`p1` : | a GURI
`p2` : | another GURI
Returns : | TRUE if they are equal; FALSE otherwise.

### gnet_uri_parse_inplace ()

    gboolean            gnet_uri_parse_inplace              (GURI *guri,
                                                             gchar *uri,
                                                             gchar *hostname,
                                                             gsize len);

This function parses an URI string very efficiently and without allocating any memory on the heap. It does this by modifying the passed-in string `uri` and changing field separators into string terminators in place. The result will then be put into the already-allocated and usually uninitialised, GURI structure `guri`.

Because the slash (') which separates the hostname from the path in an URI is needed as the first character of the path, it cannot be turned into a string terminator for the hostname. This makes it necessary for the caller (ie. you) to pass in an array where the hostname can be put.

If the URI has been parsed successfully, the fields of the GURI structure will either point into the given string `uri` (or to `hostname` in case of the hostname field), or be NULL. No freeing or de-initialising of the GURI structure is required.

The only gnet_uri_*() functions you are allowed to call with this URI structure are `gnet_uri_clone()`, `gnet_uri_equal()`, `gnet_uri_hash()`, `gnet_uri_get_string()` and `gnet_uri_unescape()` (the latter unescapes the string fragments in place, so is safe to use here).

You must not call any other gnet_uri_*() functions with this GURI, especially not any `gnet_uri_set()` functions.

Under normal circumstances, you should never need to use this function. Use `gnet_uri_new()` instead.

`guri` : | pointer to an uninitialised GURI structure (usually on the stack)
`uri` : | a writable URI string (which will be modified by this function!)
`hostname` : | a preallocated array of size `len`, into which the hostname will be copied if the URI has a hostname. This array should live as long as `guri` may be used, since `guri` might reference it. You may pass NULL here if you know your URIs won't contain a hostname field
`len` : |
Returns : | TRUE if `uri` was parsed successfully and GURI is usable, or FALSE if there was a failure.

Since 2.0.8