---
name: "ne_request_dispatch"
section: "3"
platform: "linux"
package: "libneon27-dev"
version: "0.34.2-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/ne_request_create"
---

# ne\_request\_dispatch(3)

low-level HTTP request handling

Part of [ne\_request\_create(3)](/ne_request_create/3.md).

## 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 response. 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 optionally 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 request 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\_request\_body\_fd**, or **ne\_set\_request\_body\_provider** can be used.

The return value of **ne\_request\_dispatch** indicates merely whether the request 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 directly in request data without validation, so 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.

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 © 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