diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/SUMMARY.md | 2 | ||||
| -rw-r--r-- | docs/ref/api/http.md | 1 | ||||
| -rw-r--r-- | docs/ref/api/index.md | 1 | ||||
| -rw-r--r-- | docs/ref/api/pipe.md | 157 | ||||
| -rw-r--r-- | docs/ref/xref.md | 28 |
5 files changed, 184 insertions, 5 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 1c5ad2a5..fe05512f 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -14,6 +14,8 @@ - [Contexts](./api/ctx.md) + - [Pipes](./api/pipe.md) + - [Memory](./api/memory.md) - [Time](./api/time.md) diff --git a/docs/ref/api/http.md b/docs/ref/api/http.md index 548339f3..dfa9d07d 100644 --- a/docs/ref/api/http.md +++ b/docs/ref/api/http.md @@ -106,6 +106,7 @@ void nng_http_set_status(nng_http *conn, nng_http_status status, const char *rea The {{i:`nng_http_get_status`}} function obtains the numeric code (typipcally numbered from 100 through 599) returned by the server in the last exchange on _conn_. (If no exchange has been performed yet, the result is undefined.) +The value is returned as an {{i:`nng_http_status`}}. A descriptive message matching the status code is returned by {{i:`nng_http_get_reason`}}. diff --git a/docs/ref/api/index.md b/docs/ref/api/index.md index 77cbfca6..ef1a827d 100644 --- a/docs/ref/api/index.md +++ b/docs/ref/api/index.md @@ -18,6 +18,7 @@ include the `nng/nng.h` header file like so: - [Messages](msg.md) - [Sockets](sock.md) - [Contexts](ctx.md) +- [Pipes](pipe.md) - [Memory](memory.md) - [Time](time.md) - [URLs](url.md) diff --git a/docs/ref/api/pipe.md b/docs/ref/api/pipe.md new file mode 100644 index 00000000..fbd89120 --- /dev/null +++ b/docs/ref/api/pipe.md @@ -0,0 +1,157 @@ +# Pipes + +```c +typedef struct nng_pipe_s nng_pipe; +``` + +An {{i:`nng_pipe`}} is a handle to a {{i:pipe}} object, which can be thought of as a single {{i:connection}}. +(In most cases this is actually the case -- the pipe is an abstraction for a single TCP or IPC connection.) +Pipes are associated with either the listener or dialer that created them, +and therefore are also automatically associated with a single socket. + +> [!NOTE] +> The `nng_pipe` structure is always passed by value (both +> for input parameters and return values), and should be treated opaquely. +> Passing structures this way gives the compiler a chance to perform +> accurate type checks in functions passing values of this type. + +> [!TIP] +> Most applications should never concern themselves with individual pipes. +> However it is possible to access a pipe when more information about the +> source of a message is needed, or when more control is required over message delivery. + +Pipe objects are created by [dialers][dialer] and and [listeners][listener]. + +## Initialization + +A pipe may be initialized using the macro {{i:`NNG_PIPE_INITIALIZER`}} +before it is opened, to prevent confusion with valid open pipes. + +For example: + +```c +nng_pipe p = NNG_PIPE_INITIALIZER; +``` + +## Pipe Identity + +```c +int nng_pipe_id(nng_pipe p); +``` + +The {{i:`nng_pipe_id`}} function returns a positive identifier for the pipe _p_, if it is valid. +Otherwise it returns `-1`. + +> [!NOTE] +> A pipe is considered valid if it was ever created by the socket. +> Pipes that are allocated on the stack or statically should be initialized with the macro +> [`NNG_PIPE_INITIALIZER`] to ensure that they cannot be confused with a valid pipe. + +## Closing a Pipe + +```c +nng_err nng_pipe_close(nng_pipe p); +``` + +The {{i:`nng_pipe_close`}} function closes the supplied pipe, _p_. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport. + +Further attempts to use the pipe after this call returns will result in [`NNG_ECLOSED`]. + +> [!TIP] +> Pipes are automatically closed when their creator closes, or when the +> remote peer closes the underlying connection. + +## Pipe Creator + +```c +nng_dialer nng_pipe_dialer(nng_pipe p); +nng_listener nng_pipe_listener(nng_pipe p); +nng_socket nng_pipe_socket(nng_pipe p); +``` + +{{hi:`nng_pipe_dialer`}} +{{hi:`nng_pipe_listener`}} +{{hi:`nng_pipe_socket`}} +These functions return the [socket], [dialer], or [listener] that created or owns the pipe. + +If the pipe was does not have an associated dialer or listener, then the associated will +return [`NNG_DIALER_INITIALIZER`] or [`NNG_LISTENER_INITIALIZER`], as appropriate, and +either [`nng_dialer_id`] or [`nng_listener_id`] for the returned object will return -1. + +> [!NOTE] +> The socket, or the endpoint, returned by these functions may be in the process of closing, +> and might not be further usable as a result. (Other functions will result in [`NNG_ECLOSED`].) + +## Pipe Options + +```c +nng_err nng_pipe_get_bool(nng_pipe p, const char *opt, bool *valp); +nng_err nng_pipe_get_int(nng_pipe p, const char *opt, int *valp); +nng_err nng_pipe_get_ms(nng_pipe p, const char *opt, nng_duration *valp); +nng_err nng_pipe_get_size(nng_pipe p, const char *opt, size_t *valp); +nng_err nng_pipe_get_addr(nng_pipe p, const char *opt, nng_sockaddr *valp); +nng_err nng_pipe_get_string(nng_pipe p, const char *opt, char **valp); +``` + +{{hi:`nng_pipe_get_bool`}} +{{hi:`nng_pipe_get_int`}} +{{hi:`nng_pipe_get_ms`}} +{{hi:`nng_pipe_get_size`}} +{{hi:`nng_pipe_get_addr`}} +{{hi:`nng_pipe_get_string`}} +These functions are used to obtain value of an option named _opt_ from the pipe _p_, and store it in the location +referenced by _valp_. + +These functions access an option as a specific type. The transport layer will have details about which options +are available, and which type they may be accessed using. + +In the case of `nng_pipe_get_string`, the string is created as if by [`nng_strdup`], and must be freed by +the caller using [`nng_strfree`] when no longer needed. + +## Pipe Notifications + +```c +typedef enum { + NNG_PIPE_EV_ADD_PRE, + NNG_PIPE_EV_ADD_POST, + NNG_PIPE_EV_REM_POST, +} nng_pipe_ev; + +typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_ev, void *); + +nng_err nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg); +``` + +The {{i:`nng_pipe_notify`}} function registers the callback function _cb_ +to be called whenever the pipe event specified by +_ev_ occurs on the socket _s_. +The callback _cb_ will be passed _arg_ as its final argument. + +A different callback may be supplied for each event. +Each event may have at most one callback registered. +Registering a callback implicitly unregisters any previously registered. + +The following pipe events are supported: + +| Event | Description | +| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| {{i:`NNG_PIPE_EV_ADD_PRE`}}<a name="NNG_PIPE_EV_ADD_PRE"></a> | This event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using [`nng_pipe_close`]) at this point, the socket will never see the pipe, and no further events will occur for the given pipe. | +| {{i:`NNG_PIPE_EV_ADD_POST`}}<a name="NNG_PIPE_EV_ADD_POST"></a> | This event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket. | +| {{i:`NNG_PIPE_EV_REM_POST`}}<a name="NNG_PIPE_EV_REM_POST"></a> | This event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe. | + +> [!WARNING] +> The callback _cb_ function must _not_ attempt to perform any +> accesses to the socket, as it is called with a lock on the socket held! +> Doing so would thus result in a deadlock. + +> [!TIP] +> The callback _cb_ may close a pipe for any reason by simply closing it using [`nng_pipe_close`]. +> For example, this might be done to prevent an unauthorized peer from connecting to the socket, +> if an authorization check made during `NNG_PIPE_EV_ADD_PRE` fails. + +> [!NOTE] +> This function ignores invalid values for _ev_. + +{{#include ../xref.md}} diff --git a/docs/ref/xref.md b/docs/ref/xref.md index bee853ff..e3b57585 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -236,6 +236,19 @@ [`nng_ctx_send`]: /api/ctx.md#nng_ctx_send [`nng_ctx_recvmsg`]: /api/ctx.md#nng_ctx_recvmsg [`nng_ctx_recv`]: /api/ctx.md#nng_ctx_recv +[`nng_pipe`]: /api/pipe.md#pipes +[`nng_pipe_id`]: /api/pipe.md#pipe-identity +[`nng_pipe_close`]: /api/pipe.md#closing-a-pipe +[`nng_pipe_dialer`]: /api/pipe.md#pipe-creator +[`nng_pipe_listener`]: /api/pipe.md#pipe-creator +[`nng_pipe_socket`]: /api/pipe.md#pipe-creator +[`nng_pipe_get_bool`]: /api/pipe.md#pipe-options +[`nng_pipe_get_int`]: /api/pipe.md#pipe-options +[`nng_pipe_get_ms`]: /api/pipe.md#pipe-options +[`nng_pipe_get_size`]: /api/pipe.md#pipe-options +[`nng_pipe_get_addr`]: /api/pipe.md#pipe-options +[`nng_pipe_get_string`]: /api/pipe.md#pipe-options +[`nng_pipe_notify`]: /api/pipe.md#pipe-notifications [`nng_sockaddr`]: /TODO.md [`nng_sockaddr_in`]: /TODO.md [`nng_sockaddr_in6`]: /TODO.md @@ -258,19 +271,20 @@ [`nng_http_set_version`]: /api/http.md#http-protocol-versions [`nng_http_get_method`]: /api/http.md#http-method [`nng_http_set_method`]: /api/http.md#http-method -[`nng_http_set_url`]: /api/http.md#preparing-a-transaction +[`nng_http_set_uri`]: /api/http.md#http-uri +[`nng_http_get_uri`]: /api/http.md#http-uri [`nng_http_get_reason`]: /api/http.md#http-status [`nng_http_get_status`]: /api/http.md#http-status [`nng_http_set_status`]: /api/http.md#http-status -[`nng_http_get_url`]: /TODO.md [`nng_http_hijack`]: /api/http.md#hijacking-connections [`nng_http_get_header`]: /api/http.md#retrieving-headers [`nng_http_next_header`]: /api/http.md#retrieving-headers [`nng_http_add_header`]: /api/http.md#modifying-headers [`nng_http_set_header`]: /api/http.md#modifying-headers [`nng_http_del_header`]: /api/http.md#modifying-headers -[`nng_http_set_response_body`]: /TODO.md -[`nng_http_get_response_body`]: /TODO.md +[`nng_http_copy_body`]: /api/http.md#storing-body-content +[`nng_http_set_body`]: /api/http.md#storing-body-content +[`nng_http_get_body`]: /api/http.md#retrieving-body-content [`nng_http_read_response_body`]: /TODO.md [`nng_http_read_request_body`]: /TODO.md [`nng_http_server_set_error`]: /TODO.md @@ -352,6 +366,10 @@ [`NNG_OPT_IPC_PERMISSIONS`]: /tran/ipc.md#NNG_OPT_IPC_PERMISSIONS [`NNG_SOCKET_INITIALIZER`]: /api/sock.md#socket-structure [`NNG_CTX_INITIALIZER`]: /api/ctx.md#context-structure +[`NNG_PIPE_INITIALIZER`]: /api/pipe.md#initialization +[`NNG_PIPE_EV_ADD_PRE`]: /api/pipe.md#NNG_PIPE_EV_ADD_PRE +[`NNG_PIPE_EV_ADD_POST`]: /api/pipe.md#NNG_PIPE_EV_ADD_POST +[`NNG_PIPE_EV_REM_POST`]: /api/pipe.md#NNG_PIPE_EV_REM_POST <!-- Protocols --> @@ -378,7 +396,7 @@ [aio]: /api/aio.md [raw]: /api/sock.md#raw-mode-sockets -[pipe]: /TODO.md +[pipe]: /api/pipe.md [socket]: /TODO.md [context]: /TODO.md [dialer]: /TODO.md |