1 files changed, 37 insertions, 22 deletions
diff --git a/docs/man/nng_pipe_notify.3.adoc b/docs/man/nng_pipe_notify.3.adoc
index 34b640c8..0a8785e3 100644
--- a/docs/man/nng_pipe_notify.3.adoc
+++ b/docs/man/nng_pipe_notify.3.adoc
@@ -19,40 +19,55 @@ nng_pipe_notify - register pipe notification callback
 ----
 #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);
 ----
 
 == DESCRIPTION
 
 The `nng_pipe_notify()` function registers the callback function _cb_
-to be called whenever a <<nng_pipe.5#,pipe>> is added to or removed from the
-socket _s_.
+to be called whenever a <<nng_pipe.5#,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:
 
-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.
+`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.3#,nng_pipe_close()>>`) at
+this point, the socket will never see the pipe, and no further events will
+occur for the given pipe.
 
-TIP: The callback _cb_ may reject a pipe for any reason by simply closing
+`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.
+
+TIP: The callback _cb_ may close a pipe for any reason by simply closing
 it using `<<nng_pipe_close.3#,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.3#,nng_pipe_getopt()>>`.
+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.
+
+TIP: It is possible to register the same _cb_ and _arg_ for different events
+by calling this function separately for different values of _ev_.
+
+NOTE: This function ignores invalid values for _ev_.
 
 == RETURN VALUES