1NE_REQUEST_CREATE(3)          neon API reference          NE_REQUEST_CREATE(3)
2
3
4

NAME

6       ne_request_create, ne_request_dispatch, ne_request_destroy - low-level
7       HTTP request handling
8

SYNOPSIS

10       #include <ne_request.h>
11
12       ne_request *ne_request_create(ne_session *session, const char *method,
13                                     const char *path);
14
15       int ne_request_dispatch(ne_request *req);
16
17       void ne_request_destroy(ne_request *req);
18

DESCRIPTION

20       The ne_request object represents an HTTP request and the associated
21       response. The ne_request_create function creates a new request object
22       for the given session. The target resource for the request is
23       identified by the path, and the method to be performed on that resource
24       via the method parameter.
25
26       The path string used must conform to the abs_path definition given in
27       RFC2396, with an optional "?query" part, and must be URI-escaped by the
28       caller (for instance, using ne_path_escape). If the string comes from
29       an untrusted source, failure to perform URI-escaping results in a
30       security vulnerability.
31
32       To dispatch a request, and process the response, the
33       ne_request_dispatch function can be used. An alternative is to use the
34       (more complex, but more flexible) combination of the ne_begin_request,
35       ne_end_request, and ne_read_response_block functions; see
36       ne_begin_request.
37
38       To add extra headers in the request, the functions
39       ne_add_request_header and ne_print_request_header can be used. To
40       include a message body with the request, one of the functions
41       ne_set_request_body_buffer, ne_set_request_body_fd, or
42       ne_set_request_body_provider can be used.
43
44       The return value of ne_request_dispatch indicates merely whether the
45       request was sent and the response read successfully. To discover the
46       result of the operation, ne_get_status, along with any processing of
47       the response headers and message body.
48
49       A request can only be dispatched once: calling ne_request_dispatch more
50       than once on a single ne_request object produces undefined behaviour.
51       Once all processing associated with the request object is complete, use
52       the ne_request_destroy function to destroy the resources associated
53       with it. Any subsequent use of the request object produces undefined
54       behaviour.
55
56       If a request is being using a non-idempotent method such as POST, the
57       NE_REQFLAG_IDEMPOTENT flag should be disabled; see ne_set_request_flag.
58

RETURN VALUE

60       The ne_request_create function returns a pointer to a request object
61       (and never NULL).
62
63       The ne_request_dispatch function returns zero if the request was
64       dispatched successfully, and a non-zero error code otherwise.
65

ERRORS

67       NE_ERROR
68           Request failed (see session error string)
69
70       NE_LOOKUP
71           The DNS lookup for the server (or proxy server) failed.
72
73       NE_AUTH
74           Authentication failed on the server.
75
76       NE_PROXYAUTH
77           Authentication failed on the proxy server.
78
79       NE_CONNECT
80           A connection to the server could not be established.
81
82       NE_TIMEOUT
83           A timeout occurred while waiting for the server to respond.
84

EXAMPLE

86       An example of applying a MKCOL operation to the resource at the
87       location http://www.example.com/foo/bar/:
88
89           ne_session *sess = ne_session_create("http", "www.example.com", 80);
90           ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
91           if (ne_request_dispatch(req)) {
92              printf("Request failed: %s\n", ne_get_error(sess));
93           }
94           ne_request_destroy(req);
95

SEE ALSO

97       ne_get_error, ne_set_error, ne_get_status, ne_add_request_header,
98       ne_set_request_body_buffer, ne_set_request_flag.
99

AUTHOR

101       Joe Orton <neon@lists.manyfish.co.uk>
102           Author.
103
105neon 0.30.0                      31 July 2013             NE_REQUEST_CREATE(3)
Impressum