api: extend usage of nng_err

This replaces the int, and we will expand this further, as this
makes it clear that the int is actually an error code and helps in
debuggers that can provide symbolic values.

Author: gdamore

Diff for: docs/ref/api/aio.md

@@ -81,7 +81,7 @@ is safe to call from _aio_'s own callback.
 ## Cancellation
 
 ```c
-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);
 ```
@@ -169,7 +169,7 @@ This is the same test used internally by [`nng_aio_wait`].
 ## Result of Operation
 
 ```c
-int nng_aio_result(nng_aio *aio);
+nng_err nng_aio_result(nng_aio *aio);
 size_t nng_aio_count(nng_aio *aio);
 ```
 

Diff for: docs/ref/api/errors.md

@@ -1,21 +1,29 @@
 # Errors
 
+```c
+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.
 {{footnote: This convention goes back to UNIX system calls,
 which behave the same way, but _NNG_ does not use a separate
 _errno_ variable.}}
 
-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
 
 ```c
-const char *nng_strerror(int err);
+const char *nng_strerror(nng_err err);
 ```
 
 The {{i:`nng_strerror`}} returns the human-readable description of the

Diff for: docs/ref/api/http.md

@@ -56,7 +56,7 @@ set when issuing the transaction.
 ### HTTP URI
 
 ```c
-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);
 ```
 
@@ -76,7 +76,7 @@ will have any query concentated, for example "/api/get_user.cgi?name=garrett".
 ### HTTP Version
 
 ```c
-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);
 ```
 
@@ -210,8 +210,8 @@ The scan can be rest by setting _next_ to `NULL`.
 ### Modifying Headers
 
 ```c
-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);
 ```
 
@@ -323,7 +323,7 @@ They can be used to transfer request or response body data as well.
 ### Hijacking Connections
 
 ```c
-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.
@@ -387,8 +387,8 @@ of its resources.
 ### Client TLS
 
 ```c
-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 {{i:`nng_http_client_get_tls`}} and {{i:`nng_http_client_set_tls`}} functions are used to
@@ -456,15 +456,6 @@ if ((rv = nng_aio_result(aio)) != 0) {
 
 ### Preparing a Transaction
 
-```c
-int nng_http_set_version(nng_http *conn, const char *version);
-int nng_http_set_uri(nng_http *conn, const char *uri);
-```
-
-The {{i:`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
@@ -510,7 +501,7 @@ It does _not_ transfer any response body. To do that, use [`nng_http_read_all`]
 ### Submitting the Transaction
 
 ```c
-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 {{i:`nng_http_transact`}} function.

Diff for: include/nng/http.h

@@ -147,7 +147,7 @@ NNG_DECL void nng_http_reset(nng_http *);
 // include an optional query string, either inline in the URI to start,
 // or as a separate argument.  If the query string already exists
 // and one is also supplied here, it will be appended (separated with &).
-NNG_DECL int nng_http_set_uri(nng_http *, const char *, const char *);
+NNG_DECL nng_err nng_http_set_uri(nng_http *, const char *, const char *);
 
 // nng_http_get_uri returns the URI.  It will be NULL if not set.
 NNG_DECL const char *nng_http_get_uri(nng_http *);
@@ -167,7 +167,7 @@ NNG_DECL void nng_http_set_status(nng_http *, uint16_t, const char *);
 // nng_http_set_version is used to change the version of a request.
 // Normally the version is "HTTP/1.1".  Note that the framework does
 // not support HTTP/2 at all.  Null sets the default ("HTTP/1.1").
-NNG_DECL int nng_http_set_version(nng_http *, const char *);
+NNG_DECL nng_err nng_http_set_version(nng_http *, const char *);
 
 // nng_http_get_version is used to get the version of a request.
 NNG_DECL const char *nng_http_get_version(nng_http *);
@@ -184,8 +184,8 @@ NNG_DECL const char *nng_http_get_method(nng_http *);
 // a header to either the request or response.  Clients modify the request
 // headers, and servers (and callbacks on the server) modify response headers.
 // These can return NNG_ENOMEM, NNG_MSGSIZE, etc.
-NNG_DECL int nng_http_set_header(nng_http *, const char *, const char *);
-NNG_DECL int nng_http_add_header(nng_http *, const char *, const char *);
+NNG_DECL nng_err nng_http_set_header(nng_http *, const char *, const char *);
+NNG_DECL nng_err nng_http_add_header(nng_http *, const char *, const char *);
 
 // nng_http_del_header removes all of the headers for the given header.
 // For clients this is done on the request headers, for servers its the
@@ -205,7 +205,7 @@ NNG_DECL void nng_http_set_body(nng_http *, void *, size_t);
 
 // nng_http_copy_body sets the body to send out in the next exchange, but
 // makes a local copy.  It can fail due to NNG_ENOMEM.
-NNG_DECL int nng_http_copy_body(nng_http *, const void *, size_t);
+NNG_DECL nng_err nng_http_copy_body(nng_http *, const void *, size_t);
 
 // nng_http_handler is a handler used on the server side to handle HTTP
 // requests coming into a specific URL.
@@ -230,7 +230,7 @@ typedef struct nng_http_handler nng_http_handler;
 // completion by nng_aio_finish.  The second argument to this function is the
 // handler data that was optionally set by nng_handler_set_data.
 typedef void (*nng_http_handler_func)(nng_http *, void *, nng_aio *);
-NNG_DECL int nng_http_handler_alloc(
+NNG_DECL nng_err nng_http_handler_alloc(
     nng_http_handler **, const char *, nng_http_handler_func);
 
 // nng_http_handler_free frees the handler. This actually just drops a
@@ -241,19 +241,19 @@ NNG_DECL void nng_http_handler_free(nng_http_handler *);
 // nng_http_handler_alloc_file creates a "file" based handler, that
 // serves up static content from the given file path.  The content-type
 // supplied is determined from the file name using a simple built-in map.
-NNG_DECL int nng_http_handler_alloc_file(
+NNG_DECL nng_err nng_http_handler_alloc_file(
     nng_http_handler **, const char *, const char *);
 
 // nng_http_handler_alloc_static creates a static-content handler.
 // The last argument is the content-type, which may be NULL (in which case
 // "application/octet-stream" is assumed.)
-NNG_DECL int nng_http_handler_alloc_static(
+NNG_DECL nng_err nng_http_handler_alloc_static(
     nng_http_handler **, const char *, const void *, size_t, const char *);
 
 // nng_http_handler_alloc_redirect creates an HTTP redirect handler.
 // The status is given, along with the new URL.  If the status is 0,
 // then 301 will be used instead.
-NNG_DECL int nng_http_handler_alloc_redirect(
+NNG_DECL nng_err nng_http_handler_alloc_redirect(
     nng_http_handler **, const char *, uint16_t, const char *);
 
 // nng_http_handler_alloc_file creates a "directory" based handler, that
@@ -262,7 +262,7 @@ NNG_DECL int nng_http_handler_alloc_redirect(
 // directory content, otherwise a suitable error page is returned (the server
 // does not generate index pages automatically.)  The content-type for
 // files is determined from the file name using a simple built-in map.
-NNG_DECL int nng_http_handler_alloc_directory(
+NNG_DECL nng_err nng_http_handler_alloc_directory(
     nng_http_handler **, const char *, const char *);
 
 // nng_http_handler_set_method sets the method that the handler will be
@@ -310,7 +310,7 @@ typedef struct nng_http_server nng_http_server;
 // from the URL.  If a server already exists, then a hold is placed on it, and
 // that instance is returned.  If no such server exists, then a new instance
 // is created.
-NNG_DECL int nng_http_server_hold(nng_http_server **, const nng_url *);
+NNG_DECL nng_err nng_http_server_hold(nng_http_server **, const nng_url *);
 
 // nng_http_server_release releases the hold on the server.  If this is the
 // last instance of the server, then it is shutdown and resources are freed.
@@ -319,7 +319,7 @@ NNG_DECL void nng_http_server_release(nng_http_server *);
 // nng_http_server_start starts the server handling HTTP.  Once this is
 // called, it will not be possible to change certain parameters (such as
 // any TLS configuration).
-NNG_DECL int nng_http_server_start(nng_http_server *);
+NNG_DECL nng_err nng_http_server_start(nng_http_server *);
 
 // nng_http_server_stop stops the server.  No new client connections are
 // accepted after this returns.  Once a server is stopped fully, the
@@ -331,14 +331,14 @@ NNG_DECL void nng_http_server_stop(nng_http_server *);
 // This function will return NNG_EADDRINUSE if a conflicting handler
 // is already registered (i.e. a handler with the same value for Host,
 // Method, and URL.)
-NNG_DECL int nng_http_server_add_handler(
+NNG_DECL nng_err nng_http_server_add_handler(
     nng_http_server *, nng_http_handler *);
 
 // nni_http_del_handler removes the given handler.  The caller is
 // responsible for finalizing it afterwards.  If the handler was not found
 // (not registered), NNG_ENOENT is returned.  In this case it is unsafe
 // to make assumptions about the validity of the handler.
-NNG_DECL int nng_http_server_del_handler(
+NNG_DECL nng_err nng_http_server_del_handler(
     nng_http_server *, nng_http_handler *);
 
 // nng_http_server_set_tls adds a TLS configuration to the server,
@@ -347,36 +347,36 @@ NNG_DECL int nng_http_server_del_handler(
 // server client, so the caller must have configured it reasonably.
 // This API is not recommended unless the caller needs complete control
 // over the TLS configuration.
-NNG_DECL int nng_http_server_set_tls(nng_http_server *, nng_tls_config *);
+NNG_DECL nng_err nng_http_server_set_tls(nng_http_server *, nng_tls_config *);
 
 // nng_http_server_get_tls obtains the TLS configuration if one is present,
 // or returns NNG_EINVAL.  The TLS configuration is invalidated if the
 // nng_http_server_set_tls function is called, so be careful.
-NNG_DECL int nng_http_server_get_tls(nng_http_server *, nng_tls_config **);
+NNG_DECL nng_err nng_http_server_get_tls(nng_http_server *, nng_tls_config **);
 
 // nng_http_server_get_addr obtains the address with which the server was
 // initialized or returns NNG_EINVAL. Useful for instance when the port has
 // been automatically assigned.
-NNG_DECL int nng_http_server_get_addr(nng_http_server *, nng_sockaddr *);
+NNG_DECL nng_err nng_http_server_get_addr(nng_http_server *, nng_sockaddr *);
 
 // nng_http_server_set_error_page sets a custom error page (HTML) content
 // to be sent for the given error code.  This is used when the error is
 // generated internally by the framework.
-NNG_DECL int nng_http_server_set_error_page(
+NNG_DECL nng_err nng_http_server_set_error_page(
     nng_http_server *, uint16_t, const char *);
 
 // nng_http_server_set_error_file works like nng_http_server_error_page,
 // except that the content is loaded from the named file path.  The contents
 // are loaded at the time this function is called, so this function should be
 // called anytime the contents of the named file have changed.
-NNG_DECL int nng_http_server_set_error_file(
+NNG_DECL nng_err nng_http_server_set_error_file(
     nng_http_server *, uint16_t, const char *);
 
-// nng_http_server_res_error takes replaces the body of the response with
+// nng_http_server_error takes replaces the body of the response with
 // a custom error page previously set for the server, using the status
 // of the response.  The response must have the status set first using
 // nng_http_res_set_status.
-NNG_DECL int nng_http_server_error(nng_http_server *, nng_http *);
+NNG_DECL nng_err nng_http_server_error(nng_http_server *, nng_http *);
 
 // nng_http_hijack is intended to be called by a handler that wishes to
 // take over the processing of the HTTP session -- usually to change protocols
@@ -389,7 +389,7 @@ NNG_DECL int nng_http_server_error(nng_http_server *, nng_http *);
 // of the request structure.  (Some hijackers may keep the request for
 // further processing.)
 
-NNG_DECL int nng_http_hijack(nng_http *);
+NNG_DECL nng_err nng_http_hijack(nng_http *);
 
 // nng_http_client represents a "client" object.  Clients can be used
 // to create HTTP connections.  At present, connections are not cached
@@ -398,7 +398,7 @@ typedef struct nng_http_client nng_http_client;
 
 // nng_http_client_alloc allocates a client object, associated with
 // the given URL.
-NNG_DECL int nng_http_client_alloc(nng_http_client **, const nng_url *);
+NNG_DECL nng_err nng_http_client_alloc(nng_http_client **, const nng_url *);
 
 // nng_http_client_free frees the client.  Connections created by the
 // the client are not necessarily closed.
@@ -408,12 +408,12 @@ NNG_DECL void nng_http_client_free(nng_http_client *);
 // the entire TLS configuration on the client, so the caller must have
 // configured it reasonably.  This API is not recommended unless the
 // caller needs complete control over the TLS configuration.
-NNG_DECL int nng_http_client_set_tls(nng_http_client *, nng_tls_config *);
+NNG_DECL nng_err nng_http_client_set_tls(nng_http_client *, nng_tls_config *);
 
 // nng_http_client_get_tls obtains the TLS configuration if one is present,
 // or returns NNG_EINVAL.  The supplied TLS configuration object may
 // be invalidated by any future calls to nni_http_client_set_tls.
-NNG_DECL int nng_http_client_get_tls(nng_http_client *, nng_tls_config **);
+NNG_DECL nng_err nng_http_client_get_tls(nng_http_client *, nng_tls_config **);
 
 // nng_http_client_connect establishes a new connection with the server
 // named in the URL used when the client was created.  Once the connection