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: 15 April 2025
.\"    Manual: neon API reference
.\"    Source: neon 0.34.2
.\"  Language: English
.\"
.TH "NE_REQUEST_CREATE" "3" "15 April 2025" "neon 0.34.2" "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\ *" "target" ");"
.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
\fItarget\fR, parameter, and the method to be performed on that resource via the
\fImethod\fR
parameter\&.
.PP
The
\fItarget\fR
string used must conform to the
request\-target
definition given in
\m[blue]\fBRFC 9112\fR\m[]\&\s-2\u[1]\d\s+2\&. Usually this will take the
abolute\-path
form, which optionally includes a query string\&.
.PP
To
\fIdispatch\fR
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\&.
\fIDispatching\fR
a request may require multiple iterations of a request being sent and response received, for example if authentication is used (see
ne_set_server_auth), or if a persistent connection times out; this is handled internally by
\fBne_request_dispatch\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
Request methods are assumed to be
\m[blue]\fBidempotent\fR\m[]\&\s-2\u[2]\d\s+2
by default\&. For a request using a non\-idempotent method such as
POST, the
NE_REQFLAG_IDEMPOTENT
flag must be disabled using
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 "NOTES"
.PP
The
\fIpath\fR,
\fImethod\fR
and
\fItarget\fR
parameters of
\fBne_request_create\fR
are used directly in request data without validation, so must not be taken from untrusted sources\&. For example, allowing insertion of unescaped CR, LF or other control characters in these parameters may result in unexpected or insecure behaviour\&.
.PP
neon does not impose any length restrictions on request input data\&.
.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 "COPYRIGHT"
.br
Copyright \(co 2001-2024 Joe Orton
.br
.SH "REFERENCES"
.IP " 1." 4
RFC 9112
.RS 4
\%https://www.rfc-editor.org/rfc/rfc9112
.RE
.IP " 2." 4
idempotent
.RS 4
\%https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods
.RE