ne_request_create
Prev | neon API reference | Next

## Name

ne_request_create, ne_request_dispatch, ne_request_destroy — low-level HTTP request handling

## Synopsis

    #include <ne_request.h>

``ne_request *ne_request_create(`ne_session *session, const char *method, const char *target`)`;`
``int ne_request_dispatch(`ne_request *req`)`;`
``void ne_request_destroy(`ne_request *req`)`;`

## Description

The ne_request object represents an HTTP request and the associated response. The `ne_request_create` function creates a new request object for the given `session`. The target resource for the request is identified by the `target`, parameter, and the method to be performed on that resource via the `method` parameter.

The `target` string used must conform to the `request-target` definition given in RFC 9112. Usually this will take the `abolute-path` form, which optionally includes a query string.

To dispatch a request, and process the response, the `ne_request_dispatch` function can be used. An alternative is to use the (more complex, but more flexible) combination of the `ne_begin_request`, `ne_end_request`, and `ne_read_response_block` functions; see `ne_begin_request`. Dispatching a request may require multiple iterations of a request being sent and response received, for example if authentication is used (see ne_set_server_auth), or if a persistent connection times out; this is handled internally by `ne_request_dispatch`.

To add extra headers in the request, the functions ne_add_request_header and ne_print_request_header can be used. To include a message body with the request, one of the functions `ne_set_request_body_buffer`, `ne_set_request_body_fd`, or `ne_set_request_body_provider` can be used.

The return value of `ne_request_dispatch` indicates merely whether the request was sent and the response read successfully. To discover the result of the operation, ne_get_status, along with any processing of the response headers and message body.

A request can only be dispatched once: calling `ne_request_dispatch` more than once on a single ne_request object produces undefined behaviour. Once all processing associated with the request object is complete, use the `ne_request_destroy` function to destroy the resources associated with it. Any subsequent use of the request object produces undefined behaviour.

Request methods are assumed to be idempotent by default. For a request using a non-idempotent method such as `POST`, the `NE_REQFLAG_IDEMPOTENT` flag must be disabled using ne_set_request_flag.

## Return value

The `ne_request_create` function returns a pointer to a request object (and never `NULL`).

The `ne_request_dispatch` function returns zero if the request was dispatched successfully, and a non-zero error code code otherwise, as described in the following section.

## Error codes

Error codes have a non-zero value, and correspond to an `NE_*` macro definition, as listed below. Future versions of neon may introduce additional error code definitions. Functions which return an error code and have an associated session object set the session error string (see ne_get_error) unless documented otherwise.

NE_ERROR | Request failed (see session error string)
NE_LOOKUP | The DNS lookup for the server (or proxy server) failed.
NE_AUTH | Authentication failed on the server.
NE_PROXYAUTH | Authentication failed on the proxy server.
NE_CONNECT | A connection to the server could not be established.
NE_TIMEOUT | A timeout occurred while waiting for the server to respond.
NE_REDIRECT | A valid redirect was retuerned. Note: Only returned if redirect handling is registered for the session using ne_redirect_register.

## Notes

The `path`, `method` and `target` parameters of `ne_request_create` are used directly in request data without validation, so must not be taken from untrusted sources. For example, allowing insertion of unescaped CR, LF or other control characters in these parameters may result in unexpected or insecure behaviour.

neon does not impose any length restrictions on request input data.

## Example

An example of applying a `MKCOL` operation to the resource at the location `http://www.example.com/foo/bar/`:

    ne_session *sess = ne_session_create("http", "www.example.com", 80);
    ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
    if (ne_request_dispatch(req)) {
       printf("Request failed: %s\n", ne_get_error(sess));
    }
    ne_request_destroy(req);

## See also

ne_session_create, ne_get_error, ne_set_error, ne_get_status, ne_add_request_header, ne_set_request_body_buffer, ne_set_request_flag, ne_redirect_register.

Prev | Up | Next
ne_set_session_flag | Home | ne_add_request_header