From 2b8d71694ea8755881bdb8d8fe1fdcc9d4055eac Mon Sep 17 00:00:00 2001 From: gdamore Date: Wed, 15 Jan 2025 05:56:53 +0000 Subject: deploy: 575148ac9a274d61e45220fda7d8de6a420f4fe4 --- ref/api/http.html | 51 ++++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) (limited to 'ref/api/http.html') diff --git a/ref/api/http.html b/ref/api/http.html index 19c182af..03ab3ef6 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -306,9 +306,10 @@ const char *nng_http_get_reason(nng_http_conn *conn); void nng_http_set_status(nng_http *conn, nng_http_status status, const char *reason);

The nng_http_get_status function obtains the numeric code (typipcally numbered from 100 through 599) returned -by the server in the last exchange on conn. (If no exchange has been performed yet, the result is undefined.)

-

A descriptive message matching the status code is returned by nng_http_get_reason.

-

The nng_http_set_status function is used on a server in a handler callback to set the status code that will be +by the server in the last exchange on conn. (If no exchange has been performed yet, the result is undefined.) +The value is returned as an nng_http_status.

+

A descriptive message matching the status code is returned by nng_http_get_reason.

+

The nng_http_set_status function is used on a server in a handler callback to set the status code that will be reported to the client to status, and the associated text (reason) to reason. If reason is NULL, then a built in reason based on the status will be used instead.

@@ -388,14 +389,14 @@ for display to users.

const char *nng_http_get_header(nng_http *conn, const char *key);
 bool nng_next_header(nng_http *conn, const char **keyp, const char **valuep, void **next);
-

The nng_http_get_header returns the header value matching key that was received over conn, +

The nng_http_get_header returns the header value matching key that was received over conn, or NULL if no such header exists.

Thus, if conn is a client connection, then this function returns the the header value sent by the server as part of a response, whereas if it is a server connection, it returns the header value sent by the client as part of the request.

If multiple headers are present with the same key, they may be returned as a combined value, with individual values separated by commas, but this behavior is not guaranteed.

-

The nng_http_next_header function iterates over all the headers, using the same list +

The nng_http_next_header function iterates over all the headers, using the same list that nng_http_get_header uses. To start, it is called with next initialized to NULL. If a header was found, then it returns true, and sets keyp and valuep to values containing the header name and value. It also updates next, which should be used for the next iteration.

@@ -406,7 +407,7 @@ The scan can be rest by setting next to NULL.

nng_err nng_http_set_header(nng_http *conn, const char *key, const char *val); void nng_http_del_header(nng_http *conn, const char *key); -

The nng_http_add_header, nng_http_set_header, and nng_http_del_header functions are +

The nng_http_add_header, nng_http_set_header, and nng_http_del_header functions are used to add a modify either the request or response headers for conn prior to sending to the connected peer on conn.

Thus, if the conn is a client connection created by nng_http_client_connect, then the request headers are modified. Conversely, if it is a connection created by an HTTP server and used in a callback function, then the response headers are modified.

@@ -428,7 +429,7 @@ as by guaranting that only a single instance of one of these headers is present.

Retrieving Body Content

void nng_http_get_body(nng_http_conn *conn, void **datap, size_t *sizep);
-

The nng_http_get_data obtains the most recently received request or +

The nng_http_get_data obtains the most recently received request or response body. This will be NULL if the content has not been retrieved properly yet, or if the peer did not any content. (Some requests are defined to never have body content, such as “HEAD”.)

@@ -436,10 +437,10 @@ 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_data 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_data function makes a copy of data, which will be freed automatically when the transaction is finished, but otherwise behaves like nng_http_set_data.

On client conn objects, these functions update the request object, but on server @@ -463,13 +464,13 @@ transfer-encoding.

Closing the Connection

void nng_http_close(nng_http *conn);
-

The nng_http_close function closes the supplied HTTP connection conn, +

The nng_http_close function closes the supplied HTTP connection conn, including any disposing of any underlying file descriptors or related resources.

Once this function, no further access to the conn structure may be made.

Reset Connection State

void nng_http_reset(nng_http *conn);
-

The nng_http_reset function resets the request and response state of the +

The nng_http_reset function resets the request and response state of the the connection conn, so that it is just as if it had been freshly created with nng_http_client_connect or passed into a handler function for a server callback.

The intended purpose of this function is to clear the object state before reusing the conn for @@ -480,11 +481,11 @@ void nng_http_write(nng_http *conn, nng_aio *aio); void nng_http_read_all(nng_http *conn, nng_aio *aio); void nng_http_write_all(nng_http *conn, nng_aio *aio); -

The nng_http_read and nng_http_write functions read or write data asynchronously from or to the +

The nng_http_read and nng_http_write functions read or write data asynchronously from or to the connection conn, using the nng_iov that is set in aio with nng_aio_set_iov. These functions will complete as soon as any data is transferred. Use nng_aio_count to determine how much data was actually transferred.

-

The nng_http_read_all and nng_http_write_all functions perform the same task, but will keep resubmitting +

The nng_http_read_all and nng_http_write_all functions perform the same task, but will keep resubmitting operations until the the entire amount of data requested by the nng_iov is transferred.

@@ -499,7 +500,7 @@ They can be used to transfer request or response body data as well.

nng_err nng_http_hijack(nng_http *conn);

TODO: This API will change to convert the conn into a stream object.

-

The nng_http_hijack function hijacks the connection conn, causing it +

The nng_http_hijack function hijacks the connection conn, causing it to be disassociated from the HTTP server where it was created.

The purpose of this function is the creation of HTTP upgraders (such as WebSocket), where the underlying HTTP connection will be taken over for @@ -529,18 +530,18 @@ transactions on those connections.

Client Object

typedef struct nng_http_client nng_http_client;
-

The nng_http_client object is the client side creator for nng_http objects. +

The nng_http_client object is the client side creator for nng_http objects. It is analogous to a dialer object used elsewhere in NNG, but it specifically is only for HTTP.

Create a Client

void nng_http_client_alloc(nng_http_client *clientp, const nng_url *url);
-

The nng_http_client_alloc allocates an HTTP client suitable for +

The nng_http_client_alloc allocates an HTTP client suitable for connecting to the server identified by url and stores a pointer to it in the location referenced by clientp.

Destroy a Client

void nng_http_client_free(nng_http_client *client);
-

The nng_http_client_free connection destroys the client object and any +

The nng_http_client_free connection destroys the client object and any of its resources.

@@ -554,9 +555,9 @@ and must be closed explicitly as needed.

nng_err nng_http_client_get_tls(nng_http_client *client, nng_tls_config **tlsp);
 nng_err nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
-

The nng_http_client_get_tls and nng_http_client_set_tls functions are used to +

The nng_http_client_get_tls and nng_http_client_set_tls functions are used to retrieve or change the TLS configuration used when making outbound connections, enabling -TLS as a result.

+TLS as a result.

If TLS has not been previously configured on client, then nng_http_client_get_tls will return NNG_EINVAL. Both functions will return NNG_ENOTSUP if either HTTP or TLS is not supported.

Calling nng_http_client_set_tls invalidates any client previously obtained with @@ -576,7 +577,7 @@ Existing connections will use the TLS configuration that there were created with void nng_http_client_connect(nng_http_client *client, nng_aio *aio); -

The nng_http_client_connect function makes an outgoing connection to the +

The nng_http_client_connect function makes an outgoing connection to the server configured for client, and creates an nng_http object for the connection.

This is done asynchronously, and when the operation succeseds the connection may be retried from the aio using nng_aio_get_output with index 0.

@@ -614,7 +615,7 @@ if ((rv = nng_aio_result(aio)) != 0) {

Sending the Request

void nng_http_write_request(nng_http *conn, nng_aio *aio);
-

The nng_http_write_request function starts an asynchronous write of +

The nng_http_write_request function starts an asynchronous write of the HTTP request associated with conn. The entire request is sent, including headers, and if present, the request body data. @@ -634,7 +635,7 @@ which provides a simpler interface for performing a complete HTTP client transac

Obtaining the Response

void nng_http_read_response(nng_http *conn, nng_aio *aio);
-

The nng_http_read_response function starts an asynchronous read from the +

The nng_http_read_response function starts an asynchronous read from the HTTP connection conn, reading an HTTP response into the response associated with conn, including all of the related headers.

It does not transfer any response body. To do that, use nng_http_read_all or nng_http_read.

@@ -656,9 +657,9 @@ need to do so may use the direct read functions.

Submitting the Transaction

void nng_http_transact(nng_http *conn, nng_aio *aio);
-

The HTTP request is issued, and the response processed, asynchronously by the nng_http_transact function. +

The HTTP request is issued, and the response processed, asynchronously by the nng_http_transact function. When the function is complete, the aio will be notified.

-

The nng_http_transact function is used to perform a complete +

The nng_http_transact function is used to perform a complete HTTP exchange over the connection conn, sending the request and attached body data to the remote server, and reading the response.

The entire response is read, including any associated body, which can @@ -699,7 +700,7 @@ may be obtained via [nng_aio_result()].

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