SoupURI

## SoupURI SoupURI — URIs |

## Synopsis

    #include <libsoup/soup.h>

                        SoupURI;
    SoupURI *           soup_uri_new_with_base              (SoupURI *base,
                                                             const char *uri_string);
    SoupURI *           soup_uri_new                        (const char *uri_string);
    char *              soup_uri_to_string                  (SoupURI *uri,
                                                             gboolean just_path_and_query);

    SoupURI *           soup_uri_copy                       (SoupURI *uri);
    SoupURI *           soup_uri_copy_host                  (SoupURI *uri);
    gboolean            soup_uri_equal                      (SoupURI *uri1,
                                                             SoupURI *uri2);
    gboolean            soup_uri_host_equal                 (gconstpointer v1,
                                                             gconstpointer v2);
    guint               soup_uri_host_hash                  (gconstpointer key);
    void                soup_uri_free                       (SoupURI *uri);

    char *              soup_uri_encode                     (const char *part,
                                                             const char *escape_extra);
    char *              soup_uri_decode                     (const char *part);
    char *              soup_uri_normalize                  (const char *part,
                                                             const char *unescape_extra);

    #define             SOUP_URI_SCHEME_HTTP
    #define             SOUP_URI_SCHEME_HTTPS
    #define             SOUP_URI_SCHEME_DATA
    #define             SOUP_URI_SCHEME_FILE
    #define             SOUP_URI_SCHEME_FTP
    #define             SOUP_URI_SCHEME_RESOURCE
    gboolean            soup_uri_uses_default_port          (SoupURI *uri);
    #define             SOUP_URI_IS_VALID                   (uri)
    #define             SOUP_URI_VALID_FOR_HTTP             (uri)

    void                soup_uri_set_scheme                 (SoupURI *uri,
                                                             const char *scheme);
    const char *        soup_uri_get_scheme                 (SoupURI *uri);
    void                soup_uri_set_user                   (SoupURI *uri,
                                                             const char *user);
    const char *        soup_uri_get_user                   (SoupURI *uri);
    void                soup_uri_set_password               (SoupURI *uri,
                                                             const char *password);
    const char *        soup_uri_get_password               (SoupURI *uri);
    void                soup_uri_set_host                   (SoupURI *uri,
                                                             const char *host);
    const char *        soup_uri_get_host                   (SoupURI *uri);
    void                soup_uri_set_port                   (SoupURI *uri,
                                                             guint port);
    guint               soup_uri_get_port                   (SoupURI *uri);
    void                soup_uri_set_path                   (SoupURI *uri,
                                                             const char *path);
    const char *        soup_uri_get_path                   (SoupURI *uri);
    void                soup_uri_set_query                  (SoupURI *uri,
                                                             const char *query);
    void                soup_uri_set_query_from_form        (SoupURI *uri,
                                                             GHashTable *form);
    void                soup_uri_set_query_from_fields      (SoupURI *uri,
                                                             const char *first_field,
                                                             ...);
    const char *        soup_uri_get_query                  (SoupURI *uri);
    void                soup_uri_set_fragment               (SoupURI *uri,
                                                             const char *fragment);
    const char *        soup_uri_get_fragment               (SoupURI *uri);

## Object Hierarchy

      GBoxed
       +----SoupURI

## Description

A SoupURI represents a (parsed) URI.

Many applications will not need to use SoupURI directly at all; on the client side, `soup_message_new()` takes a stringified URI, and on the server side, the path and query components are provided for you in the server callback.

## Details

### SoupURI

    typedef struct {
    	const char *scheme;

    	char       *user;
    	char       *password;

    	char       *host;
    	guint       port;

    	char       *path;
    	char       *query;

    	char       *fragment;
    } SoupURI;

A SoupURI represents a (parsed) URI. SoupURI supports RFC 3986 (URI Generic Syntax), and can parse any valid URI. However, libsoup only uses "http" and "https" URIs internally; You can use `SOUP_URI_VALID_FOR_HTTP()` to test if a SoupURI is a valid HTTP URI.

`scheme` will always be set in any URI. It is an interned string and is always all lowercase. (If you parse a URI with a non-lowercase scheme, it will be converted to lowercase.) The macros `SOUP_URI_SCHEME_HTTP` and `SOUP_URI_SCHEME_HTTPS` provide the interned values for "http" and "https" and can be compared against URI `scheme` values.

`user` and `password` are parsed as defined in the older URI specs (ie, separated by a colon; RFC 3986 only talks about a single "userinfo" field). Note that `password` is not included in the output of `soup_uri_to_string()`. libsoup does not normally use these fields; authentication is handled via SoupSession signals.

`host` contains the hostname, and `port` the port specified in the URI. If the URI doesn't contain a hostname, `host` will be `NULL`, and if it doesn't specify a port, `port` may be 0. However, for "http" and "https" URIs, `host` is guaranteed to be non-`NULL` (trying to parse an http URI with no `host` will return `NULL`), and `port` will always be non-0 (because libsoup knows the default value to use when it is not specified in the URI).

`path` is always non-`NULL`. For http/https URIs, `path` will never be an empty string either; if the input URI has no path, the parsed SoupURI will have a `path` of "/".

`query` and `fragment` are optional for all URI types. `soup_form_decode()` may be useful for parsing `query`.

Note that `path`, `query`, and `fragment` may contain %-encoded characters. `soup_uri_new()` calls `soup_uri_normalize()` on them, but not `soup_uri_decode()`. This is necessary to ensure that `soup_uri_to_string()` will generate a URI that has exactly the same meaning as the original. (In theory, SoupURI should leave `user`, `password`, and `host` partially-encoded as well, but this would be more annoying than useful.)

const char *`scheme`; | the URI scheme (eg, "http")
char *`user`; | a username, or `NULL`
char *`password`; | a password, or `NULL`
char *`host`; | the hostname or IP address
guint `port`; | the port number on `host`
char *`path`; | the path on `host`
char *`query`; | a query for `path`, or `NULL`
char *`fragment`; | a fragment identifier within `path`, or `NULL`

### soup_uri_new_with_base ()

    SoupURI *           soup_uri_new_with_base              (SoupURI *base,
                                                             const char *uri_string);

Parses `uri_string` relative to `base`.

`base` : | a base URI
`uri_string` : | the URI
Returns : | a parsed SoupURI.

### soup_uri_new ()

    SoupURI *           soup_uri_new                        (const char *uri_string);

Parses an absolute URI.

You can also pass `NULL` for `uri_string` if you want to get back an "empty" SoupURI that you can fill in by hand. (You will need to call at least `soup_uri_set_scheme()` and `soup_uri_set_path()`, since those fields are required.)

`uri_string` : | a URI. [allow-none]
Returns : | a SoupURI, or `NULL` if the given string was found to be invalid.

### soup_uri_to_string ()

    char *              soup_uri_to_string                  (SoupURI *uri,
                                                             gboolean just_path_and_query);

Returns a string representing `uri`.

If `just_path_and_query` is `TRUE`, this concatenates the path and query together. That is, it constructs the string that would be needed in the Request-Line of an HTTP request for `uri`.

`uri` : | a SoupURI
`just_path_and_query` : | if `TRUE`, output just the path and query portions
Returns : | a string representing `uri`, which the caller must free.

### soup_uri_copy ()

    SoupURI *           soup_uri_copy                       (SoupURI *uri);

Copies `uri`

`uri` : | a SoupURI
Returns : | a copy of `uri`, which must be freed with `soup_uri_free()`

### soup_uri_copy_host ()

    SoupURI *           soup_uri_copy_host                  (SoupURI *uri);

Makes a copy of `uri`, considering only the protocol, host, and port

`uri` : | a SoupURI
Returns : | the new SoupURI

Since 2.28

### soup_uri_equal ()

    gboolean            soup_uri_equal                      (SoupURI *uri1,
                                                             SoupURI *uri2);

Tests whether or not `uri1` and `uri2` are equal in all parts

`uri1` : | a SoupURI
`uri2` : | another SoupURI
Returns : | `TRUE` or `FALSE`

### soup_uri_host_equal ()

    gboolean            soup_uri_host_equal                 (gconstpointer v1,
                                                             gconstpointer v2);

Compares `v1` and `v2`, considering only the scheme, host, and port.

`v1` : | a SoupURI with a non-`NULL` `host` member. [type Soup.URI]
`v2` : | a SoupURI with a non-`NULL` `host` member. [type Soup.URI]
Returns : | whether or not the URIs are equal in scheme, host, and port.

Since 2.28

### soup_uri_host_hash ()

    guint               soup_uri_host_hash                  (gconstpointer key);

Hashes `key`, considering only the scheme, host, and port.

`key` : | a SoupURI with a non-`NULL` `host` member. [type Soup.URI]
Returns : | a hash

Since 2.28

### soup_uri_free ()

    void                soup_uri_free                       (SoupURI *uri);

Frees `uri`.

`uri` : | a SoupURI

### soup_uri_encode ()

    char *              soup_uri_encode                     (const char *part,
                                                             const char *escape_extra);

This %-encodes the given URI part and returns the escaped version in allocated memory, which the caller must free when it is done.

`part` : | a URI part
`escape_extra` : | additional reserved characters to escape (or `NULL`). [allow-none]
Returns : | the encoded URI part

### soup_uri_decode ()

    char *              soup_uri_decode                     (const char *part);

Fully %-decodes `part`.

In the past, this would return `NULL` if `part` contained invalid percent-encoding, but now it just ignores the problem (as `soup_uri_new()` already did).

`part` : | a URI part
Returns : | the decoded URI part.

### soup_uri_normalize ()

    char *              soup_uri_normalize                  (const char *part,
                                                             const char *unescape_extra);

%-decodes any "unreserved" characters (or characters in `unescape_extra`) in `part`.

"Unreserved" characters are those that are not allowed to be used for punctuation according to the URI spec. For example, letters are unreserved, so `soup_uri_normalize()` will turn `http://example.com/foo/b%61r` into `http://example.com/foo/bar`, which is guaranteed to mean the same thing. However, "/" is "reserved", so `http://example.com/foo%2Fbar` would not be changed, because it might mean something different to the server.

In the past, this would return `NULL` if `part` contained invalid percent-encoding, but now it just ignores the problem (as `soup_uri_new()` already did).

`part` : | a URI part
`unescape_extra` : | reserved characters to unescape (or `NULL`)
Returns : | the normalized URI part

### SOUP_URI_SCHEME_HTTP

    #define SOUP_URI_SCHEME_HTTP     _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_HTTP, "http")

"http" as an interned string. This can be compared directly against the value of a SoupURI's `scheme`

### SOUP_URI_SCHEME_HTTPS

    #define SOUP_URI_SCHEME_HTTPS    _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_HTTPS, "https")

"https" as an interned string. This can be compared directly against the value of a SoupURI's `scheme`

### SOUP_URI_SCHEME_DATA

    #define SOUP_URI_SCHEME_DATA     _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_DATA, "data")

"data" as an interned string; you can compare this directly to a SoupURI's `scheme` field using `==`.

Since 2.30

### SOUP_URI_SCHEME_FILE

    #define SOUP_URI_SCHEME_FILE     _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_FILE, "file")

"file" as an interned string; you can compare this directly to a SoupURI's `scheme` field using `==`.

Since 2.30

### SOUP_URI_SCHEME_FTP

    #define SOUP_URI_SCHEME_FTP      _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_FTP, "ftp")

"ftp" as an interned string; you can compare this directly to a SoupURI's `scheme` field using `==`.

Since 2.30

### SOUP_URI_SCHEME_RESOURCE

    #define SOUP_URI_SCHEME_RESOURCE _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_RESOURCE, "resource")

"resource" as an interned string. This can be compared directly against the value of a SoupURI's `scheme`

Since 2.42

### soup_uri_uses_default_port ()

    gboolean            soup_uri_uses_default_port          (SoupURI *uri);

Tests if `uri` uses the default port for its scheme. (Eg, 80 for http.) (This only works for http, https and ftp; libsoup does not know the default ports of other protocols.)

`uri` : | a SoupURI
Returns : | `TRUE` or `FALSE`

### SOUP_URI_IS_VALID()

    #define   SOUP_URI_IS_VALID(uri)       ((uri) && (uri)->scheme && (uri)->path)

Tests whether `uri` is a valid SoupURI; that is, that it is non-`NULL` and its `scheme` and `path` members are also non-`NULL`.

This macro does not check whether http and https URIs have a non-`NULL` `host` member.

`uri` : | a SoupURI
Returns : | `TRUE` if `uri` is valid for use.

Since 2.38

### SOUP_URI_VALID_FOR_HTTP()

    #define   SOUP_URI_VALID_FOR_HTTP(uri) ((uri) && ((uri)->scheme == SOUP_URI_SCHEME_HTTP || (uri)->scheme == SOUP_URI_SCHEME_HTTPS) && (uri)->host && (uri)->path)

Tests if `uri` is a valid SoupURI for HTTP communication; that is, if it can be used to construct a SoupMessage.

`uri` : | a SoupURI
Returns : | `TRUE` if `uri` is a valid "http" or "https" URI.

Since 2.24

### soup_uri_set_scheme ()

    void                soup_uri_set_scheme                 (SoupURI *uri,
                                                             const char *scheme);

Sets `uri`'s scheme to `scheme`. This will also set `uri`'s port to the default port for `scheme`, if known.

`uri` : | a SoupURI
`scheme` : | the URI scheme

### soup_uri_get_scheme ()

    const char *        soup_uri_get_scheme                 (SoupURI *uri);

Gets `uri`'s scheme.

`uri` : | a SoupURI
Returns : | `uri`'s scheme.

Since 2.32

### soup_uri_set_user ()

    void                soup_uri_set_user                   (SoupURI *uri,
                                                             const char *user);

Sets `uri`'s user to `user`.

`uri` : | a SoupURI
`user` : | the username, or `NULL`. [allow-none]

### soup_uri_get_user ()

    const char *        soup_uri_get_user                   (SoupURI *uri);

Gets `uri`'s user.

`uri` : | a SoupURI
Returns : | `uri`'s user.

Since 2.32

### soup_uri_set_password ()

    void                soup_uri_set_password               (SoupURI *uri,
                                                             const char *password);

Sets `uri`'s password to `password`.

`uri` : | a SoupURI
`password` : | the password, or `NULL`. [allow-none]

### soup_uri_get_password ()

    const char *        soup_uri_get_password               (SoupURI *uri);

Gets `uri`'s password.

`uri` : | a SoupURI
Returns : | `uri`'s password.

Since 2.32

### soup_uri_set_host ()

    void                soup_uri_set_host                   (SoupURI *uri,
                                                             const char *host);

Sets `uri`'s host to `host`.

If `host` is an IPv6 IP address, it should not include the brackets required by the URI syntax; they will be added automatically when converting `uri` to a string.

http and https URIs should not have a `NULL` `host`.

`uri` : | a SoupURI
`host` : | the hostname or IP address, or `NULL`. [allow-none]

### soup_uri_get_host ()

    const char *        soup_uri_get_host                   (SoupURI *uri);

Gets `uri`'s host.

`uri` : | a SoupURI
Returns : | `uri`'s host.

Since 2.32

### soup_uri_set_port ()

    void                soup_uri_set_port                   (SoupURI *uri,
                                                             guint port);

Sets `uri`'s port to `port`. If `port` is 0, `uri` will not have an explicitly-specified port.

`uri` : | a SoupURI
`port` : | the port, or 0

### soup_uri_get_port ()

    guint               soup_uri_get_port                   (SoupURI *uri);

Gets `uri`'s port.

`uri` : | a SoupURI
Returns : | `uri`'s port.

Since 2.32

### soup_uri_set_path ()

    void                soup_uri_set_path                   (SoupURI *uri,
                                                             const char *path);

Sets `uri`'s path to `path`.

`uri` : | a SoupURI
`path` : | the non-`NULL` path

### soup_uri_get_path ()

    const char *        soup_uri_get_path                   (SoupURI *uri);

Gets `uri`'s path.

`uri` : | a SoupURI
Returns : | `uri`'s path.

Since 2.32

### soup_uri_set_query ()

    void                soup_uri_set_query                  (SoupURI *uri,
                                                             const char *query);

Sets `uri`'s query to `query`.

`uri` : | a SoupURI
`query` : | the query. [allow-none]

### soup_uri_set_query_from_form ()

    void                soup_uri_set_query_from_form        (SoupURI *uri,
                                                             GHashTable *form);

Sets `uri`'s query to the result of encoding `form` according to the HTML form rules. See `soup_form_encode_hash()` for more information.

`uri` : | a SoupURI
`form` : | a GHashTable containing HTML form information. [element-type utf8 utf8]

### soup_uri_set_query_from_fields ()

    void                soup_uri_set_query_from_fields      (SoupURI *uri,
                                                             const char *first_field,
                                                             ...);

Sets `uri`'s query to the result of encoding the given form fields and values according to the * HTML form rules. See `soup_form_encode()` for more information.

`uri` : | a SoupURI
`first_field` : | name of the first form field to encode into query
`...` : | value of `first_field`, followed by additional field names and values, terminated by `NULL`.

### soup_uri_get_query ()

    const char *        soup_uri_get_query                  (SoupURI *uri);

Gets `uri`'s query.

`uri` : | a SoupURI
Returns : | `uri`'s query.

Since 2.32

### soup_uri_set_fragment ()

    void                soup_uri_set_fragment               (SoupURI *uri,
                                                             const char *fragment);

Sets `uri`'s fragment to `fragment`.

`uri` : | a SoupURI
`fragment` : | the fragment. [allow-none]

### soup_uri_get_fragment ()

    const char *        soup_uri_get_fragment               (SoupURI *uri);

Gets `uri`'s fragment.

`uri` : | a SoupURI
Returns : | `uri`'s fragment.

Since 2.32