1NE_REQUEST_CREATE(3) neon API reference NE_REQUEST_CREATE(3)
2
6 ne_request_create, ne_request_dispatch, ne_request_destroy - low-level
7 HTTP request handling
8
10 #include <ne_request.h>
11 ne_request *ne_request_create(ne_session *session, const char *method,
13 const char *path);
14 int ne_request_dispatch(ne_request *req);
16 void ne_request_destroy(ne_request *req);
18
20 An HTTP request, represented by the ne_request type, specifies that
21 some operation is to be performed on some resource. The
22 ne_request_create function creates a request object, specifying the
23 operation in the method parameter. The location of the resource is
24 determined by the server in use for the session given by the sess
25 parameter, combined with the path parameter.
26 The path string used must conform to the abs_path definition given in
28 RFC2396, with an optional "?query" part, and must be URI-escaped by the
29 caller (for instance, using ne_path_escape). If the string comes from
30 an untrusted source, failure to perform URI-escaping results in a
31 security vulnerability.
32 To dispatch a request, and process the response, the
34 ne_request_dispatch function can be used. An alternative is to use the
35 (more complex, but more flexible) combination of the ne_begin_request,
36 ne_end_request, and ne_read_response_block functions; see
37 ne_begin_request.
38 To add extra headers in the request, the functions
40 ne_add_request_header and ne_print_request_header can be used. To
41 include a message body with the request, one of the functions
42 ne_set_request_body_buffer, ne_set_request_body_fd, or
43 ne_set_request_body_provider can be used.
44 The return value of ne_request_dispatch indicates merely whether the
46 request was sent and the response read successfully. To discover the
47 result of the operation, ne_get_status, along with any processing of
48 the response headers and message body.
49 A request can only be dispatched once: calling ne_request_dispatch more
51 than once on a single ne_request object produces undefined behaviour.
52 Once all processing associated with the request object is complete, use
53 the ne_request_destroy function to destroy the resources associated
54 with it. Any subsequent use of the request object produces undefined
55 behaviour.
56 If a request is being using a non-idempotent method such as POST, the
58 NE_REQFLAG_IDEMPOTENT flag should be disabled; see ne_set_request_flag.
59
61 The ne_request_create function returns a pointer to a request object
62 (and never NULL).
63 The ne_request_dispatch function returns zero if the request was
65 dispatched successfully, and a non-zero error code otherwise.
66
68 NE_ERROR
69 Request failed (see session error string)
70 NE_LOOKUP
72 The DNS lookup for the server (or proxy server) failed.
73 NE_AUTH
75 Authentication failed on the server.
76 NE_PROXYAUTH
78 Authentication failed on the proxy server.
79 NE_CONNECT
81 A connection to the server could not be established.
82 NE_TIMEOUT
84 A timeout occurred while waiting for the server to respond.
85
87 An example of applying a MKCOL operation to the resource at the
88 location http://www.example.com/foo/bar/:
89 ne_session *sess = ne_session_create("http", "www.example.com", 80);
91 ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
92 if (ne_request_dispatch(req)) {
93 printf("Request failed: %s\n", ne_get_error(sess));
94 }
95 ne_request_destroy(req);
96
98 ne_get_error, ne_set_error, ne_get_status, ne_add_request_header,
99 ne_set_request_body_buffer, ne_set_request_flag.
100
102 Joe Orton <neon@lists.manyfish.co.uk>
103 Author.
104
106neon 0.29.3 11 January 2010 NE_REQUEST_CREATE(3)