# nng_pipe_notify(3) Manual Page

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

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

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

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

## 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)