## soup-uri

soup-uri — URIs

## Synopsis

    struct      SoupUri;
    typedef     SoupProtocol;
    #define     SOUP_PROTOCOL_HTTP
    #define     SOUP_PROTOCOL_HTTPS
    SoupUri*    soup_uri_new_with_base          (const SoupUri *base,
                                                 const char *uri_string);
    SoupUri*    soup_uri_new                    (const char *uri_string);
    char*       soup_uri_to_string              (const SoupUri *uri,
                                                 gboolean just_path);
    SoupUri*    soup_uri_copy                   (const SoupUri *uri);
    SoupUri*    soup_uri_copy_root              (const SoupUri *uri);
    gboolean    soup_uri_equal                  (const SoupUri *uri1,
                                                 const SoupUri *uri2);
    void        soup_uri_free                   (SoupUri *uri);
    char*       soup_uri_encode                 (const char *part,
                                                 const char *escape_extra);
    void        soup_uri_decode                 (char *part);
    gboolean    soup_uri_uses_default_port      (const SoupUri *uri);

## Description

## Details

### struct SoupUri

    struct SoupUri {
    	SoupProtocol  protocol;

    	char         *user;
    	char         *passwd;

    	char         *host;
    	guint         port;

    	char         *path;
    	char         *query;

    	char         *fragment;

    	/* Don't use this */
    	gboolean      broken_encoding;
    };

### SoupProtocol

    typedef GQuark SoupProtocol;

GQuark is used for SoupProtocol so that the protocol of a SoupUri can be tested quickly.

### SOUP_PROTOCOL_HTTP

    #define SOUP_PROTOCOL_HTTP (g_quark_from_static_string ("http"))

This returns the SoupProtocol value for "http".

### SOUP_PROTOCOL_HTTPS

    #define SOUP_PROTOCOL_HTTPS (g_quark_from_static_string ("https"))

This returns the SoupProtocol value for "https".

### soup_uri_new_with_base ()

    SoupUri*    soup_uri_new_with_base          (const 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.

`uri_string` : | a URI
Returns : | a SoupUri, or `NULL`.

### soup_uri_to_string ()

    char*       soup_uri_to_string              (const SoupUri *uri,
                                                 gboolean just_path);

Returns a string representing `uri`.

`uri` : | a SoupUri
`just_path` : | 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                   (const SoupUri *uri);

Copies `uri`

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

### soup_uri_copy_root ()

    SoupUri*    soup_uri_copy_root              (const SoupUri *uri);

Copies the protocol, host, and port of `uri` into a new SoupUri (all other fields in the new URI will be empty.)

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

### soup_uri_equal ()

    gboolean    soup_uri_equal                  (const SoupUri *uri1,
                                                 const 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_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 characters beyond " \"%#<>{}|\^[]`" to escape (or `NULL`)
Returns : | the encoded URI part

### soup_uri_decode ()

    void        soup_uri_decode                 (char *part);

`-decodes` the passed-in URI *in place*. The decoded version is never longer than the encoded version, so there does not need to be any additional space at the end of the string.

`part` : | a URI part

### soup_uri_uses_default_port ()

    gboolean    soup_uri_uses_default_port      (const SoupUri *uri);

Tests if `uri` uses the default port for its protocol. (Eg, 80 for http.)

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