SoupHeaders

SoupHeaders — Functions to help working with HTTP Headers

Functions

Includes

#include <libsoup/soup.h>

Description

These are utility functions to help working with HTTP headers.

Functions

soup_headers_parse_request ()

guint
soup_headers_parse_request (const char *str,
                            int len,
                            SoupMessageHeaders *req_headers,
                            char **req_method,
                            char **req_path,
                            SoupHTTPVersion *ver);

Parses the headers of an HTTP request in str and stores the results in req_method , req_path , ver , and req_headers .

Beware that req_headers may be modified even on failure.

Parameters

str

the headers (up to, but not including, the trailing blank line)

 

len

length of str

 

req_headers

SoupMessageHeaders to store the header values in

 

req_method

if non-NULL, will be filled in with the request method.

[out][optional]

req_path

if non-NULL, will be filled in with the request path.

[out][optional]

ver

if non-NULL, will be filled in with the HTTP version.

[out][optional]

Returns

SOUP_STATUS_OK if the headers could be parsed, or an HTTP error to be returned to the client if they could not be.


soup_headers_parse_response ()

gboolean
soup_headers_parse_response (const char *str,
                             int len,
                             SoupMessageHeaders *headers,
                             SoupHTTPVersion *ver,
                             guint *status_code,
                             char **reason_phrase);

Parses the headers of an HTTP response in str and stores the results in ver , status_code , reason_phrase , and headers .

Beware that headers may be modified even on failure.

Parameters

str

the headers (up to, but not including, the trailing blank line)

 

len

length of str

 

headers

SoupMessageHeaders to store the header values in

 

ver

if non-NULL, will be filled in with the HTTP version.

[out][optional]

status_code

if non-NULL, will be filled in with the status code.

[out][optional]

reason_phrase

if non-NULL, will be filled in with the reason phrase.

[out][optional]

Returns

success or failure.


soup_headers_parse_status_line ()

gboolean
soup_headers_parse_status_line (const char *status_line,
                                SoupHTTPVersion *ver,
                                guint *status_code,
                                char **reason_phrase);

Parses the HTTP Status-Line string in status_line into ver , status_code , and reason_phrase . status_line must be terminated by either "\0" or "\r\n".

Parameters

status_line

an HTTP Status-Line

 

ver

if non-NULL, will be filled in with the HTTP version.

[out][optional]

status_code

if non-NULL, will be filled in with the status code.

[out][optional]

reason_phrase

if non-NULL, will be filled in with the reason phrase.

[out][optional]

Returns

TRUE if status_line was parsed successfully.


soup_headers_parse ()

gboolean
soup_headers_parse (const char *str,
                    int len,
                    SoupMessageHeaders *dest);

Parses the headers of an HTTP request or response in str and stores the results in dest . Beware that dest may be modified even on failure.

This is a low-level method; normally you would use soup_headers_parse_request() or soup_headers_parse_response().

Parameters

str

the header string (including the Request-Line or Status-Line, but not the trailing blank line)

 

len

length of str

 

dest

SoupMessageHeaders to store the header values in

 

Returns

success or failure


soup_header_parse_list ()

GSList *
soup_header_parse_list (const char *header);

Parses a header whose content is described by RFC2616 as "something", where "something" does not itself contain commas, except as part of quoted-strings.

Parameters

header

a header value

 

Returns

a GSList of list elements, as allocated strings.

[transfer full][element-type utf8]


soup_header_parse_quality_list ()

GSList *
soup_header_parse_quality_list (const char *header,
                                GSList **unacceptable);

Parses a header whose content is a list of items with optional "qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding, Accept-Language, TE).

If unacceptable is not NULL, then on return, it will contain the items with qvalue 0. Either way, those items will be removed from the main list.

Parameters

header

a header value

 

unacceptable

on return, will contain a list of unacceptable values.

[out][optional][transfer full][element-type utf8]

Returns

a GSList of acceptable values (as allocated strings), highest-qvalue first.

[transfer full][element-type utf8]


soup_header_free_list ()

void
soup_header_free_list (GSList *list);

Frees list .

[skip]

Parameters


soup_header_contains ()

gboolean
soup_header_contains (const char *header,
                      const char *token);

Parses header to see if it contains the token token (matched case-insensitively). Note that this can't be used with lists that have qvalues.

Parameters

header

An HTTP header suitable for parsing with soup_header_parse_list()

 

token

a token

 

Returns

whether or not header contains token


soup_header_parse_param_list ()

GHashTable *
soup_header_parse_param_list (const char *header);

Parses a header which is a comma-delimited list of something like: token [ "=" ( token | quoted-string ) ].

Tokens that don't have an associated value will still be added to the resulting hash table, but with a NULL value.

This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

Parameters

header

a header value

 

Returns

a GHashTable of list elements, which can be freed with soup_header_free_param_list().

[element-type utf8 utf8][transfer full]


soup_header_parse_semi_param_list ()

GHashTable *
soup_header_parse_semi_param_list (const char *header);

Parses a header which is a semicolon-delimited list of something like: token [ "=" ( token | quoted-string ) ].

Tokens that don't have an associated value will still be added to the resulting hash table, but with a NULL value.

This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

Parameters

header

a header value

 

Returns

a GHashTable of list elements, which can be freed with soup_header_free_param_list().

[element-type utf8 utf8][transfer full]


soup_header_parse_param_list_strict ()

GHashTable *
soup_header_parse_param_list_strict (const char *header);

A strict version of soup_header_parse_param_list() that bails out if there are duplicate parameters. Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use soup_header_parse_param_list() instead.

Parameters

header

a header value

 

Returns

a GHashTable of list elements, which can be freed with soup_header_free_param_list() or NULL if there are duplicate elements.

[element-type utf8 utf8][transfer full][nullable]


soup_header_parse_semi_param_list_strict ()

GHashTable *
soup_header_parse_semi_param_list_strict
                               (const char *header);

A strict version of soup_header_parse_semi_param_list() that bails out if there are duplicate parameters. Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use soup_header_parse_semi_param_list() instead.

Parameters

header

a header value

 

Returns

a GHashTable of list elements, which can be freed with soup_header_free_param_list() or NULL if there are duplicate elements.

[element-type utf8 utf8][transfer full][nullable]


soup_header_free_param_list ()

void
soup_header_free_param_list (GHashTable *param_list);

Frees param_list .

Parameters

param_list

a GHashTable returned from soup_header_parse_param_list() or soup_header_parse_semi_param_list().

[element-type utf8 utf8]

soup_header_g_string_append_param ()

void
soup_header_g_string_append_param (GString *string,
                                   const char *name,
                                   const char *value);

Appends something like name =value to string , taking care to quote value if needed, and if so, to escape any quotes or backslashes in value .

Alternatively, if value is a non-ASCII UTF-8 string, it will be appended using RFC5987 syntax. Although in theory this is supposed to work anywhere in HTTP that uses this style of parameter, in reality, it can only be used portably with the Content-Disposition "filename" parameter.

If value is NULL, this will just append name to string .

Parameters

string

a GString being used to construct an HTTP header value

 

name

a parameter name

 

value

a parameter value, or NULL

 

soup_header_g_string_append_param_quoted ()

void
soup_header_g_string_append_param_quoted
                               (GString *string,
                                const char *name,
                                const char *value);

Appends something like name ="value " to string , taking care to escape any quotes or backslashes in value .

If value is (non-ASCII) UTF-8, this will instead use RFC 5987 encoding, just like soup_header_g_string_append_param().

Parameters

string

a GString being used to construct an HTTP header value

 

name

a parameter name

 

value

a parameter value