SoupMessageHeaders

## SoupMessageHeaders SoupMessageHeaders — HTTP message headers |

## Synopsis

    #include <libsoup/soup.h>

    typedef             SoupMessageHeaders;
    enum                SoupMessageHeadersType;
    SoupMessageHeaders * soup_message_headers_new           (SoupMessageHeadersType type);
    void                soup_message_headers_free           (SoupMessageHeaders *hdrs);

    void                soup_message_headers_append         (SoupMessageHeaders *hdrs,
                                                             const char *name,
                                                             const char *value);
    void                soup_message_headers_replace        (SoupMessageHeaders *hdrs,
                                                             const char *name,
                                                             const char *value);
    void                soup_message_headers_remove         (SoupMessageHeaders *hdrs,
                                                             const char *name);
    void                soup_message_headers_clear          (SoupMessageHeaders *hdrs);
    const char *        soup_message_headers_get_one        (SoupMessageHeaders *hdrs,
                                                             const char *name);
    const char *        soup_message_headers_get_list       (SoupMessageHeaders *hdrs,
                                                             const char *name);
    const char *        soup_message_headers_get            (SoupMessageHeaders *hdrs,
                                                             const char *name);

    void                (*SoupMessageHeadersForeachFunc)    (const char *name,
                                                             const char *value,
                                                             gpointer user_data);
    void                soup_message_headers_foreach        (SoupMessageHeaders *hdrs,
                                                             SoupMessageHeadersForeachFunc func,
                                                             gpointer user_data);

                        SoupMessageHeadersIter;
    void                soup_message_headers_iter_init      (SoupMessageHeadersIter *iter,
                                                             SoupMessageHeaders *hdrs);
    gboolean            soup_message_headers_iter_next      (SoupMessageHeadersIter *iter,
                                                             const char **name,
                                                             const char **value);

    enum                SoupEncoding;
    SoupEncoding        soup_message_headers_get_encoding   (SoupMessageHeaders *hdrs);
    void                soup_message_headers_set_encoding   (SoupMessageHeaders *hdrs,
                                                             SoupEncoding encoding);
    goffset             soup_message_headers_get_content_length
                                                            (SoupMessageHeaders *hdrs);
    void                soup_message_headers_set_content_length
                                                            (SoupMessageHeaders *hdrs,
                                                             goffset content_length);

    enum                SoupExpectation;
    SoupExpectation     soup_message_headers_get_expectations
                                                            (SoupMessageHeaders *hdrs);
    void                soup_message_headers_set_expectations
                                                            (SoupMessageHeaders *hdrs,
                                                             SoupExpectation expectations);

    const char *        soup_message_headers_get_content_type
                                                            (SoupMessageHeaders *hdrs,
                                                             GHashTable **params);
    void                soup_message_headers_set_content_type
                                                            (SoupMessageHeaders *hdrs,
                                                             const char *content_type,
                                                             GHashTable *params);

    gboolean            soup_message_headers_get_content_disposition
                                                            (SoupMessageHeaders *hdrs,
                                                             char **disposition,
                                                             GHashTable **params);
    void                soup_message_headers_set_content_disposition
                                                            (SoupMessageHeaders *hdrs,
                                                             const char *disposition,
                                                             GHashTable *params);

                        SoupRange;
    gboolean            soup_message_headers_get_ranges     (SoupMessageHeaders *hdrs,
                                                             goffset total_length,
                                                             SoupRange **ranges,
                                                             int *length);
    void                soup_message_headers_set_ranges     (SoupMessageHeaders *hdrs,
                                                             SoupRange *ranges,
                                                             int length);
    void                soup_message_headers_set_range      (SoupMessageHeaders *hdrs,
                                                             goffset start,
                                                             goffset end);
    void                soup_message_headers_free_ranges    (SoupMessageHeaders *hdrs,
                                                             SoupRange *ranges);
    gboolean            soup_message_headers_get_content_range
                                                            (SoupMessageHeaders *hdrs,
                                                             goffset *start,
                                                             goffset *end,
                                                             goffset *total_length);
    void                soup_message_headers_set_content_range
                                                            (SoupMessageHeaders *hdrs,
                                                             goffset start,
                                                             goffset end,
                                                             goffset total_length);

## Object Hierarchy

      GBoxed
       +----SoupMessageHeaders

## Description

SoupMessageHeaders represents the HTTP message headers associated with a request or response.

## Details

### SoupMessageHeaders

    typedef struct SoupMessageHeaders SoupMessageHeaders;

### enum SoupMessageHeadersType

    typedef enum {
    	SOUP_MESSAGE_HEADERS_REQUEST,
    	SOUP_MESSAGE_HEADERS_RESPONSE,
    	SOUP_MESSAGE_HEADERS_MULTIPART
    } SoupMessageHeadersType;

Value passed to `soup_message_headers_new()` to set certain default behaviors.

`SOUP_MESSAGE_HEADERS_REQUEST` | request headers
`SOUP_MESSAGE_HEADERS_RESPONSE` | response headers
`SOUP_MESSAGE_HEADERS_MULTIPART` | multipart body part headers

### soup_message_headers_new ()

    SoupMessageHeaders * soup_message_headers_new           (SoupMessageHeadersType type);

Creates a SoupMessageHeaders. (SoupMessage does this automatically for its own headers. You would only need to use this method if you are manually parsing or generating message headers.)

`type` : | the type of headers
Returns : | a new SoupMessageHeaders

### soup_message_headers_free ()

    void                soup_message_headers_free           (SoupMessageHeaders *hdrs);

Frees `hdrs`.

`hdrs` : | a SoupMessageHeaders

### soup_message_headers_append ()

    void                soup_message_headers_append         (SoupMessageHeaders *hdrs,
                                                             const char *name,
                                                             const char *value);

Appends a new header with name `name` and value `value` to `hdrs`. (If there is an existing header with name `name`, then this creates a second one, which is only allowed for list-valued headers; see also `soup_message_headers_replace()`.)

The caller is expected to make sure that `name` and `value` are syntactically correct.

`hdrs` : | a SoupMessageHeaders
`name` : | the header name to add
`value` : | the new value of `name`

### soup_message_headers_replace ()

    void                soup_message_headers_replace        (SoupMessageHeaders *hdrs,
                                                             const char *name,
                                                             const char *value);

Replaces the value of the header `name` in `hdrs` with `value`. (See also `soup_message_headers_append()`.)

The caller is expected to make sure that `name` and `value` are syntactically correct.

`hdrs` : | a SoupMessageHeaders
`name` : | the header name to replace
`value` : | the new value of `name`

### soup_message_headers_remove ()

    void                soup_message_headers_remove         (SoupMessageHeaders *hdrs,
                                                             const char *name);

Removes `name` from `hdrs`. If there are multiple values for `name`, they are all removed.

`hdrs` : | a SoupMessageHeaders
`name` : | the header name to remove

### soup_message_headers_clear ()

    void                soup_message_headers_clear          (SoupMessageHeaders *hdrs);

Clears `hdrs`.

`hdrs` : | a SoupMessageHeaders

### soup_message_headers_get_one ()

    const char *        soup_message_headers_get_one        (SoupMessageHeaders *hdrs,
                                                             const char *name);

Gets the value of header `name` in `hdrs`. Use this for headers whose values are not comma-delimited lists, and which therefore can only appear at most once in the headers. For list-valued headers, use `soup_message_headers_get_list()`.

If `hdrs` does erroneously contain multiple copies of the header, it is not defined which one will be returned. (Ideally, it will return whichever one makes libsoup most compatible with other HTTP implementations.)

`hdrs` : | a SoupMessageHeaders
`name` : | header name
Returns : | the header's value or `NULL` if not found.

Since 2.26.1

### soup_message_headers_get_list ()

    const char *        soup_message_headers_get_list       (SoupMessageHeaders *hdrs,
                                                             const char *name);

Gets the value of header `name` in `hdrs`. Use this for headers whose values are comma-delimited lists, and which are therefore allowed to appear multiple times in the headers. For non-list-valued headers, use `soup_message_headers_get_one()`.

If `name` appears multiple times in `hdrs`, `soup_message_headers_get_list()` will concatenate all of the values together, separated by commas. This is sometimes awkward to parse (eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal with it anyway, because the HTTP spec explicitly states that this transformation is allowed, and so an upstream proxy could do the same thing.

`hdrs` : | a SoupMessageHeaders
`name` : | header name
Returns : | the header's value or `NULL` if not found.

Since 2.26.1

### soup_message_headers_get ()

    const char *        soup_message_headers_get            (SoupMessageHeaders *hdrs,
                                                             const char *name);

### Warning

`soup_message_headers_get` is deprecated and should not be used in newly-written code. Use `soup_message_headers_get_one()` or `soup_message_headers_get_list()` instead.

Gets the value of header `name` in `hdrs`.

This method was supposed to work correctly for both single-valued and list-valued headers, but because some HTTP clients/servers mistakenly send multiple copies of headers that are supposed to be single-valued, it sometimes returns incorrect results. To fix this, the methods `soup_message_headers_get_one()` and `soup_message_headers_get_list()` were introduced, so callers can explicitly state which behavior they are expecting.

`hdrs` : | a SoupMessageHeaders
`name` : | header name
Returns : | as with `soup_message_headers_get_list()`.

### SoupMessageHeadersForeachFunc ()

    void                (*SoupMessageHeadersForeachFunc)    (const char *name,
                                                             const char *value,
                                                             gpointer user_data);

The callback passed to `soup_message_headers_foreach()`.

`name` : | the header name
`value` : | the header value
`user_data` : | the data passed to `soup_message_headers_foreach()`

### soup_message_headers_foreach ()

    void                soup_message_headers_foreach        (SoupMessageHeaders *hdrs,
                                                             SoupMessageHeadersForeachFunc func,
                                                             gpointer user_data);

Calls `func` once for each header value in `hdrs`.

Beware that unlike `soup_message_headers_get()`, this processes the headers in exactly the way they were added, rather than concatenating multiple same-named headers into a single value. (This is intentional; it ensures that if you call `soup_message_headers_append()` multiple times with the same name, then the I/O code will output multiple copies of the header when sending the message to the remote implementation, which may be required for interoperability in some cases.)

You may not modify the headers from `func`.

`hdrs` : | a SoupMessageHeaders
`func` : | callback function to run for each header. [scope call]
`user_data` : | data to pass to `func`

### SoupMessageHeadersIter

    typedef struct {
    } SoupMessageHeadersIter;

An opaque type used to iterate over a `SoupMessageHeaders` structure.

After intializing the iterator with `soup_message_headers_iter_init()`, call `soup_message_headers_iter_next()` to fetch data from it.

You may not modify the headers while iterating over them.

### soup_message_headers_iter_init ()

    void                soup_message_headers_iter_init      (SoupMessageHeadersIter *iter,
                                                             SoupMessageHeaders *hdrs);

Initializes `iter` for iterating `hdrs`.

`iter` : | a pointer to a `SoupMessageHeadersIter` structure. [out][transfer none]
`hdrs` : | a `SoupMessageHeaders`

### soup_message_headers_iter_next ()

    gboolean            soup_message_headers_iter_next      (SoupMessageHeadersIter *iter,
                                                             const char **name,
                                                             const char **value);

Yields the next name/value pair in the `SoupMessageHeaders` being iterated by `iter`. If `iter` has already yielded the last header, then `soup_message_headers_iter_next()` will return `FALSE` and `name` and `value` will be unchanged.

`iter` : | a `SoupMessageHeadersIter`. [inout][transfer none]
`name` : | pointer to a variable to return the header name in. [out][transfer none]
`value` : | pointer to a variable to return the header value in. [out][transfer none]
Returns : | `TRUE` if another name and value were returned, `FALSE` if the end of the headers has been reached.

### enum SoupEncoding

    typedef enum {
    	SOUP_ENCODING_UNRECOGNIZED,
    	SOUP_ENCODING_NONE,
    	SOUP_ENCODING_CONTENT_LENGTH,
    	SOUP_ENCODING_EOF,
    	SOUP_ENCODING_CHUNKED,
    	SOUP_ENCODING_BYTERANGES
    } SoupEncoding;

How a message body is encoded for transport

`SOUP_ENCODING_UNRECOGNIZED` | unknown / error
`SOUP_ENCODING_NONE` | no body is present (which is not the same as a 0-length body, and only occurs in certain places)
`SOUP_ENCODING_CONTENT_LENGTH` | Content-Length encoding
`SOUP_ENCODING_EOF` | Response body ends when the connection is closed
`SOUP_ENCODING_CHUNKED` | chunked encoding (currently only supported for response)
`SOUP_ENCODING_BYTERANGES` | multipart/byteranges (Reserved for future use: NOT CURRENTLY IMPLEMENTED)

### soup_message_headers_get_encoding ()

    SoupEncoding        soup_message_headers_get_encoding   (SoupMessageHeaders *hdrs);

Gets the message body encoding that `hdrs` declare. This may not always correspond to the encoding used on the wire; eg, a HEAD response may declare a Content-Length or Transfer-Encoding, but it will never actually include a body.

`hdrs` : | a SoupMessageHeaders
Returns : | the encoding declared by `hdrs`.

### soup_message_headers_set_encoding ()

    void                soup_message_headers_set_encoding   (SoupMessageHeaders *hdrs,
                                                             SoupEncoding encoding);

Sets the message body encoding that `hdrs` will declare. In particular, you should use this if you are going to send a request or response in chunked encoding.

`hdrs` : | a SoupMessageHeaders
`encoding` : | a SoupEncoding

### soup_message_headers_get_content_length ()

    goffset             soup_message_headers_get_content_length
                                                            (SoupMessageHeaders *hdrs);

Gets the message body length that `hdrs` declare. This will only be non-0 if `soup_message_headers_get_encoding()` returns `SOUP_ENCODING_CONTENT_LENGTH`.

`hdrs` : | a SoupMessageHeaders
Returns : | the message body length declared by `hdrs`.

### soup_message_headers_set_content_length ()

    void                soup_message_headers_set_content_length
                                                            (SoupMessageHeaders *hdrs,
                                                             goffset content_length);

Sets the message body length that `hdrs` will declare, and sets `hdrs`'s encoding to `SOUP_ENCODING_CONTENT_LENGTH`.

You do not normally need to call this; if `hdrs` is set to use Content-Length encoding, libsoup will automatically set its Content-Length header for you immediately before sending the headers. One situation in which this method is useful is when generating the response to a HEAD request; Calling `soup_message_headers_set_content_length()` allows you to put the correct content length into the response without needing to waste memory by filling in a response body which won't actually be sent.

`hdrs` : | a SoupMessageHeaders
`content_length` : | the message body length

### enum SoupExpectation

    typedef enum {
    	SOUP_EXPECTATION_UNRECOGNIZED = (1 << 0),
    	SOUP_EXPECTATION_CONTINUE     = (1 << 1)
    } SoupExpectation;

Represents the parsed value of the "Expect" header.

`SOUP_EXPECTATION_UNRECOGNIZED` | any unrecognized expectation
`SOUP_EXPECTATION_CONTINUE` | "100-continue"

### soup_message_headers_get_expectations ()

    SoupExpectation     soup_message_headers_get_expectations
                                                            (SoupMessageHeaders *hdrs);

Gets the expectations declared by `hdrs`'s "Expect" header. Currently this will either be `SOUP_EXPECTATION_CONTINUE` or `SOUP_EXPECTATION_UNRECOGNIZED`.

`hdrs` : | a SoupMessageHeaders
Returns : | the contents of `hdrs`'s "Expect" header

### soup_message_headers_set_expectations ()

    void                soup_message_headers_set_expectations
                                                            (SoupMessageHeaders *hdrs,
                                                             SoupExpectation expectations);

Sets `hdrs`'s "Expect" header according to `expectations`.

Currently `SOUP_EXPECTATION_CONTINUE` is the only known expectation value. You should set this value on a request if you are sending a large message body (eg, via POST or PUT), and want to give the server a chance to reject the request after seeing just the headers (eg, because it will require authentication before allowing you to post, or because you're POSTing to a URL that doesn't exist). This saves you from having to transmit the large request body when the server is just going to ignore it anyway.

`hdrs` : | a SoupMessageHeaders
`expectations` : | the expectations to set

### soup_message_headers_get_content_type ()

    const char *        soup_message_headers_get_content_type
                                                            (SoupMessageHeaders *hdrs,
                                                             GHashTable **params);

Looks up the "Content-Type" header in `hdrs`, parses it, and returns its value in *`content_type` and *`params`. `params` can be `NULL` if you are only interested in the content type itself.

`hdrs` : | a SoupMessageHeaders
`params` : | return location for the Content-Type parameters (eg, "charset"), or `NULL`. [out][allow-none]
Returns : | a string with the value of the "Content-Type" header or NULL if `hdrs` does not contain that header or it cannot be parsed (in which case *`params` will be unchanged).

Since 2.26

### soup_message_headers_set_content_type ()

    void                soup_message_headers_set_content_type
                                                            (SoupMessageHeaders *hdrs,
                                                             const char *content_type,
                                                             GHashTable *params);

Sets the "Content-Type" header in `hdrs` to `content_type`, optionally with additional parameters specified in `params`.

`hdrs` : | a SoupMessageHeaders
`content_type` : | the MIME type
`params` : | additional parameters, or `NULL`

Since 2.26

### soup_message_headers_get_content_disposition ()

    gboolean            soup_message_headers_get_content_disposition
                                                            (SoupMessageHeaders *hdrs,
                                                             char **disposition,
                                                             GHashTable **params);

Looks up the "Content-Disposition" header in `hdrs`, parses it, and returns its value in *`disposition` and *`params`. `params` can be `NULL` if you are only interested in the disposition-type.

In HTTP, the most common use of this header is to set a disposition-type of "attachment", to suggest to the browser that a response should be saved to disk rather than displayed in the browser. If `params` contains a "filename" parameter, this is a suggestion of a filename to use. (If the parameter value in the header contains an absolute or relative path, libsoup will truncate it down to just the final path component, so you do not need to test this yourself.)

Content-Disposition is also used in "multipart/form-data", however this is handled automatically by SoupMultipart and the associated form methods.

`hdrs` : | a SoupMessageHeaders
`disposition` : | return location for the disposition-type, or `NULL`
`params` : | return location for the Content-Disposition parameters, or `NULL`
Returns : | `TRUE` if `hdrs` contains a "Content-Disposition" header, `FALSE` if not (in which case *`disposition` and *`params` will be unchanged).

Since 2.26

### soup_message_headers_set_content_disposition ()

    void                soup_message_headers_set_content_disposition
                                                            (SoupMessageHeaders *hdrs,
                                                             const char *disposition,
                                                             GHashTable *params);

Sets the "Content-Disposition" header in `hdrs` to `disposition`, optionally with additional parameters specified in `params`.

See `soup_message_headers_get_content_disposition()` for a discussion of how Content-Disposition is used in HTTP.

`hdrs` : | a SoupMessageHeaders
`disposition` : | the disposition-type
`params` : | additional parameters, or `NULL`

Since 2.26

### SoupRange

    typedef struct {
    	goffset start;
    	goffset end;
    } SoupRange;

Represents a byte range as used in the Range header.

If `end` is non-negative, then `start` and `end` represent the bounds of of the range, counting from `0`. (Eg, the first 500 bytes would be represented as `start` = `0` and `end` = `499`.)

If `end` is `-1` and `start` is non-negative, then this represents a range starting at `start` and ending with the last byte of the requested resource body. (Eg, all but the first 500 bytes would be `start` = `500`, and `end` = `-1`.)

If `end` is `-1` and `start` is negative, then it represents a "suffix range", referring to the last -`start` bytes of the resource body. (Eg, the last 500 bytes would be `start` = `-500` and `end` = `-1`.)

goffset `start`; | the start of the range
goffset `end`; | the end of the range

Since 2.26

### soup_message_headers_get_ranges ()

    gboolean            soup_message_headers_get_ranges     (SoupMessageHeaders *hdrs,
                                                             goffset total_length,
                                                             SoupRange **ranges,
                                                             int *length);

Parses `hdrs`'s Range header and returns an array of the requested byte ranges. The returned array must be freed with `soup_message_headers_free_ranges()`.

If `total_length` is non-0, its value will be used to adjust the returned ranges to have explicit start and end values, and the returned ranges will be sorted and non-overlapping. If `total_length` is 0, then some ranges may have an end value of -1, as described under SoupRange, and some of the ranges may be redundant.

`hdrs` : | a SoupMessageHeaders
`total_length` : | the total_length of the response body
`ranges` : | return location for an array of SoupRange
`length` : | the length of the returned array
Returns : | `TRUE` if `hdrs` contained a "Range" header containing byte ranges which could be parsed, `FALSE` otherwise (in which case `range` and `length` will not be set).

Since 2.26

### soup_message_headers_set_ranges ()

    void                soup_message_headers_set_ranges     (SoupMessageHeaders *hdrs,
                                                             SoupRange *ranges,
                                                             int length);

Sets `hdrs`'s Range header to request the indicated ranges. (If you only want to request a single range, you can use `soup_message_headers_set_range()`.)

`hdrs` : | a SoupMessageHeaders
`ranges` : | an array of SoupRange
`length` : | the length of `range`

Since 2.26

### soup_message_headers_set_range ()

    void                soup_message_headers_set_range      (SoupMessageHeaders *hdrs,
                                                             goffset start,
                                                             goffset end);

Sets `hdrs`'s Range header to request the indicated range. `start` and `end` are interpreted as in a SoupRange.

If you need to request multiple ranges, use `soup_message_headers_set_ranges()`.

`hdrs` : | a SoupMessageHeaders
`start` : | the start of the range to request
`end` : | the end of the range to request

Since 2.26

### soup_message_headers_free_ranges ()

    void                soup_message_headers_free_ranges    (SoupMessageHeaders *hdrs,
                                                             SoupRange *ranges);

Frees the array of ranges returned from `soup_message_headers_get_ranges()`.

`hdrs` : | a SoupMessageHeaders
`ranges` : | an array of SoupRange

Since 2.26

### soup_message_headers_get_content_range ()

    gboolean            soup_message_headers_get_content_range
                                                            (SoupMessageHeaders *hdrs,
                                                             goffset *start,
                                                             goffset *end,
                                                             goffset *total_length);

Parses `hdrs`'s Content-Range header and returns it in `start`, `end`, and `total_length`. If the total length field in the header was specified as "*", then `total_length` will be set to -1.

`hdrs` : | a SoupMessageHeaders
`start` : | return value for the start of the range
`end` : | return value for the end of the range
`total_length` : | return value for the total length of the resource, or `NULL` if you don't care.
Returns : | `TRUE` if `hdrs` contained a "Content-Range" header containing a byte range which could be parsed, `FALSE` otherwise.

Since 2.26

### soup_message_headers_set_content_range ()

    void                soup_message_headers_set_content_range
                                                            (SoupMessageHeaders *hdrs,
                                                             goffset start,
                                                             goffset end,
                                                             goffset total_length);

Sets `hdrs`'s Content-Range header according to the given values. (Note that `total_length` is the total length of the entire resource that this is a range of, not simply `end` - `start` + 1.)

`hdrs` : | a SoupMessageHeaders
`start` : | the start of the range
`end` : | the end of the range
`total_length` : | the total length of the resource, or -1 if unknown

Since 2.26

## See Also

SoupMessage