From b4c6169cfab829cf6632115c930145802321cbec Mon Sep 17 00:00:00 2001 From: gdamore Date: Fri, 10 Oct 2025 13:31:20 +0000 Subject: deploy: f41cd6a9edf4b9a680194b3fb4378f39d1ed1f34 --- ref/api/http.html | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) (limited to 'ref/api/http.html') diff --git a/ref/api/http.html b/ref/api/http.html index 325f793b..45f469f4 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -732,12 +732,19 @@ request interleaving.

This function returns immediately, with no return value. Completion of the operation is signaled via the aio, and the final result may be obtained via nng_aio_result.

+

Socket Addresses

+
nng_err nng_http_local_address(nng_http *conn, nng_sockaddr *addr);
+nng_err nng_http_remote_address(nng_http *conn, nng_sockaddr *addr);
+
+

The nng_http_local_address and nng_http_remote_address functions +can be used to determine the local and remote addresses for an HTTP connection. +This can only be done while the connection is alive.

Response Body

Server API

Handlers

typedef struct nng_http_handler nng_http_handler;
-

An nng_http_handler encapsulates a function used used to handle +

An nng_http_handler encapsulates a function used used to handle incoming requests on an HTTP server, routed based on method and URI, and the parameters used with that function.

Every handler has a Request-URI to which it refers, which is determined by the path argument. @@ -764,7 +771,7 @@ rather than just a single element. nng_err nng_http_handler_alloc(nng_http_handler **hp, const char *path, nng_http_handler_func cb); -

The nng_http_handler_alloc function allocates a generic handler +

The nng_http_handler_alloc function allocates a generic handler which will be used to process requests coming into an HTTP server. On success, a pointer to the handler is stored at the located pointed to by hp.

The handler function is specified by cb. @@ -798,7 +805,7 @@ sent, if possible, and the connection will be closed.

nng_err nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, const char *dirname);
 nng_err nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, const char *filename);
-

The nng_http_handler_alloc_directory and nng_http_handler_alloc_file +

The nng_http_handler_alloc_directory and nng_http_handler_alloc_file create handlers pre-configured to act as static content servers for either a full directory at dirname, or the single file at filename. These support the “GET” and “HEAD” methods, and the directory variant will dynamically generate index.html content based on @@ -809,7 +816,7 @@ determined, the content type is set to “application/octet-stream”.

nng_err nng_http_handler_alloc_static(nng_http_handler **hp, const char *path,
         const void *data, size_t size, const char *content_type);
-

The nng_http_handler_alloc_static function creates a handler that +

The nng_http_handler_alloc_static function creates a handler that serves the content located in data (consisting of size bytes) at the URI path. The content_type determines the “Content-Type” header. If NULL is specified then a value of application/octet-stream is assumed.

@@ -817,7 +824,7 @@ then a value of application/octet-stream is assumed.

nng_err nng_http_handler_alloc_redirect(nng_http_handler **hp, const char *path,
         nng_http_status status, const char *location);
-

The nng_http_handler_alloc_redirect function creates a handler with +

The nng_http_handler_alloc_redirect function creates a handler with a function that simply directions from the URI at path to the given location.

The HTTP reply it creates will be with status code status, which should be a 3XX code such as 301, and a Location: header will contain the URL @@ -847,7 +854,7 @@ created with POST should use Collecting Request Body 

void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz);
-

The nng_http_handler_collect_body function requests that HTTP server +

The nng_http_handler_collect_body function requests that HTTP server framework collect any request body for the request and attach it to the connection before calling the callback for the handler.

Subsequently the data can be retrieved by the handler from the request with the @@ -891,7 +898,7 @@ create few limitations.

void nng_http_handler_set_data(nng_http_handler *handler, void *data,
     void (*dtor)(void *));
-

The nng_http_handler_set_data function is used to set the +

The nng_http_handler_set_data function is used to set the data argument that will be passed to the callback.

Additionally, when the handler is deallocated, if dtor is not NULL, then it will be called with data as its argument. @@ -899,7 +906,7 @@ The intended use of this function is deallocate any resources associated with Setting the Method 

void nng_http_handler_set_method(nng_http_handler *handler, const char *method);
-

The nng_http_handler_set_method function sets the method that the +

The nng_http_handler_set_method function sets the method that the handler will be called for, such as “GET” or “POST”. (By default the “GET” method is handled.)

If method is NULL the handler will be executed for all methods. @@ -917,7 +924,7 @@ sent for such requests.

Filtering by Host

void nng_http_handler_set_host(nng_http_handler *handler, const char *host);
-

The nng_http_handler_set_host function is used to limit the scope of the +

The nng_http_handler_set_host function is used to limit the scope of the handler so that it will only be called when the specified host matches the value of the Host: HTTP header.

This can be used to create servers with different content for different virtual hosts.

@@ -932,10 +939,15 @@ exactly the value of the Host header sent by the client.

The port number may be ignored; at present the HTTP server framework does not support a single server listening on different ports concurrently.

+

Detecting Addresses

+

The nng_http_local_address and nng_http_remote_address functions +can be used to determine the local and remote addresses for an HTTP connection +on the server side (in a handler) just like the can be for HTTP clients +This can be useful to provide different handling behaviors based on network identity.

Handling an Entire Tree

void nng_http_handler_set_tree(nng_http_handler *handler);
-

The nng_http_handler_set_tree function causes the handler to be matched if the request URI sent +

The nng_http_handler_set_tree function causes the handler to be matched if the request URI sent by the client is a logical child of the path for handler, and no more specific handler has been registered.

This is useful in cases when the handler would like to examine the entire path @@ -955,7 +967,7 @@ It can also provide a logical fallback instead of relying on a 404 error code.

Normally the server will send any attached response, but there are circumstances where a response must be sent manually, such as when hijacking a connection.

-

In such a case, nng_http_write_response can be called, which will send the response and any attached data, asynchronously +

In such a case, nng_http_write_response can be called, which will send the response and any attached data, asynchronously using the nng_aio aio.

By default, for HTTP/1.1 connections, the connection is kept open, and will be reused to receive new requests. For HTTP/1.0, or if the client has requested -- cgit v1.2.3-70-g09d2