From b893f8ff1f96dde567fa6a75f4b15bf69e53d6f5 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 2 Feb 2018 16:59:26 -0800 Subject: Document the HTTP connection handling API. --- docs/nng_http_conn_close.adoc | 49 ++++++++++++++++++++ docs/nng_http_conn_read.adoc | 76 ++++++++++++++++++++++++++++++ docs/nng_http_conn_read_all.adoc | 79 +++++++++++++++++++++++++++++++ docs/nng_http_conn_read_req.adoc | 67 +++++++++++++++++++++++++++ docs/nng_http_conn_read_res.adoc | 67 +++++++++++++++++++++++++++ docs/nng_http_conn_write.adoc | 77 +++++++++++++++++++++++++++++++ docs/nng_http_conn_write_all.adoc | 97 +++++++++++++++++++++++++++++++++++++++ docs/nng_http_conn_write_req.adoc | 65 ++++++++++++++++++++++++++ docs/nng_http_conn_write_res.adoc | 65 ++++++++++++++++++++++++++ 9 files changed, 642 insertions(+) create mode 100644 docs/nng_http_conn_close.adoc create mode 100644 docs/nng_http_conn_read.adoc create mode 100644 docs/nng_http_conn_read_all.adoc create mode 100644 docs/nng_http_conn_read_req.adoc create mode 100644 docs/nng_http_conn_read_res.adoc create mode 100644 docs/nng_http_conn_write.adoc create mode 100644 docs/nng_http_conn_write_all.adoc create mode 100644 docs/nng_http_conn_write_req.adoc create mode 100644 docs/nng_http_conn_write_res.adoc diff --git a/docs/nng_http_conn_close.adoc b/docs/nng_http_conn_close.adoc new file mode 100644 index 00000000..885015a6 --- /dev/null +++ b/docs/nng_http_conn_close.adoc @@ -0,0 +1,49 @@ += nng_http_conn_close(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_conn_close - close HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_close(nng_http_conn *conn); +----------- + +== DESCRIPTION + +The `nng_http_conn_close()` function closes the supplied HTTP connection _conn_, +including any disposing of any underlying file descriptors or related resources. + +Once this function, no further access to the _conn_ structure may be made. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_read.adoc b/docs/nng_http_conn_read.adoc new file mode 100644 index 00000000..d5d85aba --- /dev/null +++ b/docs/nng_http_conn_read.adoc @@ -0,0 +1,76 @@ += nng_http_conn_read(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_conn_read - read from HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_read(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read()` function starts an asynchronous read from the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +read, or an error has occurred. +Therefore, the number of bytes read may be less than requested. The actual +number of bytes read can be determined with <>. + +TIP: This function is intended to facilitate uses cases that involve changing +the protocol from HTTP -- such as WebSocket. Most applications will never need +to use this function. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_read_all.adoc b/docs/nng_http_conn_read_all.adoc new file mode 100644 index 00000000..6e469ae6 --- /dev/null +++ b/docs/nng_http_conn_read_all.adoc @@ -0,0 +1,79 @@ += nng_http_conn_read_all(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_conn_read_all - read all from HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_read_all(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read_all()` function starts an asynchronous read from the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +The I/O operation completes only when the entire amount of data +requested has been read, or an error has occurred. If the operation +completes successfully, then the entire requested data has been read. + +It is still possible for a partial read to complete in the event of an +error. The actual number of bytes read can be determined with +<>. + +TIP: The main purpose for this function is to faciliate reading HTTP +body content, after first determining the length of the body content +from the relevant HTTP headers (typically `Content-Length`). + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_read_req.adoc b/docs/nng_http_conn_read_req.adoc new file mode 100644 index 00000000..8759a699 --- /dev/null +++ b/docs/nng_http_conn_read_req.adoc @@ -0,0 +1,67 @@ += nng_http_conn_read_req(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_conn_read_req - read HTTP request + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_read_req(nng_http_conn *conn, nng_http_req *req, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read_req()` function starts an asynchronous read from the +HTTP connection _conn_, reading an HTTP request into the _req_, including all +of the related headers. + +NOTE: Any HTTP entity/body data associated with the request is *not* read +automatically. The caller should use +<> to read the entity +data, based on the details of the request itself. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_read_res.adoc b/docs/nng_http_conn_read_res.adoc new file mode 100644 index 00000000..6bfa3460 --- /dev/null +++ b/docs/nng_http_conn_read_res.adoc @@ -0,0 +1,67 @@ += nng_http_conn_read_res(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_conn_read_res - read HTTP response + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_read_res(nng_http_conn *conn, nng_http_res *res, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read_res()` function starts an asynchronous read from the +HTTP connection _conn_, reading an HTTP response into the _res_, including all +of the related headers. + +NOTE: Any HTTP entity/body data associated with the response is *not* read +automatically. The caller should use +<> to read the entity +data, based on the details of the response itself. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_write.adoc b/docs/nng_http_conn_write.adoc new file mode 100644 index 00000000..0f57c0c2 --- /dev/null +++ b/docs/nng_http_conn_write.adoc @@ -0,0 +1,77 @@ += nng_http_conn_write(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_conn_write - write to HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_write(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write()` function starts an asynchronous write to the +HTTP connection _conn_ from the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +written, or an error has occurred. +Therefore, the number of bytes written may be less than requested. The actual +number of bytes written can be determined with +<>. + +TIP: This function is intended to facilitate uses cases that involve changing +the protocol from HTTP -- such as WebSocket. Most applications will never need +to use this function. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_write_all.adoc b/docs/nng_http_conn_write_all.adoc new file mode 100644 index 00000000..1b5a06c3 --- /dev/null +++ b/docs/nng_http_conn_write_all.adoc @@ -0,0 +1,97 @@ += nng_http_conn_write_all(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_conn_write_all - write all to HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_write_all(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write_all()` function starts an asynchronous write to the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +The I/O operation completes only when the entire amount of data +requested has been written, or an error has occurred. If the operation +completes successfully, then the entire requested data has been written. + +It is still possible for a partial write to complete in the event of an +error. The actual number of bytes written can be determined with +<>. + +TIP: The main purpose for this function is to faciliate writing HTTP +body content. + +TIP: Usually an HTTP request or response will have been written immediately +prior to this with <> or +<>. In that case the +request or response should have also contained an `Content-Length` header, +and possibly a `Content-Type` header. + +TIP: An easier solution to sending HTTP content data, is to include the +conten with the request or reply using a function like +<>. In that case, +the body data will be written automatically by the +<> or +<> function. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_write_req.adoc b/docs/nng_http_conn_write_req.adoc new file mode 100644 index 00000000..d73252f9 --- /dev/null +++ b/docs/nng_http_conn_write_req.adoc @@ -0,0 +1,65 @@ += nng_http_conn_write_req(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_conn_write_req - write HTTP request + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_write_req(nng_http_conn *conn, nng_http_req *req, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write_req()` function starts an asynchronous write of +the HTTP request _req_ to the connection _conn_. The entire request is sent, +including headers, and if present, the request body data. (The +request body can be set with +<> or +<>.) + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_conn_write_res.adoc b/docs/nng_http_conn_write_res.adoc new file mode 100644 index 00000000..8f5a407d --- /dev/null +++ b/docs/nng_http_conn_write_res.adoc @@ -0,0 +1,65 @@ += nng_http_conn_write_res(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_conn_write_res - write HTTP response + +== SYNOPSIS + +[source, c] +----------- +#include + +void nng_http_conn_write_res(nng_http_conn *conn, nng_http_res *res, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write_res()` function starts an asynchronous write of +the HTTP response _res_ to the connection _conn_. The entire response is sent, +including headers, and if present, the response body data. (The +response body can be set with +<> or +<>.) + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <>. That result will +either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} -- cgit v1.2.3-70-g09d2