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

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;


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

hdrs :

a SoupMessageHeaders

func :

callback function to run for each header

user_data :

data to pass to func

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;


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