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_urlencoded() 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.)

soup_uri_new_with_base ()

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

Parses uri_string relative to base.

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

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.

soup_uri_copy ()

SoupURI *           soup_uri_copy                       (SoupURI *uri);

Copies uri

soup_uri_equal ()

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

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

soup_uri_free ()

void                soup_uri_free                       (SoupURI *uri);

Frees uri.

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.

soup_uri_decode ()

char *              soup_uri_decode                     (const char *part);

Fully %-decodes 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.

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_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 and https; libsoup does not know the default ports of other protocols.)

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.

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.

soup_uri_set_user ()

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

Sets uri's user to user.

soup_uri_set_password ()

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

Sets uri's password to password.

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.

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.

soup_uri_set_path ()

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

Sets uri's path to path.

soup_uri_set_query ()

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

Sets uri's query to query.

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.

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.

soup_uri_set_fragment ()

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

Sets uri's fragment to fragment.