SoupMessageHeaders

## SoupMessageHeaders SoupMessageHeaders — HTTP message headers |

## Synopsis

    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            (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);

## 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
    } 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_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`.

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

`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 ()

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

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

If `name` has multiple values in `hdrs`, `soup_message_headers_get()` 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 an upstream proxy could do the same thing.

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

### 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
`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
`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`
`name` : | pointer to a variable to return the header name in
`value` : | pointer to a variable to return the header value in
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

## See Also

SoupMessage