## URI

URI — Uniform Resource Identifier (URI)

## Synopsis

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

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