ne_request_create
3

# ne_request_create

# ne_request_dispatch

# ne_request_destroy

low-level HTTP request handling

    	  #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 and can be used. To include a message body with the request, one of the functions `ne_set_request_body_buffer`, , 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, , 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 .

## 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

, , , , , .