ne_request_create.3

linux subdivision ying gai ke yi le ba

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "NE_REQUEST_CREATE" 3 "5 July 2004" "neon 0.24.7" "neon API reference"
.SH NAME
ne_request_create, ne_request_dispatch, ne_request_destroy \- low-level HTTP request handling
.SH "SYNOPSIS"
.ad l
.hy 0

#include <ne_request\&.h>
.sp
.HP 31
ne_request\ *\fBne_request_create\fR\ (ne_session\ *\fIsession\fR, const\ char\ *\fImethod\fR, const\ char\ *\fIpath\fR);
.HP 25
int\ \fBne_request_dispatch\fR\ (ne_request\ *\fIreq\fR);
.HP 25
void\ \fBne_request_destroy\fR\ (ne_request\ *\fIreq\fR);
.ad
.hy

.SH "DESCRIPTION"

.PP
An HTTP request, represented by the \fBne_request\fR type, specifies that some operation is to be performed on some resource\&. The \fBne_request_create\fR function creates a request object, specifying the operation in the \fImethod\fR parameter\&. The location of the resource is determined by the server in use for the session given by the \fIsess\fR parameter, combined with the \fIpath\fR parameter\&.

.PP
The \fIpath\fR 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 \fBne_path_escape\fR)\&. If the string comes from an untrusted source, failure to perform URI\-escaping results in a security vulnerability\&.

.PP
To dispatch a request, and process the response, the \fBne_request_dispatch\fR function can be used\&. An alternative is to use the (more complex, but more flexible) combination of the \fBne_begin_request\fR, \fBne_end_request\fR, and \fBne_read_response_block\fR functions; see \fBne_begin_request\fR\&.

.PP
To add extra headers in the request, the functions \fBne_add_request_header\fR(3) and \fBne_print_request_header\fR(3) can be used\&. To include a message body with the request, one of the functions \fBne_set_request_body_buffer\fR, \fBne_set_request_body_fd\fR(3), or \fBne_set_request_body_provider\fR can be used\&.

.PP
The return value of \fBne_request_dispatch\fR indicates merely whether the request was sent and the response read successfully\&. To discover the result of the operation, \fBne_get_status\fR(3), along with any processing of the response headers and message body\&.

.PP
A request can only be dispatched once: calling \fBne_request_dispatch\fR more than once on a single \fBne_request\fR object produces undefined behaviour\&. Once all processing associated with the request object is complete, use the \fBne_request_destroy\fR function to destroy the resources associated with it\&. Any subsequent use of the request object produces undefined behaviour\&.

.SH "RETURN VALUE"

.PP
The \fBne_request_create\fR function returns a pointer to a request object (and never NULL)\&.

.PP
The \fBne_request_dispatch\fR function returns zero if the request was dispatched successfully, and a non\-zero error code otherwise\&.

.SH "ERRORS"

.TP
\fBNE_ERROR\fR
Request failed (see session error string)

.TP
\fBNE_LOOKUP\fR
The DNS lookup for the server (or proxy server) failed\&.

.TP
\fBNE_AUTH\fR
Authentication failed on the server\&.

.TP
\fBNE_PROXYAUTH\fR
Authentication failed on the proxy server\&.

.TP
\fBNE_CONNECT\fR
A connection to the server could not be established\&.

.TP
\fBNE_TIMEOUT\fR
A timeout occurred while waiting for the server to respond\&.

.SH "EXAMPLE"

.PP
An example of applying a MKCOL operation to the resource at the locationhttp://www\&.example\&.com/foo/bar/:

.nf
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);
.fi

.SH "SEE ALSO"

.PP
\fBne_get_error\fR(3), \fBne_set_error\fR(3), \fBne_get_status\fR(3), \fBne_add_request_header\fR(3), \fBne_set_request_body_buffer\fR(3)\&.

.SH AUTHOR
Joe Orton <neon@webdav\&.org>.