ne_set_request_body_buffer
Prev | neon API reference | Next

## Name

ne_set_request_body_buffer, ne_set_request_body_fd, ne_set_request_body_provider — include a message body with a request

## Synopsis

    #include <ne_request.h>

`void ne_set_request_body_buffer(` | ne_request *req,
| const char *buf,
| size_t count`)`;

`int ne_set_request_body_fd(` | ne_request *req,
| int fd,
| ne_off_t begin,
| ne_off_t length`)`;

`typedef ssize_t (*ne_provide_body)(` | void *userdata,
| char *data,
| size_t buflen`)`;

`int ne_set_request_body_provider(` | ne_request *req,
| ne_off_t length,
| ne_provide_body provider,
| void *userdata`)`;

## Description

The `ne_set_request_body_buffer` function specifies that a message body should be included with the body, which is stored in the `count` bytes buffer `buf`.

The `ne_set_request_body_fd` function can be used to include a message body with a request which is read from a file descriptor. The body is read from the file descriptor `fd`, which must be a associated with a seekable file (not a pipe, socket, or FIFO). `count` bytes are read, beginning at offset `begin` (hence, passing `begin` as zero means the body is read from the beginning of the file).

For both above functions, the source of the request body must survive until the request has been dispatched; neither the memory buffer passed to `ne_set_request_body_buffer` nor the file descriptor passed to `ne_set_request_body_fd` are copied internally.

The `ne_set_request_body_provider` function can be used to include a message body with a request which is provided by a callback function. The body length passed in the `length` paramater must be positive, or if a chunked request body is required, as covered below, `-1` can be used.

Before sending the body, the callback is invoked once with the `buflen` parameter as `0`. The body is then read by invoking the callback repeatedly until it returns `0` indicating the end-of-body. The callback return value must be as follows:

less than `0` | An error; the request will be aborted. The session error string must be set via `ne_set_error`.
`0` | End of body.
between `0` and `buflen` | Number of bytes of request body data.

### Chunked request bodies

Chunked request bodies are only sent when `ne_set_request_body_provider` is used and `-1` is passed as the `length`. In this case, the length of the request body does not have to be determined ahead of time. The end of the request body is indicated by returning `0` from the callback function.

Before using a chunked request body, the caller must determine that HTTP/1.1 is supported (by the origin server and any HTTP proxy server configured). This can be done by testing that `ne_version_pre_http11` returns zero after performing an `OPTIONS` or `HEAD` request.

## See also

ne_request_create, ne_set_error

Prev | Up | Next
ne_set_request_flag | Home | ne_get_request_target