From 159dc95695515db767e208c41d5f44b334b71adc Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 2 May 2018 16:01:22 -0700 Subject: fixes #389 Need pipe notification callbacks This adds a new pipe event notification API (callbacks called on either pipe add or remove), including both tests and docs. Also supporting APIs to get the socket or endpoint associated with a pipe are included (tested and documented as well.) --- docs/man/libnng.3.adoc | 4 +++ docs/man/nng_pipe.5.adoc | 3 ++ docs/man/nng_pipe_dialer.3.adoc | 46 +++++++++++++++++++++++++ docs/man/nng_pipe_listener.3.adoc | 46 +++++++++++++++++++++++++ docs/man/nng_pipe_notify.3.adoc | 71 +++++++++++++++++++++++++++++++++++++++ docs/man/nng_pipe_socket.3.adoc | 45 +++++++++++++++++++++++++ 6 files changed, 215 insertions(+) create mode 100644 docs/man/nng_pipe_dialer.3.adoc create mode 100644 docs/man/nng_pipe_listener.3.adoc create mode 100644 docs/man/nng_pipe_notify.3.adoc create mode 100644 docs/man/nng_pipe_socket.3.adoc (limited to 'docs') diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 61ceacc7..1164b613 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -73,8 +73,12 @@ Listeners accept incoming connection requets, and dialers make them. |<>|set listener option |<>|start listener |<>|close pipe +|<>|return dialer that created pipe |<>|get pipe option |<>|get numeric pipe identifier +|<>|return listener that created pipe +|<>|register pipe notification callback +|<>|return owning socket for pipe |=== === Message Handling Functions diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc index a777c0d0..cf11c047 100644 --- a/docs/man/nng_pipe.5.adoc +++ b/docs/man/nng_pipe.5.adoc @@ -69,7 +69,10 @@ nng_pipe p = NNG_PIPE_INITIALIZER; <>, <>, <>, +<>, <>, +<>, +<>, <>, <>, <>, diff --git a/docs/man/nng_pipe_dialer.3.adoc b/docs/man/nng_pipe_dialer.3.adoc new file mode 100644 index 00000000..476ab1be --- /dev/null +++ b/docs/man/nng_pipe_dialer.3.adoc @@ -0,0 +1,46 @@ += nng_pipe_dialer(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_pipe_dialer - return dialer that created pipe + +== SYNOPSIS + +[source, c] +---- +#include + +nng_dialer nng_pipe_dialer(nng_pipe p); +---- + +== DESCRIPTION + +The `nng_pipe_dialer()` function returns the `<>` +that created the pipe _p_. +If the pipe was not created by a dialer, then the returned value will +have an identifier (`<>`) of `-1`. + +== RETURN VALUES + +This function returns the dialer that created the pipe, unless it was +not created by a dialer, in which case a value initialized with +`NNG_DIALER_INITIALIZER` will be returned. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<> diff --git a/docs/man/nng_pipe_listener.3.adoc b/docs/man/nng_pipe_listener.3.adoc new file mode 100644 index 00000000..3b7db4d6 --- /dev/null +++ b/docs/man/nng_pipe_listener.3.adoc @@ -0,0 +1,46 @@ += nng_pipe_listener(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_pipe_listener - return listener that created pipe + +== SYNOPSIS + +[source, c] +---- +#include + +nng_listener nng_pipe_listener(nng_pipe p); +---- + +== DESCRIPTION + +The `nng_pipe_listener()` function returns the `<>` +that created the pipe _p_. +If the pipe was not created by a listener, then the returned value will +have an identifier (`<>`) of `-1`. + +== RETURN VALUES + +This function returns the listener that created the pipe, unless it was +not created by a listener, in which case a value initialized with +`NNG_LISTENER_INITIALIZER` will be returned. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<> diff --git a/docs/man/nng_pipe_notify.3.adoc b/docs/man/nng_pipe_notify.3.adoc new file mode 100644 index 00000000..34b640c8 --- /dev/null +++ b/docs/man/nng_pipe_notify.3.adoc @@ -0,0 +1,71 @@ += nng_pipe_notify(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_pipe_notify - register pipe notification callback + +== SYNOPSIS + +[source, c] +---- +#include + +typedef enum { + NNG_PIPE_ADD, + NNG_PIPE_REM, +} nng_pipe_action; + +typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_action, void *); + +int nng_pipe_notify(nng_socket s, nng_pipe_cb cb, void *arg); +---- + +== DESCRIPTION + +The `nng_pipe_notify()` function registers the callback function _cb_ +to be called whenever a <> is added to or removed from the +socket _s_. + +The function _cb_ will be called with the action `NNG_PIPE_ADD` just before +a pipe is added to the socket (as a result of a connection being established). +The final argument passed will be the argument _arg_ that was specified when +the function was registered. + +The function _cb_ will also be called with the action `NNG_PIPE_REM` when +the pipe is being removed from the socket for any reason. +This will also use the same argument _arg_. + +NOTE: Only one callback can be registered for a given socket. +Subsequent calls to `nng_pipe_notify()` on the same socket will overwrite +any prior registration. + +TIP: The callback _cb_ may reject a pipe for any reason by simply closing +it using `<>`. +This might be done, for example, if the remote peer is not authorized to +access this session, based on values determined with the aid of +`<>`. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: The socket _s_ does not refer to an open socket. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_pipe_socket.3.adoc b/docs/man/nng_pipe_socket.3.adoc new file mode 100644 index 00000000..f2d02aa3 --- /dev/null +++ b/docs/man/nng_pipe_socket.3.adoc @@ -0,0 +1,45 @@ += nng_pipe_socket(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_pipe_socket - return owning socket for pipe + +== SYNOPSIS + +[source, c] +---- +#include + +nng_socket nng_pipe_socket(nng_pipe p); +---- + +== DESCRIPTION + +The `nng_pipe_socket()` function returns the `<>` +that owns the pipe _p_. + +NOTE: The returned socket may be closed or in the process of closing, in +which case it will not be usable with other functions. + +== RETURN VALUES + +This function returns the socket that "`owns`" the pipe. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<> -- cgit v1.2.3-70-g09d2