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 *path`)`;

`int ne_request_dispatch(` | ne_request *req`)`;

`void ne_request_destroy(` | ne_request *req`)`;

## Description

An HTTP request, represented by the ne_request type, specifies that some operation is to be performed on some resource. The `ne_request_create` function creates a request object, specifying the operation in the `method` parameter. The location of the resource is determined by the server in use for the session given by the `sess` parameter, combined with the `path` parameter.

The `path` string used must conform to the `abs_path` definition given in RFC2396, with an optional "?query" part, and must be URI-escaped by the caller (for instance, using `ne_path_escape`). If the string comes from an untrusted source, failure to perform URI-escaping results in a security vulnerability.

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`.

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.

If a request is being using a non-idempotent method such as `POST`, the `NE_REQFLAG_IDEMPOTENT` flag should be disabled; see 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 otherwise.

## Errors

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.

## 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_get_error, ne_set_error, ne_get_status, ne_add_request_header, ne_set_request_body_buffer, ne_set_request_flag.

Prev | Up | Next
ne_set_session_flag | Home | ne_add_request_header