ne_get_response_header
Prev | neon API reference | Next

## Name

ne_get_response_header, ne_get_response_trailer, ne_response_header_iterate, ne_response_trailer_iterate — functions to access response headers and trailers

## Synopsis

    #include <ne_request.h>

``const char *ne_get_response_header(`ne_request *request, const char *name`)`;`
``const char *ne_get_response_trailer(`ne_request *req, const char *name`)`;`
``void *ne_response_header_iterate(`ne_request *request, void *cursor, const char **name, const char **value`)`;`
``void *ne_response_trailer_iterate(`ne_request *request, void *cursor, const char **name, const char **value`)`;`

## Description

To retrieve the value of a response header field, the `ne_get_response_header` function can be used, and is given the name of the header to return. If multiple HTTP response headers are received with the same name, their values are combined together in a comma-separated list.

To retrieve the value of a header from a chunked response trailer section (sent after, rather than before, the response body), `ne_get_response_trailer` can be used. This function otherwise has the same semantics as `ne_get_response_header`. Note that trailer fields are used rarely and should be interpreted with care, see RFC 9110 §6.5.

To iterate over all the response headers returned, the `ne_response_header_iterate` function can be used. This function takes a `cursor` parameter which should be `NULL` to retrieve the first header. The function stores the name and value of the next header header in the `name` and `value` parameters, and returns a new cursor pointer which can be passed to `ne_response_header_iterate` to retrieve the next header.

The `ne_response_trailer_iterate` function has the same semantics as `ne_response_header_iterate` except it operates on the response trailer fields rather than the header section.

## Return value

`ne_get_response_header` and `ne_get_response_trailer` each return a string, or `NULL` if no header or trailer field with that name was found. The return value pointer is valid only until the next call to `ne_begin_request` or `ne_request_destroy` for the same request.

Likewise, the cursor, names, and values returned by `ne_response_header_iterate` or `ne_response_trailer_iterate` are only valid until the next call to `ne_begin_request` or until the request object is destroyed.

## Examples

The following code will output the value of the `Last-Modified` header for a resource:

    ne_request *req = ne_request_create(sess, "GET", "/foo.txt");
    if (ne_request_dispatch(req) == NE_OK) {
        const char *mtime = ne_get_response_header(req, "Last-Modified");
        if (mtime) {
            printf("/foo.txt has last-modified value %s\n", mtime);
        }
    }
    ne_request_destroy(req);

## History

`ne_get_response_trailer` and `ne_response_trailer_iterate` are available in neon 0.37.0 and later. In older releases, trailer fields were merged with normal response headers and could be accessed using `ne_get_response_header` or `ne_response_header_iterate`.

## See also

ne_request_create, ne_request_destroy.

Prev | Up | Next
ne_add_request_header | Home | ne_read_response_to_fd