SoupMessageHeaders

SoupMessageHeaders — HTTP message headers

Functions

Object Hierarchy

    GBoxed
    ╰── SoupMessageHeaders

Includes

#include <libsoup/soup.h>

Description

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

Functions

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

Parameters

type

the type of headers

 

Returns

a new SoupMessageHeaders


soup_message_headers_free ()

void
soup_message_headers_free (SoupMessageHeaders *hdrs);

Frees hdrs .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

hdrs

a SoupMessageHeaders

 

name

the header name to remove

 

soup_message_headers_clear ()

void
soup_message_headers_clear (SoupMessageHeaders *hdrs);

Clears hdrs .

Parameters

hdrs

a SoupMessageHeaders

 

soup_message_headers_clean_connection_headers ()

void
soup_message_headers_clean_connection_headers
                               (SoupMessageHeaders *hdrs);

Removes all the headers listed in the Connection header.

Parameters

hdrs

a SoupMessageHeaders

 

Since: 2.36


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

Parameters

hdrs

a SoupMessageHeaders

 

name

header name

 

Returns

the header's value or NULL if not found.

[nullable]

Since: 2.28


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.

Parameters

hdrs

a SoupMessageHeaders

 

name

header name

 

Returns

the header's value or NULL if not found.

[nullable]

Since: 2.28


soup_message_headers_get_headers_type ()

SoupMessageHeadersType
soup_message_headers_get_headers_type (SoupMessageHeaders *hdrs);

Gets the type of headers.

Parameters

hdrs

a SoupMessageHeaders

 

Returns

the header's type.

Since: 2.50


soup_message_headers_header_contains ()

gboolean
soup_message_headers_header_contains (SoupMessageHeaders *hdrs,
                                      const char *name,
                                      const char *token);

Checks whether the list-valued header name is present in hdrs , and contains a case-insensitive match for token .

(If name is present in hdrs , then this is equivalent to calling soup_header_contains() on its value.)

Parameters

hdrs

a SoupMessageHeaders

 

name

header name

 

token

token to look for

 

Returns

TRUE if the header is present and contains token , FALSE otherwise.

Since: 2.50


soup_message_headers_header_equals ()

gboolean
soup_message_headers_header_equals (SoupMessageHeaders *hdrs,
                                    const char *name,
                                    const char *value);

Checks whether the header name is present in hdrs and is (case-insensitively) equal to value .

Parameters

hdrs

a SoupMessageHeaders

 

name

header name

 

value

expected value

 

Returns

TRUE if the header is present and its value is value , FALSE otherwise.

Since: 2.50


SoupMessageHeadersForeachFunc ()

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

The callback passed to soup_message_headers_foreach().

Parameters

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 .

Parameters

hdrs

a SoupMessageHeaders

 

func

callback function to run for each header.

[scope call]

user_data

data to pass to func

 

soup_message_headers_iter_init ()

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

Initializes iter for iterating hdrs .

Parameters

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.

Parameters

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.


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

hdrs

a SoupMessageHeaders

 

content_length

the message body length

 

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.

Parameters

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.

Parameters

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.

Parameters

hdrs

a SoupMessageHeaders

 

params

return location for the Content-Type parameters (eg, "charset"), or NULL.

[out][element-type utf8 utf8][allow-none][transfer full]

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

[nullable]

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 .

Parameters

hdrs

a SoupMessageHeaders

 

content_type

the MIME type

 

params

additional parameters, or NULL.

[allow-none][element-type utf8 utf8]

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.

Parameters

hdrs

a SoupMessageHeaders

 

disposition

return location for the disposition-type, or NULL.

[out][transfer full]

params

return location for the Content-Disposition parameters, or NULL.

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

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.

Parameters

hdrs

a SoupMessageHeaders

 

disposition

the disposition-type

 

params

additional parameters, or NULL.

[allow-none][element-type utf8 utf8]

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.

Beware that even if given a total_length , this function does not check that the ranges are satisfiable.

SoupServer has built-in handling for range requests. If your server handler returns a SOUP_STATUS_OK response containing the complete response body (rather than pausing the message and returning some of the response body later), and there is a Range header in the request, then libsoup will automatically convert the response to a SOUP_STATUS_PARTIAL_CONTENT response containing only the range(s) requested by the client. The only time you need to process the Range header yourself is if either you need to stream the response body rather than returning it all at once, or you do not already have the complete response body available, and only want to generate the parts that were actually requested by the client.

Parameters

hdrs

a SoupMessageHeaders

 

total_length

the total_length of the response body

 

ranges

return location for an array of SoupRange.

[out][array length=length]

length

the length of the returned array

 

Returns

TRUE if hdrs contained a syntactically-valid "Range" header, 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().)

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

SoupServer has built-in handling for range requests, and you do not normally need to call this function youself. See soup_message_headers_get_ranges() for more details.

Parameters

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

Types and Values

SoupMessageHeaders

typedef struct SoupMessageHeaders SoupMessageHeaders;

The HTTP message headers associated with a request or response.


enum SoupMessageHeadersType

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

Members

SOUP_MESSAGE_HEADERS_REQUEST

request headers

 

SOUP_MESSAGE_HEADERS_RESPONSE

response headers

 

SOUP_MESSAGE_HEADERS_MULTIPART

multipart body part headers

 

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.


enum SoupEncoding

How a message body is encoded for transport

Members

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)

 

enum SoupExpectation

Represents the parsed value of the "Expect" header.

Members

SOUP_EXPECTATION_UNRECOGNIZED

any unrecognized expectation

 

SOUP_EXPECTATION_CONTINUE

"100-continue"

 

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

Members

goffset start;

the start of the range

 

goffset end;

the end of the range

 

Since: 2.26

See Also

SoupMessage