NAME

       libssh2_session_callback_set - set a callback function

SYNOPSIS

       #include <libssh2.h>

       void *libssh2_session_callback_set(LIBSSH2_SESSION *session,
                                          int cbtype, void *callback);

DESCRIPTION

       Sets  a custom callback handler for a previously initialized session object. Callbacks are
       triggered by the receipt of special packets at the Transport layer. To disable a callback,
       set it to NULL.

       session - Session instance as returned by libssh2_session_init_ex(3)

       cbtype - Callback type. One of the types listed in Callback Types.

       callback - Pointer to custom callback function. The prototype for this function must match
       the associated callback declaration macro.

CALLBACK TYPES

       LIBSSH2_CALLBACK_IGNORE
              Called when a SSH_MSG_IGNORE message is received

       LIBSSH2_CALLBACK_DEBUG
              Called when a SSH_MSG_DEBUG message is received

       LIBSSH2_CALLBACK_DISCONNECT
              Called when a SSH_MSG_DISCONNECT message is received

       LIBSSH2_CALLBACK_MACERROR
              Called when a mismatched MAC has been detected  in  the  transport  layer.  If  the
              function returns 0, the packet will be accepted nonetheless.

       LIBSSH2_CALLBACK_X11
              Called when an X11 connection has been accepted

       LIBSSH2_CALLBACK_SEND
              Called  when  libssh2 wants to send data on the connection.  Can be set to a custom
              function to handle I/O your own way.

              The prototype of the callback:

              ssize_t sendcb(libssh2_socket_t sockfd, const void *buffer,
                             size_t length, int flags, void **abstract);

              sockfd is the socket to write to, buffer points to the data to send, length is  the
              size  of  the data, flags is the flags that would've been used to a send() call and
              abstract is a pointer to the abstract pointer set in the libssh2_session_init_ex(3)
              call.

              The  callback returns the number of bytes sent, or -1 for error. The special return
              code -EAGAIN can be returned to signal that the send was aborted to prevent getting
              blocked and it needs to be called again.

       LIBSSH2_CALLBACK_RECV
              Called  when libssh2 wants to read data from the connection. Can be set to a custom
              function to handle I/O your own way.

              The prototype of the callback:

              ssize_t recvcb(libssh2_socket_t sockfd, void *buffer,
                             size_t length, int flags, void **abstract);

              sockfd is the socket to read from, buffer where to store received data into, length
              is  the  size of the buffer, flags is the flags that would've been used to a recv()
              call  and  abstract  is  a  pointer  to   the   abstract   pointer   set   in   the
              libssh2_session_init_ex(3) call.

              The  callback returns the number of bytes read, or -1 for error. The special return
              code -EAGAIN can be returned to signal that the read was aborted to prevent getting
              blocked and it needs to be called again.

RETURN VALUE

       Pointer to previous callback handler. Returns NULL if no prior callback handler was set or
       the callback type was unknown.

SEE ALSO

       libssh2_session_init_ex(3)