From 35df6a2f9a33084b71b24ab31197da81e6486078 Mon Sep 17 00:00:00 2001 From: gdamore Date: Wed, 8 Oct 2025 22:20:36 +0000 Subject: deploy: f01e5dc6223a104fcec853cf5a0f443368f9c814 --- ref/api/http.html | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) (limited to 'ref/api/http.html') diff --git a/ref/api/http.html b/ref/api/http.html index 67c7048e..1d137541 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -266,7 +266,7 @@ performed after the first transaction is complete.

At any given point in time, an nng_http object can only refer to a single HTTP transaction. In NNG, these nng_http objects are used in both the client and server APIs.

The nng_http object is created by either nng_http_client_connect or by an HTTP server -object which then passes it to an [nng_http_handler] callback function.

+object which then passes it to an nng_http_handler callback function.

HTTP Method

void nng_http_set_method(nng_http *conn, const char *method);
 const char *nng_http_get_method(nng_http *conn);
@@ -460,12 +460,12 @@ to never have body content, such as “HEAD”.)

 
void nng_http_set_body(nng_http_conn *conn, void *data, size_t size);
 void nng_http_copy_body(nng_http_conn *conn, const void *data, size_t size);
 

-
The nng_http_set_data function sets the outgoing body content to data,
+
The nng_http_set_body function sets the outgoing body content to data,
 which must be size bytes long. The caller must ensure that data remains
 valid for the duration of the transaction.

-
The nng_http_copy_data function makes a copy of data, which
+
The nng_http_copy_body function makes a copy of data, which
 will be freed automatically when the transaction is finished, but otherwise
-behaves like nng_http_set_data.

+behaves like nng_http_set_body.

 
On client conn objects, these functions update the request object, but on server
 conn objects, they update the response object.

 
These functions also update the relevant “Content-Length” header.

@@ -529,7 +529,7 @@ to be disassociated from the HTTP server where it was created.

 WebSocket), where the underlying HTTP connection will be taken over for
 some other purpose, and should not be used any further by the server.

 
This function is most useful when called from a handler function.
-(See [nng_http_handler_alloc].)

+(See nng_http_handler_alloc.)

 

 

   
@@ -537,7 +537,7 @@ some other purpose, and should not be used any further by the server.

 

 
It is the responsibility of the caller to dispose of the underlying connection when it is no longer needed.
 Furthermore, the HTTP server will no longer send any responses to the hijacked connection, so the caller should do that as well if appropriate.
-(See [nng_http_write_response].)

+(See nng_http_write_response.)

 

 

 

@@ -660,7 +660,7 @@ the HTTP request associated with conn.
 The entire request is sent,
 including headers, and if present, the request body data.
 (The request body can be set with
-[nng_http_set_data] or [nng_http_copy_data].)

+nng_http_set_body or nng_http_copy_body.)

 
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.

@@ -754,8 +754,8 @@ URIs from being supported, but doing so will require setting the handler to matc
 
The NNG HTTP framework is optimized for URLs shorter than 200 characters.

 

 
Additionally each handler has a method it is registered to handle
-(the default is “GET” andc can be changed with [nng_http_handler_set_method]), and
-optionally a “Host” header it can be matched against (see [nng_http_handler_set_host]).

+(the default is “GET” andc can be changed with nng_http_handler_set_method), and
+optionally a “Host” header it can be matched against (see nng_http_handler_set_host).

 
In some cases, a handler may reference a logical tree rather (directory)
 rather than just a single element.
 (See [nng_http_handler_set_tree]).

@@ -770,9 +770,9 @@ On success, a pointer to the handler is stored at the located pointed to by 
 
The handler function is specified by cb.
 This function uses the asynchronous I/O framework.

 
The function receives the connection on conn, and an optional data pointer that was set
-previously with [nng_http_handler_set_data] as the second argument. The
+previously with nng_http_handler_set_data as the second argument. The
 final argument is the nng_aio aio, which must be “finished” to complete the operation.

-
The handler may call [nng_http_write_response] to send the response, or
+
The handler may call nng_http_write_response to send the response, or
 it may simply let the framework do so on its behalf. The server will perform
 this step if the callback has not already done so.

 
Response headers may be set using nng_http_set_header, and request headers
@@ -786,11 +786,11 @@ the response body may be set using either nng_http_handler_collect_body function has been called for the handler.

 
 
The HTTP status should be set for the transaction using nng_http_set_status.

 
Finally, the handler should finish the operation by calling the nng_aio_finish function
-after having set the status to [NNG_OK].
+after having set the status to NNG_OK.
 If any other status is set on the aio, then a generic 500 response will be created and
 sent, if possible, and the connection will be closed.

 
The aio may be scheduled for deferred completion using the nng_aio_start.

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

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][nng_http_status] status, +

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 referenced by location, with any residual suffix from the request URI appended.

@@ -840,9 +840,9 @@ of the new site, such as https://newsite.example.com as the new loc

Be sure to use the appropriate value for status. Permanent redirection should use [NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY] (301) -and temporary redirections should use [NNG_HTTP_STATUS_TEMPORARY_REDIRECT] (307). +and temporary redirections should use NNG_HTTP_STATUS_TEMPORARY_REDIRECT (307). In REST APIs, using a redirection to supply the new location of an object -created with POST should use [NNG_HTTP_STATUS_SEE_OTHER] (303).

+created with POST should use NNG_HTTP_STATUS_SEE_OTHER (303).

Collecting Request Body

void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz);
@@ -856,7 +856,7 @@ connection before calling the callback for the handler.

 Furthermore, the data that the client may sent is limited by the
 value of maxsz.
 If the client attempts to send more data than maxsz, then the
-request will be terminated with [NNG_HTTP_STATUS_CONTENT_TOO_LARGE] (413).

+request will be terminated with NNG_HTTP_STATUS_CONTENT_TOO_LARGE (413).

 

 

   
@@ -963,6 +963,7 @@ explicitly by setting the “Connection: close” header, the connection will be
 response is fully sent.

 
 
+
 
 
 
-- 
cgit v1.2.3-70-g09d2