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