Debian Codegraph @

deps/libneon/doc/man/ne_request_create.3

raw
1 '\" t
2 .\" Title: ne_request_create
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NE_REQUEST_CREATE" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ne_request_create, ne_request_dispatch, ne_request_destroy \- low\-level HTTP request handling
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <ne_request\&.h>
37 .fi
38 .ft
39 .HP \w'ne_request\ *ne_request_create('u
40 .BI "ne_request *ne_request_create(ne_session\ *" "session" ", const\ char\ *" "method" ", const\ char\ *" "path" ");"
41 .HP \w'int\ ne_request_dispatch('u
42 .BI "int ne_request_dispatch(ne_request\ *" "req" ");"
43 .HP \w'void\ ne_request_destroy('u
44 .BI "void ne_request_destroy(ne_request\ *" "req" ");"
45 .SH "DESCRIPTION"
46 .PP
47 An HTTP request, represented by the
48 \fBne_request\fR
49 type, specifies that some operation is to be performed on some resource\&. The
50 \fBne_request_create\fR
51 function creates a request object, specifying the operation in the
52 \fImethod\fR
53 parameter\&. The location of the resource is determined by the server in use for the session given by the
54 \fIsess\fR
55 parameter, combined with the
56 \fIpath\fR
57 parameter\&.
58 .PP
59 The
60 \fIpath\fR
61 string used must conform to the
62 abs_path
63 definition given in RFC2396, with an optional "?query" part, and must be URI\-escaped by the caller (for instance, using
64 \fBne_path_escape\fR)\&. If the string comes from an untrusted source, failure to perform URI\-escaping results in a security vulnerability\&.
65 .PP
66 To dispatch a request, and process the response, the
67 \fBne_request_dispatch\fR
68 function can be used\&. An alternative is to use the (more complex, but more flexible) combination of the
69 \fBne_begin_request\fR,
70 \fBne_end_request\fR, and
71 \fBne_read_response_block\fR
72 functions; see
73 \fBne_begin_request\fR\&.
74 .PP
75 To add extra headers in the request, the functions
76 ne_add_request_header
77 and
78 ne_print_request_header
79 can be used\&. To include a message body with the request, one of the functions
80 \fBne_set_request_body_buffer\fR,
81 ne_set_request_body_fd, or
82 \fBne_set_request_body_provider\fR
83 can be used\&.
84 .PP
85 The return value of
86 \fBne_request_dispatch\fR
87 indicates merely whether the request was sent and the response read successfully\&. To discover the result of the operation,
88 ne_get_status, along with any processing of the response headers and message body\&.
89 .PP
90 A request can only be dispatched once: calling
91 \fBne_request_dispatch\fR
92 more than once on a single
93 \fBne_request\fR
94 object produces undefined behaviour\&. Once all processing associated with the request object is complete, use the
95 \fBne_request_destroy\fR
96 function to destroy the resources associated with it\&. Any subsequent use of the request object produces undefined behaviour\&.
97 .PP
98 If a request is being using a non\-idempotent method such as
99 POST, the
100 NE_REQFLAG_IDEMPOTENT
101 flag should be disabled; see
102 ne_set_request_flag\&.
103 .SH "RETURN VALUE"
104 .PP
105 The
106 \fBne_request_create\fR
107 function returns a pointer to a request object (and never
108 NULL)\&.
109 .PP
110 The
111 \fBne_request_dispatch\fR
112 function returns zero if the request was dispatched successfully, and a non\-zero error code otherwise\&.
113 .SH "ERRORS"
114 .PP
115 \fBNE_ERROR\fR
116 .RS 4
117 Request failed (see session error string)
118 .RE
119 .PP
120 \fBNE_LOOKUP\fR
121 .RS 4
122 The DNS lookup for the server (or proxy server) failed\&.
123 .RE
124 .PP
125 \fBNE_AUTH\fR
126 .RS 4
127 Authentication failed on the server\&.
128 .RE
129 .PP
130 \fBNE_PROXYAUTH\fR
131 .RS 4
132 Authentication failed on the proxy server\&.
133 .RE
134 .PP
135 \fBNE_CONNECT\fR
136 .RS 4
137 A connection to the server could not be established\&.
138 .RE
139 .PP
140 \fBNE_TIMEOUT\fR
141 .RS 4
142 A timeout occurred while waiting for the server to respond\&.
143 .RE
144 .SH "EXAMPLE"
145 .PP
146 An example of applying a
147 MKCOL
148 operation to the resource at the location
149 http://www\&.example\&.com/foo/bar/:
150 .sp
151 .if n \{\
152 .RS 4
153 .\}
154 .nf
155 ne_session *sess = ne_session_create("http", "www\&.example\&.com", 80);
156 ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
157 if (ne_request_dispatch(req)) {
158 printf("Request failed: %s\en", ne_get_error(sess));
159 }
160 ne_request_destroy(req);
161 .fi
162 .if n \{\
163 .RE
164 .\}
165 .SH "SEE ALSO"
166 .PP
167 ne_get_error,
168 ne_set_error,
169 ne_get_status,
170 ne_add_request_header,
171 ne_set_request_body_buffer,
172 ne_set_request_flag\&.
173 .SH "AUTHOR"
174 .PP
175 \fBJoe Orton\fR <\&[email protected]\&>
176 .RS 4
177 Author.
178 .RE
179 .SH "COPYRIGHT"
180 .br