![]() |
![]() |
![]() |
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_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);
SoupMessageHeaders represents the HTTP message headers associated with a request or response.
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.
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 |
void soup_message_headers_free (SoupMessageHeaders *hdrs);
Frees hdrs
.
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
. (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
|
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
|
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 |
void soup_message_headers_clear (SoupMessageHeaders *hdrs);
Clears hdrs
.
hdrs : |
a SoupMessageHeaders |
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
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
const char* soup_message_headers_get (SoupMessageHeaders *hdrs, const char *name);
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() .
|
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()
|
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
|
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
.
iter : |
a pointer to a SoupMessageHeadersIter structure
|
hdrs : |
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.
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.
|
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
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 .
|
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 |
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 .
|
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 |
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
.
hdrs : |
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.
hdrs : |
a SoupMessageHeaders |
expectations : |
the expectations to set |
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
|
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
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
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
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
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
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
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
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
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
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
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