![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
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);
SoupMessageHeaders represents the HTTP message headers associated with a request or response.
typedef enum { SOUP_MESSAGE_HEADERS_REQUEST, SOUP_MESSAGE_HEADERS_RESPONSE } SoupMessageHeadersType;
Value passed to soup_message_headers_new()
to set certain default
behaviors.
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.)
|
the type of headers |
Returns : |
a new SoupMessageHeaders |
void soup_message_headers_free (SoupMessageHeaders *hdrs);
Frees hdrs
.
|
a SoupMessageHeaders |
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
.
|
a SoupMessageHeaders |
|
the header name to add |
|
the new value of name
|
void soup_message_headers_replace (SoupMessageHeaders *hdrs, const char *name, const char *value);
Replaces the value of the header name
in hdrs
with value
.
|
a SoupMessageHeaders |
|
the header name to replace |
|
the new value of name
|
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.
|
a SoupMessageHeaders |
|
the header name to remove |
void soup_message_headers_clear (SoupMessageHeaders *hdrs);
Clears hdrs
.
|
a SoupMessageHeaders |
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.
|
a SoupMessageHeaders |
|
header name |
Returns : |
the header's value or NULL if not found.
|
void (*SoupMessageHeadersForeachFunc) (const char *name, const char *value, gpointer user_data);
The callback passed to soup_message_headers_foreach()
.
|
the header name |
|
the header value |
|
the data passed to 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
.
|
a SoupMessageHeaders |
|
callback function to run for each header |
|
data to pass to func
|
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.
void soup_message_headers_iter_init (SoupMessageHeadersIter *iter, SoupMessageHeaders *hdrs);
Initializes iter
for iterating hdrs
.
|
a pointer to a SoupMessageHeadersIter structure
|
|
a SoupMessageHeaders
|
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.
|
a SoupMessageHeadersIter
|
|
pointer to a variable to return the header name in |
|
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.
|
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
unknown / error | |
no body is present (which is not the same as a 0-length body, and only occurs in certain places) | |
Content-Length encoding | |
Response body ends when the connection is closed | |
chunked encoding (currently only supported for response) | |
multipart/byteranges (Reserved for future use: NOT CURRENTLY IMPLEMENTED) |
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.
|
a SoupMessageHeaders |
Returns : |
the encoding declared by hdrs .
|
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.
|
a SoupMessageHeaders |
|
a SoupEncoding |
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
.
|
a SoupMessageHeaders |
Returns : |
the message body length declared by hdrs .
|
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.
|
a SoupMessageHeaders |
|
the message body length |
typedef enum { SOUP_EXPECTATION_UNRECOGNIZED = (1 << 0), SOUP_EXPECTATION_CONTINUE = (1 << 1) } SoupExpectation;
Represents the parsed value of the "Expect" header.
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
.
|
a SoupMessageHeaders |
Returns : |
the contents of hdrs 's "Expect" header
|
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.
|
a SoupMessageHeaders |
|
the expectations to set |