Add documentation for HTTP client API.

6 files changed, 317 insertions, 1 deletions

diff --git a/docs/nng_http_client_alloc.adoc b/docs/nng_http_client_alloc.adoc
new file mode 100644
index 00000000..32b30ce5
--- /dev/null
+++ b/docs/nng_http_client_alloc.adoc
@@ -0,0 +1,51 @@
+= nng_http_client_alloc(3)
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \
+            Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \
+            {blank} + \
+            This document is supplied under the terms of the \
+            https://opensource.org/licenses/MIT[MIT License].
+
+== NAME
+
+nng_http_client_alloc - allocate HTTP client
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_client_alloc(nng_http_client *clientp, const nng_url *url);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_client_alloc()` allocates an HTTP client suitable for
+connecting to the server identifyed by _url_ and stores a pointer to
+it in the location referenced by _clientp_.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: HTTP not supported.
+
+== SEE ALSO
+
+<<nng_http_client_connect#,nng_http_client_connect(3)>>,
+<<nng_http_client_free#,nng_http_client_free(3)>>,
+<<nng_url_parse#,nng_url_parse(3)>>
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_client_connect.adoc b/docs/nng_http_client_connect.adoc
new file mode 100644
index 00000000..c6a4fefc
--- /dev/null
+++ b/docs/nng_http_client_connect.adoc
@@ -0,0 +1,100 @@
+= nng_http_client_connect(3)
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \
+            Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \
+            {blank} + \
+            This document is supplied under the terms of the \
+            https://opensource.org/licenses/MIT[MIT License].
+
+== NAME
+
+nng_http_client_connect - establish HTTP client connection
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_http_client_connect(nng_http_client *client, nng_aio *aio);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_client_connect()` starts the process of establishing an HTTP
+connection from _client_ to the server that was indicated in the URL that
+_client_ was configured with.
+
+The result of the operation will be stored in the _aio_ when the operation
+is complete, and will be obtainable via
+<<nng_aio_result#,nng_aio_result(3)>>.
+
+On success, a pointer to the underlying HTTP client (type `nng_http_conn *`)
+will be stored in the first output result of the _aio_, and can be
+obtained by
+<<nng_aio_get_output#,nng_aio_get_output(3)>> with an _index_ of zero (0).
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+`NNG_EADDRINVAL`:: The server is configured with an invalid address.
+`NNG_ECANCELED`:: The operation was aborted.
+`NNG_ECONNREFUSED`:: The TCP connection was refused by the server.
+`NNG_ECONNRESET`:: The TCP connection was reset by the server.
+`NNG_ENOMEM`:: Insufficient free memory exists.
+
+== EXAMPLE
+
+[source, c]
+----
+    nng_aio *aio;
+    nng_url *url;
+    nng_http_client *client;
+    nng_http_conn *conn;
+    int rv;
+
+    // Error checks elided for clarity.
+    nng_url_parse(&url, "http://www.google.com");
+    nng_aio_alloc(&aio, NULL, NULL);
+    nng_http_client_alloc(&client, url);
+
+    nng_http_client_connect(client, aio);
+
+    // Wait for connection to establish (or attempt to fail).
+    nng_aio_wait(aio);
+
+    if ((rv = nng_aio_result(aio)) != 0) {
+            printf("Connection failed: %s\n", nng_strerror(rv));
+    } else {
+            // Connection established, get it.
+            conn = nng_aio_get_output(aio, 0);
+
+            // ... do something with it here
+
+            // Close the connection when done to avoid leaking it.
+            nng_http_conn_close(conn);
+    }
+----
+
+== SEE ALSO
+
+<<nng_aio_get_output#,nng_aio_get_output(3)>>,
+<<nng_aio_result#,nng_aio_result(3)>>,
+<<nng_aio_wait#,nng_aio_wait(3)>>,
+<<nng_http_client_alloc#,nng_http_client_alloc(3)>>,
+<<nng_http_conn_close#,nng_http_conn_close(3)>>,
+<<nng_http_conn_read#,nng_http_conn_read(3)>>,
+<<nng_http_conn_write#,nng_http_conn_write(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_client_free.adoc b/docs/nng_http_client_free.adoc
new file mode 100644
index 00000000..fecb5bbf
--- /dev/null
+++ b/docs/nng_http_client_free.adoc
@@ -0,0 +1,51 @@
+= nng_http_client_free(3)
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \
+            Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \
+            {blank} + \
+            This document is supplied under the terms of the \
+            https://opensource.org/licenses/MIT[MIT License].
+
+== NAME
+
+nng_http_client_free - free HTTP client
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_http_client_free(nng_http_client *client);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_client_free()` frees the HTTP client and any associated
+resources referenced by _client_.
+
+NOTE: Any connections created by
+<<nng_http_client_connect#,nng_http_client_connect(3)>> are unaffected,
+and so the caller must close those explicitly if desired.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_http_client_alloc#,nng_http_client_alloc(3)>>,
+<<nng_http_client_connect#,nng_http_client_connect(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_client_get_tls.adoc b/docs/nng_http_client_get_tls.adoc
new file mode 100644
index 00000000..ecf7f5fd
--- /dev/null
+++ b/docs/nng_http_client_get_tls.adoc
@@ -0,0 +1,54 @@
+= nng_http_client_get_tls(3)
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \
+            Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \
+            {blank} + \
+            This document is supplied under the terms of the \
+            https://opensource.org/licenses/MIT[MIT License].
+
+== NAME
+
+nng_http_client_get_tls - get HTTP client TLS configuration
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_client_get_tls(nng_http_client *client, nng_tls_config **cfgp);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_client_get_tls()` obtains the TLS configuration of _client_ and
+saves a pointer to it in the address referenced by _cfgp_.
+
+The configuration will be `NULL` if the HTTP client instance is not enabled
+to use HTTPS.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: Either HTTP or TLS not supported.
+
+== SEE ALSO
+
+<<nng_http_client_alloc#,nng_http_client_alloc(3)>>,
+<<nng_http_client_connect#,nng_http_client_connect(3)>>,
+<<nng_http_client_set_tls#,nng_http_client_set_tls(3)>>,
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_client_set_tls.adoc b/docs/nng_http_client_set_tls.adoc
new file mode 100644
index 00000000..10ff825d
--- /dev/null
+++ b/docs/nng_http_client_set_tls.adoc
@@ -0,0 +1,60 @@
+= nng_http_client_set_tls(3)
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \
+            Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \
+            {blank} + \
+            This document is supplied under the terms of the \
+            https://opensource.org/licenses/MIT[MIT License].
+
+== NAME
+
+nng_http_client_set_tls - set HTTP client TLS configuration
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_client_set_tls(nng_http_client *client, nng_tls_config *cfg);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_client_set_tls()` sets the TLS configuration of _client_ to
+_cfg_.
+
+This change overwrites any previous TLS configuration.
+
+WARNING: This also invalidates any previously obtained values from
+<<nng_http_client_get_tls#,nng_http_client_get_tls(3)>>.
+
+NOTE: Any connections established with
+<<nng_http_client_connect#,nng_http_client_connect(3)>>
+will continue to use any TLS configuration that they were started with.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: Either HTTP or TLS not supported.
+
+== SEE ALSO
+
+<<nng_http_client_alloc#,nng_http_client_alloc(3)>>,
+<<nng_http_client_connect#,nng_http_client_connect(3)>>,
+<<nng_http_client_get_tls#,nng_http_client_get_tls(3)>>,
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_set_tls.adoc b/docs/nng_http_server_set_tls.adoc
index 5dda35ed..4a2949dc 100644
--- a/docs/nng_http_server_set_tls.adoc
+++ b/docs/nng_http_server_set_tls.adoc
@@ -26,7 +26,7 @@ int nng_http_server_set_tls(nng_http_server *s, nng_tls_config *cfg);
 == DESCRIPTION
 
 The `nng_http_server_set_tls()` sets the TLS configuration of server _s_ to
-instance _s_.
+_cfg_.
 
 This change overwrites any previous TLS configuration.