Add documentation for HTTP client API.

1 files changed, 100 insertions, 0 deletions

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}