SoupHeaders: libsoup Reference Manual

## SoupHeaders SoupHeaders — Functions to help working with HTTP Headers |

## Functions

guint | soup_headers_parse_request ()
gboolean | soup_headers_parse_response ()
gboolean | soup_headers_parse_status_line ()
gboolean | soup_headers_parse ()
GSList * | soup_header_parse_list ()
GSList * | soup_header_parse_quality_list ()
void | soup_header_free_list ()
gboolean | soup_header_contains ()
GHashTable * | soup_header_parse_param_list ()
GHashTable * | soup_header_parse_semi_param_list ()
GHashTable * | soup_header_parse_param_list_strict ()
GHashTable * | soup_header_parse_semi_param_list_strict ()
void | soup_header_free_param_list ()
void | soup_header_g_string_append_param ()
void | soup_header_g_string_append_param_quoted ()

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

list | a GSList returned from `soup_header_parse_list()` or `soup_header_parse_quality_list()` |

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