From b163d078fcb3e40ad3f047f42326e9267bc4da50 Mon Sep 17 00:00:00 2001 From: gdamore Date: Mon, 13 Jan 2025 00:34:40 +0000 Subject: deploy: 1b1f4609c6dad724b88dfb069b2260341e582906 --- ref/api/http.html | 37 ++++++++++++++++--------------------- 1 file changed, 16 insertions(+), 21 deletions(-) (limited to 'ref/api/http.html') diff --git a/ref/api/http.html b/ref/api/http.html index bec909b9..19c182af 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -256,7 +256,7 @@ and so forth. This function silently truncates any method to 32-characters. (The

The nng_http_get_method function is used, typically on a server, to retrieve the method the client set when issuing the transaction.

HTTP URI

-
int nng_http_set_uri(nng_http *conn, const char *uri, const char *query);
+
nng_err nng_http_set_uri(nng_http *conn, const char *uri, const char *query);
 const char *nng_http_get_uri(nng_http *conn);
 

 
The nng_http_set_uri function sets the URI, which normally appears like a path such as “/docs/index.html”,
@@ -275,7 +275,7 @@ or NNG_EINVAL if there is
 If the URI is unset (such as for a freshly created connection), then it returns NULL. The returned value
 will have any query concentated, for example “/api/get_user.cgi?name=garrett”.

 
HTTP Version

-
int nng_http_set_version(nng_http *conn, const char *version);
+
nng_err nng_http_set_version(nng_http *conn, const char *version);
 const char *nng_http_get_version(nng_http *conn);
 

 
The nng_http_set_version function is used to select the HTTP protocol version to use for the
@@ -300,9 +300,10 @@ It might be easiest to just fail any request coming in that is not HTTP/1.1.

 
NNG does not support HTTP/2 or HTTP/3 at this time.

 
 
HTTP Status

-
uint16_t nng_http_get_status(nng_http *conn);
+
typedef enum ... nng_http_status;
+nng_http_status nng_http_get_status(nng_http *conn);
 const char *nng_http_get_reason(nng_http_conn *conn);
-void nng_http_set_status(nng_http *conn, uint16_t status, const char *reason);
+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.)

@@ -401,8 +402,8 @@ the header name and value. It also updates next, which should be used f
 
Once nng_http_next_header returns false, further calls with the same parameters will continue to do so.
 The scan can be rest by setting next to NULL.

 
Modifying Headers

-
int nng_http_add_header(nng_http *conn, const char *key, const char *val);
-int nng_http_set_header(nng_http *conn, const char *key, const char *val);
+
nng_err nng_http_add_header(nng_http *conn, const char *key, const char *val);
+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
@@ -495,7 +496,7 @@ operations until the the entire amount of data requested by the nng_http_hijack.
 They can be used to transfer request or response body data as well.

 
Hijacking Connections

-
void nng_http_hijack(nng_http_conn *conn);
+
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
@@ -550,8 +551,8 @@ of its resources.

 and must be closed explicitly as needed.

 
 
Client TLS

-
int nng_http_client_get_tls(nng_http_client *client, nng_tls_config **tlsp);
-int nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
+
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
 retrieve or change the TLS configuration used when making outbound connections, enabling
@@ -609,17 +610,11 @@ if ((rv = nng_aio_result(aio)) != 0) {
 }
 

 
Preparing a Transaction

-
int nng_http_set_version(nng_http *conn, const char *version);
-int nng_http_set_uri(nng_http *conn, const char *uri);
-

-
The nng_http_set_uri function provides a URI for the transaction. This will be used to
-set the URI for the request. The URI typically appears like a path, starting with “/”, although
-it may also contain a query string.

 
Request Body

 
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.
@@ -639,7 +634,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.

@@ -659,11 +654,11 @@ need to do so may use the direct read functions.

 
An easier one-shot method for many use cases might be [nng_http_transact].

 
 
Submitting the Transaction

-
int nng_http_transact(nng_http *conn, nng_aio *aio);
+
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
@@ -704,7 +699,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