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/aio.html | 4 ++-- ref/api/errors.html | 14 ++++++++++++-- ref/api/http.html | 37 ++++++++++++++++--------------------- 3 files changed, 30 insertions(+), 25 deletions(-) (limited to 'ref/api') diff --git a/ref/api/aio.html b/ref/api/aio.html index 371ed269..1ce6258e 100644 --- a/ref/api/aio.html +++ b/ref/api/aio.html @@ -295,7 +295,7 @@ is safe to call from aio’s own callback.

Use nng_aio_reap instead if an object must be destroyed from a callback.

Cancellation

-
void nng_aio_abort(nng_aio *aio, int err);
+
void nng_aio_abort(nng_aio *aio, nng_err err);
 void nng_aio_cancel(nng_aio *aio);
 void nng_aio_stop(nng_aio *aio);
 

@@ -373,7 +373,7 @@ This is the same test used internally by Result of Operation
-
int nng_aio_result(nng_aio *aio);
+
nng_err nng_aio_result(nng_aio *aio);
 size_t nng_aio_count(nng_aio *aio);
 

 
The nng_aio_result function returns the result of the operation associated
diff --git a/ref/api/errors.html b/ref/api/errors.html
index f3834e8f..766ab1f7 100644
--- a/ref/api/errors.html
+++ b/ref/api/errors.html
@@ -221,15 +221,25 @@
 
 
 
Errors

+
typedef enum ... nng_err;
+

 
Many NNG functions can fail for a variety of reasons.
 These functions tend to return either zero on success,
 or a non-zero error code to indicate failure.
 1

-
All these error codes are int.

+
All these error codes are nng_err.

+

+

+  
+  note
+

+
Many APIs are still using int, but the nng_err enumeration can be used
+instead, and will help with debugging.

+

 
Not every possible error code is defined here, as sometimes
 an underlying system or library error code is “wrapped”.

 
Human Readable Error Message

-
const char *nng_strerror(int err);
+
const char *nng_strerror(nng_err err);
 

 
The nng_strerror returns the human-readable description of the
 given error in err.

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