NE_REQUEST_CREATE(3) neon API reference NE_REQUEST_CREATE(3) NAME ne_request_create, ne_request_dispatch, ne_request_destroy - low-level HTTP request handling SYNOPSIS #include <ne_request.h> ne_request *ne_request_create(ne_session *session, const char *method, const char *target); int ne_request_dispatch(ne_request *req); void ne_request_destroy(ne_request *req); DESCRIPTION The ne_request object represents an HTTP request and the associated re- sponse. The ne_request_create function creates a new request object for the given session. The target resource for the request is identified by the target, parameter, and the method to be performed on that resource via the method parameter. The target string used must conform to the request-target definition given in RFC 9112[1]. Usually this will take the abolute-path form, which option- ally includes a query string. To dispatch a request, and process the response, the ne_request_dispatch function can be used. An alternative is to use the (more complex, but more flexible) combination of the ne_begin_request, ne_end_request, and ne_read_response_block functions; see ne_begin_request. Dispatching a re- quest 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 ne_request_dispatch. 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 ne_set_request_body_buffer, ne_set_re- quest_body_fd, or ne_set_request_body_provider can be used. The return value of ne_request_dispatch indicates merely whether the re- quest 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. A request can only be dispatched once: calling ne_request_dispatch more than once on a single ne_request object produces undefined behaviour. Once all processing associated with the request object is complete, use the ne_request_destroy function to destroy the resources associated with it. Any subsequent use of the request object produces undefined behaviour. Request methods are assumed to be idempotent[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. RETURN VALUE The ne_request_create function returns a pointer to a request object (and never NULL). The ne_request_dispatch function returns zero if the request was dispatched successfully, and a non-zero error code otherwise. NOTES The path, method and target parameters of ne_request_create are used di- rectly in request data without validation, so must not be taken from un- trusted sources. For example, allowing insertion of unescaped CR, LF or other control characters in these parameters may result in unexpected or insecure behaviour. neon does not impose any length restrictions on request input data. ERRORS NE_ERROR Request failed (see session error string) NE_LOOKUP The DNS lookup for the server (or proxy server) failed. NE_AUTH Authentication failed on the server. NE_PROXYAUTH Authentication failed on the proxy server. NE_CONNECT A connection to the server could not be established. NE_TIMEOUT A timeout occurred while waiting for the server to respond. EXAMPLE An example of applying a MKCOL operation to the resource at the location http://www.example.com/foo/bar/: 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\n", ne_get_error(sess)); } ne_request_destroy(req); SEE ALSO ne_get_error, ne_set_error, ne_get_status, ne_add_request_header, ne_set_request_body_buffer, ne_set_request_flag. COPYRIGHT Copyright (C) 2001-2024 Joe Orton REFERENCES 1. RFC 9112 https://www.rfc-editor.org/rfc/rfc9112 2. idempotent https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods neon 0.34.0 23 November 2024 NE_REQUEST_CREATE(3)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | ERRORS | EXAMPLE | SEE ALSO | COPYRIGHT | REFERENCES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ne_request_destroy&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>