forked from nanomsg/nng
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
fixes nanomsg#681 HTTP convenience GET method desired...
This adds a couple of new methods, and related documentation and test cases.
- Loading branch information
Showing
15 changed files
with
793 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| = nng_http_client_transact(3http) | ||
| // | ||
| // Copyright 2018 Staysail Systems, Inc. <[email protected]> | ||
| // Copyright 2018 Capitar IT Group BV <[email protected]> | ||
| // | ||
| // This document is supplied under the terms of the MIT License, a | ||
| // copy of which should be located in the distribution where this | ||
| // file was obtained (LICENSE.txt). A copy of the license may also be | ||
| // found online at https://opensource.org/licenses/MIT. | ||
| // | ||
|
|
||
| == NAME | ||
|
|
||
| nng_http_client_transact - perform one HTTP transaction | ||
|
|
||
| == SYNOPSIS | ||
|
|
||
| [source, c] | ||
| ---- | ||
| #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.3http#,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.3http#,nng_http_conn_transact()>>`, | ||
| exists. | ||
| That function behaves similarily, but uses an existing connection, which | ||
| can be reused. | ||
|
|
||
| NOTE: 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. | ||
|
|
||
| WARNING: 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.3#,nng_aio_result()>>`. | ||
| That result will either be zero or an error code. | ||
|
|
||
| == RETURN VALUES | ||
|
|
||
| None. | ||
|
|
||
| == ERRORS | ||
|
|
||
| [horizontal] | ||
| `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 | ||
|
|
||
| [.text-left] | ||
| <<nng_aio_alloc.3#,nng_aio_alloc(3)>>, | ||
| <<nng_aio_result.3#,nng_aio_result(3)>>, | ||
| <<nng_strerror.3#,nng_strerror(3)>>, | ||
| <<nng_http_client_connect.3http#,nng_http_client_connect(3http)>>, | ||
| <<nng_http_conn_transact.3http#,nng_http_conn_transact(3http)>>, | ||
| <<nng_http_res_get_data.3http#,nng_http_res_get_data(3http)>>, | ||
| <<nng.7#,nng(7)>> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| = nng_http_conn_transact(3http) | ||
| // | ||
| // Copyright 2018 Staysail Systems, Inc. <[email protected]> | ||
| // Copyright 2018 Capitar IT Group BV <[email protected]> | ||
| // | ||
| // This document is supplied under the terms of the MIT License, a | ||
| // copy of which should be located in the distribution where this | ||
| // file was obtained (LICENSE.txt). A copy of the license may also be | ||
| // found online at https://opensource.org/licenses/MIT. | ||
| // | ||
|
|
||
| == NAME | ||
|
|
||
| nng_http_conn_transact - perform one HTTP transaction on connection | ||
|
|
||
| == SYNOPSIS | ||
|
|
||
| [source, c] | ||
| ---- | ||
| #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.3http#,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.3http#,nng_http_conn_close()>>`, as it may not | ||
| necessarily be usable with other transactions. | ||
|
|
||
| A similar function, | ||
| `<<nng_http_client_transact.3http#,nng_http_client_transact()>>`, | ||
| exists. | ||
| That function behaves similarily, but creates a connection on demand | ||
| for the transaction, and disposes of it when finished. | ||
|
|
||
| NOTE: 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. | ||
|
|
||
| WARNING: 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. | ||
|
|
||
| WARNING: 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.3#,nng_aio_result()>>`. | ||
| That result will either be zero or an error code. | ||
|
|
||
| == RETURN VALUES | ||
|
|
||
| None. | ||
|
|
||
| == ERRORS | ||
|
|
||
| [horizontal] | ||
| `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 | ||
|
|
||
| [.text-left] | ||
| <<nng_aio_alloc.3#,nng_aio_alloc(3)>>, | ||
| <<nng_aio_result.3#,nng_aio_result(3)>>, | ||
| <<nng_strerror.3#,nng_strerror(3)>>, | ||
| <<nng_http_client_connect.3http#,nng_http_client_connect(3http)>>, | ||
| <<nng_http_client_transact.3http#,nng_http_client_transact(3http)>>, | ||
| <<nng_http_conn_read_res.3http#,nng_http_conn_read_res(3http)>>, | ||
| <<nng_http_conn_read_all.3http#,nng_http_conn_read_all(3http)>>, | ||
| <<nng_http_conn_write_req.3http#,nng_http_conn_write_req(3http)>>, | ||
| <<nng_http_res_get_data.3http#,nng_http_res_get_data(3http)>>, | ||
| <<nng.7#,nng(7)>> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| = nng_http_req_get_data(3http) | ||
| // | ||
| // Copyright 2018 Staysail Systems, Inc. <[email protected]> | ||
| // Copyright 2018 Capitar IT Group BV <[email protected]> | ||
| // | ||
| // This document is supplied under the terms of the MIT License, a | ||
| // copy of which should be located in the distribution where this | ||
| // file was obtained (LICENSE.txt). A copy of the license may also be | ||
| // found online at https://opensource.org/licenses/MIT. | ||
| // | ||
|
|
||
| == NAME | ||
|
|
||
| nng_http_req_get_data - get HTTP request body | ||
|
|
||
| == SYNOPSIS | ||
|
|
||
| [source, c] | ||
| ---- | ||
| #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_. | ||
|
|
||
| NOTE: The buffer returned is owned by _req_, and will automatically freed | ||
| when the request is freed. | ||
|
|
||
| == RETURN VALUES | ||
|
|
||
| None. | ||
|
|
||
| == ERRORS | ||
|
|
||
| None. | ||
|
|
||
| == SEE ALSO | ||
|
|
||
| [.text-left] | ||
| <<nng_http_req_alloc.3http#,nng_http_req_alloc(3http)>>, | ||
| <<nng_http_req_set_data.3http#,nng_http_req_copy_data(3http)>>, | ||
| <<nng_http_req_copy_data.3http#,nng_http_req_copy_data(3http)>>, | ||
| <<nng.7#,nng(7)>> |
Oops, something went wrong.