From ab885ffeb1d5981a97602acbdef2ce0cfa6e4625 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 30 Aug 2018 15:55:29 -0700 Subject: man page updates for tip --- man/tip/index.html | 24 + man/tip/libnng.3.html | 30 +- man/tip/nng_aio_begin.3.html | 621 ++++++++++++++++++++++++ man/tip/nng_aio_defer.3.html | 650 +++++++++++++++++++++++++ man/tip/nng_aio_finish.3.html | 2 + man/tip/nng_http_client_transact.3http.html | 691 +++++++++++++++++++++++++++ man/tip/nng_http_conn_read_res.3http.html | 18 + man/tip/nng_http_conn_transact.3http.html | 711 ++++++++++++++++++++++++++++ man/tip/nng_http_conn_write_req.3http.html | 18 + man/tip/nng_http_conn_write_res.3http.html | 18 + man/tip/nng_http_handler_alloc.3http.html | 27 +- man/tip/nng_http_req_get_data.3http.html | 589 +++++++++++++++++++++++ man/tip/nng_http_res_get_data.3http.html | 589 +++++++++++++++++++++++ 13 files changed, 3982 insertions(+), 6 deletions(-) create mode 100644 man/tip/nng_aio_begin.3.html create mode 100644 man/tip/nng_aio_defer.3.html create mode 100644 man/tip/nng_http_client_transact.3http.html create mode 100644 man/tip/nng_http_conn_transact.3http.html create mode 100644 man/tip/nng_http_req_get_data.3http.html create mode 100644 man/tip/nng_http_res_get_data.3http.html (limited to 'man') diff --git a/man/tip/index.html b/man/tip/index.html index f870a6f0..ba8e2d5d 100644 --- a/man/tip/index.html +++ b/man/tip/index.html @@ -507,6 +507,10 @@ primary API for building such applications.

allocate asynchronous I/O handle

+

nng_aio_begin(3)

+

begin asynchronous I/O operation

+ +

nng_aio_cancel(3)

cancel asynchronous I/O operation

@@ -515,6 +519,10 @@ primary API for building such applications.

return number of bytes transferred

+

nng_aio_defer(3)

+

defer asynchronous I/O operation

+ +

nng_aio_finish(3)

finish asynchronous I/O operation

@@ -1086,6 +1094,10 @@ Protocols sockets.

set HTTP client TLS configuration

+

nng_http_client_transact(3http)

+

perform one HTTP transaction

+ +

nng_http_conn_close(3http)

close HTTP connection

@@ -1106,6 +1118,10 @@ Protocols sockets.

read HTTP response

+

nng_http_conn_transact(3http)

+

perform one HTTP transaction on connection

+ +

nng_http_conn_write(3http)

write to HTTP connection

@@ -1174,6 +1190,10 @@ Protocols sockets.

free HTTP request structure

+

nng_http_req_get_data(3http)

+

get HTTP request body

+ +

nng_http_req_get_header(3http)

return HTTP request header

@@ -1234,6 +1254,10 @@ Protocols sockets.

free HTTP response structure

+

nng_http_res_get_data(3http)

+

get HTTP response body

+ +

nng_http_res_get_header(3http)

return HTTP response header

diff --git a/man/tip/libnng.3.html b/man/tip/libnng.3.html index 81032996..f9a6c45c 100644 --- a/man/tip/libnng.3.html +++ b/man/tip/libnng.3.html @@ -921,6 +921,10 @@ Only a single asynchronous operation may be associated with an

allocate asynchronous I/O handle

+

nng_aio_begin()

+

begin asynchronous I/O operation

+ +

nng_aio_cancel()

cancel asynchronous I/O operation

@@ -929,8 +933,12 @@ Only a single asynchronous operation may be associated with an

return number of bytes transferred

+

nng_aio_defer()

+

defer asynchronous I/O operation

+ +

nng_aio_finish()

-

finish an asynchronous I/O operation

+

finish asynchronous I/O operation

nng_aio_free()

@@ -1320,6 +1328,10 @@ and connections.

free HTTP request structure

+

nng_http_req_get_data()

+

get HTTP request body

+ +

nng_http_req_get_header()

return HTTP request header

@@ -1380,8 +1392,8 @@ and connections.

free HTTP response structure

-

nng_http_res_set_data()

-

set HTTP response body

+

nng_http_res_get_data()

+

get HTTP response body

nng_http_res_get_header()

@@ -1400,6 +1412,10 @@ and connections.

return HTTP response protocol version

+

nng_http_res_set_data()

+

set HTTP response body

+ +

nng_http_res_set_header()

set HTTP response header

@@ -1449,6 +1465,14 @@ and connections.

nng_http_client_set_tls()

set HTTP client TLS configuration

+ +

nng_http_client_transact()

+

perform one HTTP transaction

+ + +

nng_http_conn_transact()

+

perform one HTTP transaction on connection

+ diff --git a/man/tip/nng_aio_begin.3.html b/man/tip/nng_aio_begin.3.html new file mode 100644 index 00000000..b48fb42a --- /dev/null +++ b/man/tip/nng_aio_begin.3.html @@ -0,0 +1,621 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_aio_begin(3) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+
+bool nng_aio_begin(nng_aio *aio);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_aio_begin() function is called by the I/O provider to indicate that +it is going to process the operation.

+
+
+

The function may return false, indicating that the aio has been closed +by the caller asynchronously. +In this case the provider should abandon the operation and do nothing else.

+
+
+

This operation should be called at the start of any I/O operation, and must +be called not more than once for a given I/O operation on a given aio.

+
+
+

Once this function is called, if true is returned, then the provider MUST +guarantee that nng_aio_finish() is called for the aio +exactly once, when the operation is complete or canceled.

+
+
+ + + + + +
+ + +This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the aio should not call this function. +
+
+
+
+
+

RETURN VALUES

+
+
+ + + + + + + + + +
+true + +

The operation has been started.

+
+false + +

The operation cannot be started.

+
+
+
+
+
+

ERRORS

+
+
+

None.

+
+
+
+
+

SEE ALSO

+
+
+

nng_aio_alloc(3), +nng_aio_cancel(3), +nng_aio_defer(3), +nng_aio_finish(3), +nng_aio_result(3), +nng_aio(5), +nng(7)

+
+
+
+
+ + diff --git a/man/tip/nng_aio_defer.3.html b/man/tip/nng_aio_defer.3.html new file mode 100644 index 00000000..58f9628d --- /dev/null +++ b/man/tip/nng_aio_defer.3.html @@ -0,0 +1,650 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_aio_defer(3) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+
+typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err);
+
+void nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_aio_defer() function marks operation associated with aio as +being deferred for asynchronous completion, and also registers a cancellation +function fn and associated argument arg, thereby +permitting the operation to be canceled.

+
+
+

If the aio is being canceled, the cancellation routine fn will be called +with the aio, the arg specified by nng_aio_defer(), and an error +value in err, which is the reason that the operation is being canceled.

+
+
+

The operation may not be cancelable; for example it may have already been +completed, or be in a state where it is no longer possible to unschedule it. +In this case, the cancelfn should just return without making any changes.

+
+
+

If the cancellation routine successfully canceled the operation, it should +ensure that nng_aio_finish() is called, with the +error code specified by err.

+
+
+ + + + + +
+ + +It is mandatory that I/O providers call +nng_aio_finish() +EXACTLY ONCE when they are finished with the operation. +
+
+
+ + + + + +
+ + +This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the aio should not call this function. +
+
+
+ + + + + +
+ + +Care must be taken to ensure that cancellation and completion of +the routine are multi-thread safe; this will usually involve the use +of locks or other synchronization primitives. +
+
+
+ + + + + +
+ + +For operations that complete synchronously, without any need to be +deferred, the provider should not bother to call nng_aio_defer(), +although it is harmless if it does. +
+
+
+
+
+

RETURN VALUES

+
+
+

None.

+
+
+
+
+

ERRORS

+
+
+

None.

+
+
+
+
+

SEE ALSO

+
+
+

nng_aio_alloc(3), +nng_aio_cancel(3), +nng_aio_finish(3), +nng_aio_result(3), +nng_aio(5), +nng(7)

+
+
+
+
+ + diff --git a/man/tip/nng_aio_finish.3.html b/man/tip/nng_aio_finish.3.html index 3b78adca..6f32acb1 100644 --- a/man/tip/nng_aio_finish.3.html +++ b/man/tip/nng_aio_finish.3.html @@ -596,7 +596,9 @@ users of the aio should not have any need for this function.

nng_aio_alloc(3), +nng_aio_begin(3), nng_aio_cancel(3), +nng_aio_defer(3), nng_aio_result(3), nng_aio(5), nng(7)

diff --git a/man/tip/nng_http_client_transact.3http.html b/man/tip/nng_http_client_transact.3http.html new file mode 100644 index 00000000..1b60b9f1 --- /dev/null +++ b/man/tip/nng_http_client_transact.3http.html @@ -0,0 +1,691 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_client_transact(3http) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+void nng_http_client_transact(nng_http_client *client, nng_http_req *req,
+    nng_http_res *res, nng_aio *aio);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_http_client_transact() function is used to perform a complete +HTTP exchange. +It creates a new connection using client, performs the transaction by +sending the request req +(and attached body data) to the remote server, then reading the response +res, and finally closes the connection that it created. +The entire response is read, including any associated body, which can +subsequently be obtained using +nng_http_res_get_data().

+
+
+

This function is intended to make creation of client applications easier, +by performing multiple asynchronous operations required to complete an +entire HTTP transaction.

+
+
+

A similar function, +nng_http_conn_transact(), +exists. +That function behaves similarily, but uses an existing connection, which +can be reused.

+
+
+ + + + + +
+ + +This function does not support reading data sent using chunked +transfer encoding, and if the server attempts to do so, the underlying +connection will be closed and an NNG_ENOTSUP error will be returned. +This limitation is considered a bug, and a fix is planned for the future. +
+
+
+ + + + + +
+ + +If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. +
+
+
+

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 nng_aio_result(). +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, or peer sent chunked encoding.

+
+NNG_EPROTO + +

An HTTP protocol error occurred.

+
+NNG_ETIMEDOUT + +

Timeout waiting for data from the connection.

+
+
+
+
+
+

SEE ALSO

+
+
+

nng_aio_alloc(3), +nng_aio_result(3), +nng_strerror(3), +nng_http_client_connect(3http), +nng_http_conn_transact(3http), +nng_http_res_get_data(3http), +nng(7)

+
+
+
+
+ + diff --git a/man/tip/nng_http_conn_read_res.3http.html b/man/tip/nng_http_conn_read_res.3http.html index 9e133e22..0b4ef951 100644 --- a/man/tip/nng_http_conn_read_res.3http.html +++ b/man/tip/nng_http_conn_read_res.3http.html @@ -565,6 +565,22 @@ the operation is signaled via the aio, and the final result may be obtained via nng_aio_result(). That result will either be zero or an error code.

+
+ + + + + +
+ + +Consider using the +nng_http_client_transact() or +nng_http_conn_transact() functions, +which provide a simpler interface for performing a complete HTTP client +transaction. +
+
@@ -640,6 +656,8 @@ That result will either be zero or an error code.

nng_aio_result(3), nng_strerror(3), nng_http_client_connect(3http), +nng_http_client_transact(3http), +nng_http_conn_transact(3http), nng_http_conn_read_all(3http), nng(7)

diff --git a/man/tip/nng_http_conn_transact.3http.html b/man/tip/nng_http_conn_transact.3http.html new file mode 100644 index 00000000..e4d1f569 --- /dev/null +++ b/man/tip/nng_http_conn_transact.3http.html @@ -0,0 +1,711 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_conn_transact(3http) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+void nng_http_conn_transact(nng_http_conn *conn, nng_http_req *req,
+    nng_http_res *res, nng_aio *aio);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_http_conn_transact() function is used to perform a complete +HTTP exchange over the connection conn, sending the request req +(and attached body data) to the remote server, and reading the response +res. +The entire response is read, including any associated body, which can +subsequently be obtained using +nng_http_res_get_data().

+
+
+

This function is intended to make creation of client applications easier, +by performing multiple asynchronous operations required to complete an +entire HTTP transaction.

+
+
+

If an error occurs, the caller should close conn with +nng_http_conn_close(), as it may not +necessarily be usable with other transactions.

+
+
+

A similar function, +nng_http_client_transact(), +exists. +That function behaves similarily, but creates a connection on demand +for the transaction, and disposes of it when finished.

+
+
+ + + + + +
+ + +This function does not support reading data sent using chunked +transfer encoding, and if the server attempts to do so, the underlying +connection will be closed and an NNG_ENOTSUP error will be returned. +This limitation is considered a bug, and a fix is planned for the future. +
+
+
+ + + + + +
+ + +If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. +
+
+
+ + + + + +
+ + +A given connection conn should be used with only one +operation or transaction at a time as HTTP/1.1 has no support for +request interleaving. +
+
+
+

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 nng_aio_result(). +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, or peer sent chunked encoding.

+
+NNG_EPROTO + +

An HTTP protocol error occurred.

+
+NNG_ETIMEDOUT + +

Timeout waiting for data from the connection.

+
+
+
+
+
+

SEE ALSO

+
+
+

nng_aio_alloc(3), +nng_aio_result(3), +nng_strerror(3), +nng_http_client_connect(3http), +nng_http_client_transact(3http), +nng_http_conn_read_res(3http), +nng_http_conn_read_all(3http), +nng_http_conn_write_req(3http), +nng_http_res_get_data(3http), +nng(7)

+
+
+
+
+ + diff --git a/man/tip/nng_http_conn_write_req.3http.html b/man/tip/nng_http_conn_write_req.3http.html index f781b1bb..934b91a5 100644 --- a/man/tip/nng_http_conn_write_req.3http.html +++ b/man/tip/nng_http_conn_write_req.3http.html @@ -552,6 +552,22 @@ Completion of the operation is signaled via the aio, and the final resu may be obtained via nng_aio_result(). That result will either be zero or an error code.

+
+ + + + + +
+ + +Consider using the +nng_http_client_transact() or +nng_http_conn_transact() functions, +which provide a simpler interface for performing a complete HTTP client +transaction. +
+
@@ -626,7 +642,9 @@ That result will either be zero or an error code.

nng_aio_alloc(3), nng_aio_result(3), nng_http_client_connect(3http), +nng_http_client_transact(3http), nng_http_conn_read_all(3http), +nng_http_conn_transact(3http), nng_strerror(3), nng(7)

diff --git a/man/tip/nng_http_conn_write_res.3http.html b/man/tip/nng_http_conn_write_res.3http.html index dd8859fc..98e23f15 100644 --- a/man/tip/nng_http_conn_write_res.3http.html +++ b/man/tip/nng_http_conn_write_res.3http.html @@ -567,6 +567,22 @@ will be reused to receive new requests.

of Close (case-insensitive) or the response corresponds to HTTP/1.0, then the connection is immediately after sending the response.

+
+ + + + + +
+ + +Consider using the +nng_http_client_transact() or +nng_http_conn_transact() functions, +which provide a simpler interface for performing a complete HTTP client +transaction. +
+
@@ -642,7 +658,9 @@ then the connection is immediately after sending the response.

nng_aio_alloc(3), nng_aio_result(3), nng_http_client_connect(3http), +nng_http_client_transact(3http), nng_http_conn_read_all(3http), +nng_http_conn_transact(3http), nng_strerror(3), nng(7)

diff --git a/man/tip/nng_http_handler_alloc.3http.html b/man/tip/nng_http_handler_alloc.3http.html index 021d4ca6..bac2c023 100644 --- a/man/tip/nng_http_handler_alloc.3http.html +++ b/man/tip/nng_http_handler_alloc.3http.html @@ -585,8 +585,10 @@ rather than just a single element.

The generic (first) form of this creates a handler that uses a user-supplied function to process HTTP requests. This function uses the asynchronous I/O framework. -The function takes a pointer to an nng_aio structure. -That structure will be passed with the following input values (retrieved with +The function takes a pointer to an nng_aio structure.

+ +
+

The aio will be passed with the following input values (retrieved with nng_aio_get_input()):

@@ -624,6 +626,24 @@ If any non-zero status is returned back to the caller instead, then a generic 500 response will be created and sent, if possible, and the connection will be closed.

+
+

The aio may be scheduled for deferred completion using the +nng_aio_defer() function.

+
+
+ + + + + +
+ + +The callback function should NOT call +nng_aio_begin(), +as that will already have been done by the server framework. +
+

Directory Handler

@@ -718,7 +738,8 @@ sent the data, with Content-Length of size bytes,

SEE ALSO

-

nng_aio_finish(3), +

nng_aio_defer(3), +nng_aio_finish(3), nng_aio_get_input(3), nng_aio_set_output(3), nng_http_handler_free(3http), diff --git a/man/tip/nng_http_req_get_data.3http.html b/man/tip/nng_http_req_get_data.3http.html new file mode 100644 index 00000000..4da3738f --- /dev/null +++ b/man/tip/nng_http_req_get_data.3http.html @@ -0,0 +1,589 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_req_get_data(3http) + + + + + + +

+
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+void nng_http_req_get_data(nng_http_req *req, void **bodyp, size_t *sizep);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_http_req_get_data() gets the HTTP body associated with +the request req, storing a pointer to the buffer at the location referenced +by bodyp, and the length of the associated buffer at the location referenced +by sizep.

+
+
+ + + + + +
+ + +The buffer returned is owned by req, and will automatically freed +when the request is freed. +
+
+
+
+
+

RETURN VALUES

+
+
+

None.

+
+
+
+
+

ERRORS

+
+
+

None.

+
+
+
+
+

SEE ALSO

+
+
+

nng_http_req_alloc(3http), +nng_http_req_copy_data(3http), +nng_http_req_copy_data(3http), +nng(7)

+
+
+
+
+ + diff --git a/man/tip/nng_http_res_get_data.3http.html b/man/tip/nng_http_res_get_data.3http.html new file mode 100644 index 00000000..78c96b21 --- /dev/null +++ b/man/tip/nng_http_res_get_data.3http.html @@ -0,0 +1,589 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_res_get_data(3http) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+void nng_http_res_get_data(nng_http_res *res, void **bodyp, size_t *sizep);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_http_res_get_data() gets the HTTP body associated with +the request res, storing a pointer to the buffer at the location referenced +by bodyp, and the length of the associated buffer at the location referenced +by sizep.

+
+
+ + + + + +
+ + +The buffer returned is owned by res, and will automatically freed +when the request is freed. +
+
+
+
+
+

RETURN VALUES

+
+
+

None.

+
+
+
+
+

ERRORS

+
+
+

None.

+
+
+
+
+

SEE ALSO

+
+
+

nng_http_req_alloc(3http), +nng_http_req_copy_data(3http), +nng_http_req_copy_data(3http), +nng(7)

+
+
+
+
+ + -- cgit v1.2.3-70-g09d2