From 764aa7e062961eaf4fb2a160e119e70868d431a5 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 17 May 2018 21:58:21 -0700 Subject: man page updates for tip --- man/tip/nng_bus.7.html | 14 ++++++- man/tip/nng_pipe_notify.3.html | 85 +++++++++++++++++++++++++++++------------- man/tip/nng_tcp.7.html | 45 ++++++++++++++++++++++ man/tip/nng_tls.7.html | 45 ++++++++++++++++++++++ 4 files changed, 163 insertions(+), 26 deletions(-) diff --git a/man/tip/nng_bus.7.html b/man/tip/nng_bus.7.html index 0c643e84..464e74ae 100644 --- a/man/tip/nng_bus.7.html +++ b/man/tip/nng_bus.7.html @@ -609,7 +609,19 @@ Sending messages will attempt to deliver to each directly connected peer.

Protocol Headers

-

The bus protocol has no protocol-specific headers.

+

When using a “raw” bus socket, received messages will +contain the incoming pipe ID as the sole element in the header. +If a message containing such a header is sent using a raw bus socket, then, +the message will be delivered to all connected pipes except the one +identified in the header. +This behavior is intended for use with device +configurations consisting of just a single socket. +Such configurations are useful in the creation of rebroadcasters, and this +capaibility prevents a message from being routed back to its source. +If no header is present, then a message is sent to all connected pipes.

+
+
+

When using “cooked” bus sockets, no message headers are present.

diff --git a/man/tip/nng_pipe_notify.3.html b/man/tip/nng_pipe_notify.3.html index 9c22bbdd..443b7ed9 100644 --- a/man/tip/nng_pipe_notify.3.html +++ b/man/tip/nng_pipe_notify.3.html @@ -527,14 +527,15 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
#include <nng/nng.h>
 
-typedef enum {
-        NNG_PIPE_ADD,
-        NNG_PIPE_REM,
-} nng_pipe_action;
+enum {
+        NNG_PIPE_EV_ADD_PRE,
+        NNG_PIPE_EV_ADD_POST,
+        NNG_PIPE_EV_REM_POST,
+};
 
-typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_action, void *);
+typedef void (*nng_pipe_cb)(nng_pipe, int, void *);
 
-int nng_pipe_notify(nng_socket s, nng_pipe_cb cb, void *arg);
+int nng_pipe_notify(nng_socket s, int ev, nng_pipe_cb cb, void *arg);
@@ -544,30 +545,55 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

The nng_pipe_notify() function registers the callback function cb -to be called whenever a pipe is added to or removed from the -socket s.

+to be called whenever a pipe the pipe event specified by +ev occurs on the socket s. +The callback cb will be passed arg as its final argument.

-

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.

+

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 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.

+

The following pipe events are supported:

-
+
+
+
NNG_PIPE_EV_ADD_PRE
+
+

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.

+
+
NNG_PIPE_EV_ADD_POST
+
+

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.

+
+
NNG_PIPE_EV_REM_POST
+
+

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.

+
+
+
+
- + -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. +The callback cb may close a pipe for any reason by simply closing +it using nng_pipe_close(). +This might be done before the pipe is added to the socket (during +NNG_PIPE_EV_ADD_PRE), for example, if the remote peer is not authorized.
@@ -579,11 +605,20 @@ any prior registration. -The callback cb may reject a pipe for any reason by simply closing -it using nng_pipe_close(). -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 -nng_pipe_getopt(). +It is possible to register the same cb and arg for different events +by calling this function separately for different values of ev. + + + +
+
+ + + +
+ + +This function ignores invalid values for ev.
diff --git a/man/tip/nng_tcp.7.html b/man/tip/nng_tcp.7.html index a1f31e2e..ee7185fc 100644 --- a/man/tip/nng_tcp.7.html +++ b/man/tip/nng_tcp.7.html @@ -564,6 +564,51 @@ For example, to contact port 80 on the localhost either of the following URIs could be used: tcp://127.0.0.1:80 or tcp://localhost:80.

+

A URI may be restricted to IPv6 using the scheme tcp6://, and may +be restricted to IPv4 using the scheme tcp4://.

+
+
+ + + + + +
+ + +Specifying tcp6:// may not prevent IPv4 hosts from being used with +IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +listeners. +The details of varies across operating systems. +
+
+
+ + + + + +
+ + +Both tcp6:// and tcp4:// are nng extensions, and will not +be understood by other implementations such as libnanomsg. +
+
+
+ + + + + +
+ + +We recommend using either numeric IP addresses, or names that are +specific to either IPv4 or IPv6 to prevent confusion and surprises. +
+
+

When specifying IPv6 addresses, the address must be enclosed in square brackets ([]) to avoid confusion with the final colon separating the port.

diff --git a/man/tip/nng_tls.7.html b/man/tip/nng_tls.7.html index b91bd66f..70669dd0 100644 --- a/man/tip/nng_tls.7.html +++ b/man/tip/nng_tls.7.html @@ -612,6 +612,51 @@ either of the following URIs could be used: tls+tcp://127.0.0.1:4433tls+tcp://localhost:4433.

+

A URI may be restricted to IPv6 using the scheme tls+tcp6://, and may +be restricted to IPv4 using the scheme tls+tcp4://.

+
+
+ + + + + +
+ + +Specifying tls+tcp6:// may not prevent IPv4 hosts from being used with +IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +listeners. +The details of varies across operating systems. +
+
+
+ + + + + +
+ + +Both tls+tcp6:// and tls+tcp4:// are nng extensions, and will not +be understood by other implementations such as mangos. +
+
+
+ + + + + +
+ + +We recommend using either numeric IP addresses, or names that are +specific to either IPv4 or IPv6 to prevent confusion and surprises. +
+
+

When specifying IPv6 addresses, the address must be enclosed in square brackets ([]) to avoid confusion with the final colon separating the port.

-- cgit v1.2.3-70-g09d2