diff options
Diffstat (limited to 'libsoup/soup-headers.c')
| -rw-r--r-- | libsoup/soup-headers.c | 117 |
1 files changed, 53 insertions, 64 deletions
diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c index 5485e623..8b04a834 100644 --- a/libsoup/soup-headers.c +++ b/libsoup/soup-headers.c @@ -18,15 +18,6 @@ #include "soup.h" /** - * SECTION:soup-headers - * @section_id: SoupHeaders - * @title: SoupHeaders - * @short_description: Functions to help working with HTTP Headers - * - * These are utility functions to help working with HTTP headers. - */ - -/** * soup_headers_parse: * @str: the header string (including the Request-Line or Status-Line, * but not the trailing blank line) @@ -34,14 +25,14 @@ * @dest: #SoupMessageHeaders to store the header values in * * Parses the headers of an HTTP request or response in @str and - * stores the results in @dest. Beware that @dest may be modified even - * on failure. + * stores the results in @dest. + * + * Beware that @dest may be modified even on failure. * * This is a low-level method; normally you would use - * soup_headers_parse_request() or soup_headers_parse_response(). + * [func@headers_parse_request] or [func@headers_parse_response]. * * Returns: success or failure - * **/ gboolean soup_headers_parse (const char *str, int len, SoupMessageHeaders *dest) @@ -170,11 +161,11 @@ done: * @len: length of @str * @req_headers: #SoupMessageHeaders to store the header values in * @req_method: (out) (optional): if non-%NULL, will be filled in with the - * request method + * request method * @req_path: (out) (optional): if non-%NULL, will be filled in with the - * request path + * request path * @ver: (out) (optional): if non-%NULL, will be filled in with the HTTP - * version + * version * * Parses the headers of an HTTP request in @str and stores the * results in @req_method, @req_path, @ver, and @req_headers. @@ -182,7 +173,7 @@ done: * Beware that @req_headers may be modified even on failure. * * Returns: %SOUP_STATUS_OK if the headers could be parsed, or an - * HTTP error to be returned to the client if they could not be. + * HTTP error to be returned to the client if they could not be. **/ guint soup_headers_parse_request (const char *str, @@ -280,15 +271,16 @@ soup_headers_parse_request (const char *str, * soup_headers_parse_status_line: * @status_line: an HTTP Status-Line * @ver: (out) (optional): if non-%NULL, will be filled in with the HTTP - * version + * version * @status_code: (out) (optional): if non-%NULL, will be filled in with - * the status code + * the status code * @reason_phrase: (out) (optional): if non-%NULL, will be filled in with - * the reason phrase + * the reason phrase * * Parses the HTTP Status-Line string in @status_line into @ver, - * @status_code, and @reason_phrase. @status_line must be terminated by - * either "\0" or "\r\n". + * @status_code, and @reason_phrase. + * + * @status_line must be terminated by either "\0" or "\r\n". * * Returns: %TRUE if @status_line was parsed successfully. **/ @@ -357,11 +349,11 @@ soup_headers_parse_status_line (const char *status_line, * @len: length of @str * @headers: #SoupMessageHeaders to store the header values in * @ver: (out) (optional): if non-%NULL, will be filled in with the HTTP - * version + * version * @status_code: (out) (optional): if non-%NULL, will be filled in with - * the status code + * the status code * @reason_phrase: (out) (optional): if non-%NULL, will be filled in with - * the reason phrase + * the reason phrase * * Parses the headers of an HTTP response in @str and stores the * results in @ver, @status_code, @reason_phrase, and @headers. @@ -488,12 +480,12 @@ parse_list (const char *header, char delim) * soup_header_parse_list: * @header: a header value * - * Parses a header whose content is described by RFC2616 as - * "#something", where "something" does not itself contain commas, - * except as part of quoted-strings. + * Parses a header whose content is described by RFC2616 as `#something`. + * + * "something" does not itself contain commas, except as part of quoted-strings. * * Returns: (transfer full) (element-type utf8): a #GSList of - * list elements, as allocated strings + * list elements, as allocated strings **/ GSList * soup_header_parse_list (const char *header) @@ -526,7 +518,7 @@ sort_by_qval (const void *a, const void *b) * soup_header_parse_quality_list: * @header: a header value * @unacceptable: (out) (optional) (transfer full) (element-type utf8): on - * return, will contain a list of unacceptable values + * return, will contain a list of unacceptable values * * Parses a header whose content is a list of items with optional * "qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding, @@ -537,7 +529,7 @@ sort_by_qval (const void *a, const void *b) * the main list. * * Returns: (transfer full) (element-type utf8): a #GSList of - * acceptable values (as allocated strings), highest-qvalue first. + * acceptable values (as allocated strings), highest-qvalue first. **/ GSList * soup_header_parse_quality_list (const char *header, GSList **unacceptable) @@ -613,8 +605,8 @@ soup_header_parse_quality_list (const char *header, GSList **unacceptable) /** * soup_header_free_list: (skip) - * @list: a #GSList returned from soup_header_parse_list() or - * soup_header_parse_quality_list() + * @list: a #GSList returned from [func@header_parse_list] or + * [func@header_parse_quality_list] * * Frees @list. **/ @@ -627,12 +619,13 @@ soup_header_free_list (GSList *list) /** * soup_header_contains: * @header: An HTTP header suitable for parsing with - * soup_header_parse_list() + * [func@header_parse_list] * @token: a token * * Parses @header to see if it contains the token @token (matched - * case-insensitively). Note that this can't be used with lists - * that have qvalues. + * case-insensitively). + * + * Note that this can't be used with lists that have qvalues. * * Returns: whether or not @header contains @token **/ @@ -786,7 +779,7 @@ parse_param_list (const char *header, char delim, gboolean strict) * @header: a header value * * Parses a header which is a comma-delimited list of something like: - * <literal>token [ "=" ( token | quoted-string ) ]</literal>. + * `token [ "=" ( token | quoted-string ) ]`. * * Tokens that don't have an associated value will still be added to * the resulting hash table, but with a %NULL value. @@ -796,8 +789,8 @@ parse_param_list (const char *header, char delim, gboolean strict) * header). * * Returns: (element-type utf8 utf8) (transfer full): a - * #GHashTable of list elements, which can be freed with - * soup_header_free_param_list(). + * #GHashTable of list elements, which can be freed with + * [func@header_free_param_list]. **/ GHashTable * soup_header_parse_param_list (const char *header) @@ -812,7 +805,7 @@ soup_header_parse_param_list (const char *header) * @header: a header value * * Parses a header which is a semicolon-delimited list of something - * like: <literal>token [ "=" ( token | quoted-string ) ]</literal>. + * like: `token [ "=" ( token | quoted-string ) ]`. * * Tokens that don't have an associated value will still be added to * the resulting hash table, but with a %NULL value. @@ -822,9 +815,8 @@ soup_header_parse_param_list (const char *header) * header). * * Returns: (element-type utf8 utf8) (transfer full): a - * #GHashTable of list elements, which can be freed with - * soup_header_free_param_list(). - * + * #GHashTable of list elements, which can be freed with + * [func@header_free_param_list]. **/ GHashTable * soup_header_parse_semi_param_list (const char *header) @@ -838,19 +830,19 @@ soup_header_parse_semi_param_list (const char *header) * soup_header_parse_param_list_strict: * @header: a header value * - * A strict version of soup_header_parse_param_list() + * A strict version of [func@header_parse_param_list] * that bails out if there are duplicate parameters. + * * Note that this function will treat RFC5987-encoded * parameters as duplicated if an ASCII version is also * present. For header fields that might contain * RFC5987-encoded parameters, use - * soup_header_parse_param_list() instead. + * [func@header_parse_param_list] instead. * * Returns: (element-type utf8 utf8) (transfer full) (nullable): - * a #GHashTable of list elements, which can be freed with - * soup_header_free_param_list() or %NULL if there are duplicate - * elements. - * + * a #GHashTable of list elements, which can be freed with + * [func@header_free_param_list] or %NULL if there are duplicate + * elements. **/ GHashTable * soup_header_parse_param_list_strict (const char *header) @@ -864,19 +856,19 @@ soup_header_parse_param_list_strict (const char *header) * soup_header_parse_semi_param_list_strict: * @header: a header value * - * A strict version of soup_header_parse_semi_param_list() + * A strict version of [func@header_parse_semi_param_list] * that bails out if there are duplicate parameters. + * * Note that this function will treat RFC5987-encoded * parameters as duplicated if an ASCII version is also * present. For header fields that might contain * RFC5987-encoded parameters, use - * soup_header_parse_semi_param_list() instead. + * [func@header_parse_semi_param_list] instead. * * Returns: (element-type utf8 utf8) (transfer full) (nullable): - * a #GHashTable of list elements, which can be freed with - * soup_header_free_param_list() or %NULL if there are duplicate - * elements. - * + * a #GHashTable of list elements, which can be freed with + * [func@header_free_param_list] or %NULL if there are duplicate + * elements. **/ GHashTable * soup_header_parse_semi_param_list_strict (const char *header) @@ -888,8 +880,8 @@ soup_header_parse_semi_param_list_strict (const char *header) /** * soup_header_free_param_list: - * @param_list: (element-type utf8 utf8): a #GHashTable returned from soup_header_parse_param_list() - * or soup_header_parse_semi_param_list() + * @param_list: (element-type utf8 utf8): a #GHashTable returned from + * [func@header_parse_param_list] or [func@header_parse_semi_param_list] * * Frees @param_list. **/ @@ -972,12 +964,11 @@ append_param_internal (GString *string, * @name: a parameter name * @value: a parameter value * - * Appends something like <literal>@name="@value"</literal> to + * Appends something like `name="value"` to * @string, taking care to escape any quotes or backslashes in @value. * * If @value is (non-ASCII) UTF-8, this will instead use RFC 5987 - * encoding, just like soup_header_g_string_append_param(). - * + * encoding, just like [func@header_g_string_append_param]. **/ void soup_header_g_string_append_param_quoted (GString *string, @@ -997,9 +988,8 @@ soup_header_g_string_append_param_quoted (GString *string, * @name: a parameter name * @value: a parameter value, or %NULL * - * Appends something like <literal>@name=@value</literal> to @string, - * taking care to quote @value if needed, and if so, to escape any - * quotes or backslashes in @value. + * Appends something like `name=value` to @string, taking care to quote @value + * if needed, and if so, to escape any quotes or backslashes in @value. * * Alternatively, if @value is a non-ASCII UTF-8 string, it will be * appended using RFC5987 syntax. Although in theory this is supposed @@ -1008,7 +998,6 @@ soup_header_g_string_append_param_quoted (GString *string, * "filename" parameter. * * If @value is %NULL, this will just append @name to @string. - * **/ void soup_header_g_string_append_param (GString *string, |