From 03447b4532e12df48ab117c7433786334b8aeff7 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 7 Feb 2018 13:59:11 -0800 Subject: Add documentation for HTTP client API. --- docs/nng_http_client_alloc.adoc | 51 +++++++++++++++++++ docs/nng_http_client_connect.adoc | 100 ++++++++++++++++++++++++++++++++++++++ docs/nng_http_client_free.adoc | 51 +++++++++++++++++++ docs/nng_http_client_get_tls.adoc | 54 ++++++++++++++++++++ docs/nng_http_client_set_tls.adoc | 60 +++++++++++++++++++++++ docs/nng_http_server_set_tls.adoc | 2 +- 6 files changed, 317 insertions(+), 1 deletion(-) create mode 100644 docs/nng_http_client_alloc.adoc create mode 100644 docs/nng_http_client_connect.adoc create mode 100644 docs/nng_http_client_free.adoc create mode 100644 docs/nng_http_client_get_tls.adoc create mode 100644 docs/nng_http_client_set_tls.adoc (limited to 'docs') 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 + +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 + +<>, +<>, +<> +<>, +<> + +== 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 + +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 +<>. + +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 +<> 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 + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== 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 + +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 +<> are unaffected, +and so the caller must close those explicitly if desired. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<> + +== 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 + +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 + +<>, +<>, +<>, +<>, +<>, +<> + +== 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 + +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 +<>. + +NOTE: Any connections established with +<> +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 + +<>, +<>, +<>, +<>, +<>, +<> + +== 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. -- cgit v1.2.3-70-g09d2