NAME

       nng_pipe_notify - register pipe notification callback

SYNOPSIS

           #include <nng/nng.h>

           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 *);

           int nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg);

DESCRIPTION

       The nng_pipe_notify() function registers the callback function cb 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.

       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:

       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.

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

       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

       nng_pipe_close(3), nng_pipe_getopt(3), nng_pipe(5), nng_socket(5), nng(7)

                                                   2025-02-02                                 NNG_PIPE_NOTIFY(3)