NE_REQUEST_CREATE(3)

📦
version 0.37.1 · 12 versions
, in arch rolling

💅 NE_REQUEST_CREATE(3) — like, the neon API reference bestie ✨

okay so this is a page from the neon API reference and it's all about low-level HTTP request handling — the manual name is literally "neon API reference", that's the vibe. let's get into it 🫶

🌸 NAME 🌸

ne_request_create, ne_request_dispatch, ne_request_destroy — low-level HTTP request handling. that's the whole thing. iconic trio tbh.

✨ 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 💖

so the ne_request object is literally the main character — it represents an HTTP request and the response that comes with it. two-for-one. we love to see it.

ne_request_create makes you a brand new request object for the given session. the resource you're targeting is identified by the target parameter, and what you're doing to that resource is identified by the method parameter. simple as that.

the target string you pass in must conform to the request-target definition given in RFC 9112. usually that means it takes the abolute-path form (yes, that's how it's spelled in the original, keep it moving 💀), which optionally includes a query string.

ne_request_dispatch is how you actually send the request and process the response. it's the low-effort path and we respect it. an alternative is the more complex but more flexible combo of ne_begin_request, ne_end_request, and ne_read_response_block — go check out ne_begin_request if that's your thing.

heads up bestie: dispatching a request may need multiple iterations of a request being sent and a response being received — for example if authentication is used (see ne_set_server_auth(3)), or if a persistent connection times out. don't stress though, ne_request_dispatch handles all of that internally. it's giving competent. 👑

want extra headers in your request? use ne_add_request_header(3) and ne_print_request_header(3). want to include a message body with the request? pick one of ne_set_request_body_buffer, ne_set_request_body_fd, or ne_set_request_body_provider. one (1) of them. choose wisely 🎀

now this next part is important so pay attention: the return value of ne_request_dispatch merely tells you whether the request was sent and the response was read successfully. that's it. it does not tell you how the operation went. to find that out, use ne_get_status(3), along with whatever processing you do of the response headers and message body. don't mix these up, i'm begging 🙈

🚨 massive caveat, no cap: a request can only be dispatched once. calling ne_request_dispatch more than once on a single ne_request object produces undefined behaviour. and once all the processing associated with the request object is done, call ne_request_destroy to destroy the resources associated with it — any use of the request object after that also produces undefined behaviour. treat it like it's gone-gone. 💀

okay and one more thing that trips literally everyone up: request methods are assumed to be idempotent by default. so if you're using a non-idempotent method like POST, you must disable the NE_REQFLAG_IDEMPOTENT flag using ne_set_request_flag(3). don't skip this. it's not a suggestion, it's the rules. ✨

🦋 RETURN VALUE 🦋

  • ne_request_create — returns a pointer to a request object, and it never returns NULL. ever. slay.
  • ne_request_dispatch — returns zero if the request was dispatched successfully, and a non-zero error code otherwise, as described in the next section. (also, "non-zero error code code" is what the original says — we're keeping the lore 🫶)

🌈 ERROR CODES 🌈

error codes have a non-zero value and correspond to an NE_* macro definition, listed below. future versions of neon may introduce additional error code definitions, so like, don't hardcode your whole life around this list. functions which return an error code and have an associated session object set the session error string (see ne_get_error(3)) unless documented otherwise.

  • 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
  • NE_REDIRECT — a valid redirect was returned. ⚠️ note: only returned if redirect handling is registered for the session using ne_redirect_register(3)

🎀 NOTES 🎀

⚠️ security moment, bestie, read this twice. the path, method and target parameters of ne_request_create are used directly in request data without validation, so they must not be taken from untrusted sources. for example, allowing insertion of unescaped CR, LF or other control characters in these parameters may result in unexpected or insecure behaviour. do not let strangers write your request data. periodt. 💅

also, neon does not impose any length restrictions on request input data. none. go wild (responsibly).

🔥 EXAMPLE 🔥

here's 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);

look at that clean little lifecycle. create → dispatch → destroy. we love a full arc. 💜

🧚 SEE ALSO 🧚

ne_session_create(3), ne_get_error(3), ne_set_error(3), ne_get_status(3), ne_add_request_header(3), ne_set_request_body_buffer(3), ne_set_request_flag(3), ne_redirect_register(3).

Copyright © 2001-2026 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

okay that's the whole page!! this one's from neon, dated 03/20/2026, and the page is NE_REQUEST_CREATE(3) — go forth and dispatch your requests exactly one (1) time each, bestie 🍓💖✨

📦 where this page comes from