ne_request_dispatch(3)

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
13       ne_request *ne_request_create (ne_session *session, const char *method,
14                                      const char *path);
15
16       int ne_request_dispatch (ne_request *req);
17
18       void ne_request_destroy (ne_request *req);
19
20

DESCRIPTION

22       An  HTTP  request,  represented  by the ne_request type, specifies that
23       some operation is to be performed on some resource. The ne_request_cre‐
24       ate  function creates a request object, specifying the operation in the
25       method parameter. The location of the resource  is  determined  by  the
26       server  in  use  for  the session given by the sess parameter, combined
27       with the path parameter.
28
29
30       The path string used must conform to the abs_path definition  given  in
31       RFC2396, with an optional "?query" part, and must be URI-escaped by the
32       caller (for instance, using ne_path_escape). If the string  comes  from
33       an untrusted source, failure to perform URI-escaping results in a secu‐
34       rity vulnerability.
35
36
37       To dispatch a request, and process the  response,  the  ne_request_dis‐
38       patch function can be used. An alternative is to use the (more complex,
39       but more flexible) combination of the ne_begin_request, ne_end_request,
40       and ne_read_response_block functions; see ne_begin_request.
41
42
43       To add extra headers in the request, the functions ne_add_request_head‐
44       er(3) and ne_print_request_header(3) can be used. To include a  message
45       body with the request, one of the functions ne_set_request_body_buffer,
46       ne_set_request_body_fd(3), or ne_set_request_body_provider can be used.
47
48
49       The return value of ne_request_dispatch indicates  merely  whether  the
50       request  was  sent  and the response read successfully. To discover the
51       result of the operation, ne_get_status(3), along with any processing of
52       the response headers and message body.
53
54
55       A request can only be dispatched once: calling ne_request_dispatch more
56       than once on a single ne_request object produces  undefined  behaviour.
57       Once all processing associated with the request object is complete, use
58       the ne_request_destroy function to  destroy  the  resources  associated
59       with  it.  Any  subsequent use of the request object produces undefined
60       behaviour.
61
62

RETURN VALUE

64       The ne_request_create function returns a pointer to  a  request  object
65       (and never NULL).
66
67
68       The  ne_request_dispatch  function returns zero if the request was dis‐
69       patched successfully, and a non-zero error code otherwise.
70
71

ERRORS

73       NE_ERROR
74              Request failed (see session error string)
75
76
77       NE_LOOKUP
78              The DNS lookup for the server (or proxy server) failed.
79
80
81       NE_AUTH
82              Authentication failed on the server.
83
84
85       NE_PROXYAUTH
86              Authentication failed on the proxy server.
87
88
89       NE_CONNECT
90              A connection to the server could not be established.
91
92
93       NE_TIMEOUT
94              A timeout occurred while waiting for the server to respond.
95
96

EXAMPLE

98       An example of applying a MKCOL operation to the resource at  the  loca‐
99       tionhttp://www.example.com/foo/bar/:
100
101       ne_session *sess = ne_session_create("http", "www.example.com", 80);
102       ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
103       if (ne_request_dispatch(req)) {
104          printf("Request failed: %s\n", ne_get_error(sess));
105       }
106       ne_request_destroy(req);
107
108

AUTHOR

115       Joe Orton <neon@webdav.org>.
116
117
118
119neon 0.25.5                     20 January 2006           NE_REQUEST_CREATE(3)