winscp/libs/neon/doc/man/ne_request_create.3

'\" t
.\"     Title: ne_request_create
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 21 January 2023
.\"    Manual: neon API reference
.\"    Source: neon 0.32.5
.\"  Language: English
.\"
.TH "NE_REQUEST_CREATE" "3" "21 January 2023" "neon 0.32.5" "neon API reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ne_request_create, ne_request_dispatch, ne_request_destroy \- low\-level HTTP request handling
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <ne_request\&.h>
.fi
.ft
.HP \w'ne_request\ *ne_request_create('u
.BI "ne_request *ne_request_create(ne_session\ *" "session" ", const\ char\ *" "method" ", const\ char\ *" "path" ");"
.HP \w'int\ ne_request_dispatch('u
.BI "int ne_request_dispatch(ne_request\ *" "req" ");"
.HP \w'void\ ne_request_destroy('u
.BI "void ne_request_destroy(ne_request\ *" "req" ");"
.SH "DESCRIPTION"
.PP
The
\fBne_request\fR
object represents an HTTP request and the associated response\&. The
\fBne_request_create\fR
function creates a new request object for the given
\fIsession\fR\&. The target resource for the request is identified by the
\fIpath\fR, and the method to be performed on that resource via the
\fImethod\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
ne_add_request_header
and
ne_print_request_header
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, 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,
ne_get_status, 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\&.
.PP
For a request with a non\-idempotent method such as
POST, the
NE_REQFLAG_IDEMPOTENT
flag should be disabled; see
ne_set_request_flag\&.
.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"
.PP
\fBNE_ERROR\fR
.RS 4
Request failed (see session error string)
.RE
.PP
\fBNE_LOOKUP\fR
.RS 4
The DNS lookup for the server (or proxy server) failed\&.
.RE
.PP
\fBNE_AUTH\fR
.RS 4
Authentication failed on the server\&.
.RE
.PP
\fBNE_PROXYAUTH\fR
.RS 4
Authentication failed on the proxy server\&.
.RE
.PP
\fBNE_CONNECT\fR
.RS 4
A connection to the server could not be established\&.
.RE
.PP
\fBNE_TIMEOUT\fR
.RS 4
A timeout occurred while waiting for the server to respond\&.
.RE
.SH "EXAMPLE"
.PP
An example of applying a
MKCOL
operation to the resource at the location
http://www\&.example\&.com/foo/bar/:
.sp
.if n \{\
.RS 4
.\}
.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\en", ne_get_error(sess));
}
ne_request_destroy(req);
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
ne_get_error,
ne_set_error,
ne_get_status,
ne_add_request_header,
ne_set_request_body_buffer,
ne_set_request_flag\&.
.SH "AUTHOR"
.PP
\fBJoe Orton\fR
.RS 4
Author.
.RE
.SH "COPYRIGHT"
.br