libssh2_session_callback_set(3) libssh2 libssh2_session_callback_set(3)

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

LIBSSH2_CALLBACK_AUTHAGENT
Called during authentication process to allow the client to
connect to the ssh-agent and perform any setup, such as
configuring the agent or adding keys.

The prototype of the callback:

void authagent(LIBSSH2_SESSION* session, LIBSSH2_CHANNEL *channel,
void **abstract);

LIBSSH2_CALLBACK_AUTHAGENT_IDENTITIES
Not called by libssh2. The client is responsible for calling
this method when a SSH2_AGENTC_REQUEST_IDENTITIES message has
been received.

The prototype of the callback:

void identities(LIBSSH2_SESSION* session, void *buffer,
const char *agent_path,
void **abstract)

buffer must be filled in by the callback. Different clients
may implement this differently. For example, one client may
pass in an unsigned char ** for this parameter, while another
may pass in a pointer to a struct.

Regardless of the type of buffer used, the client will need to
send back a list of identities in the following format.

uint32 buffer length uint32 number of entries entries

Where each entry in the entries list is of the format:

string data cstring comment

agent_path The path to a running ssh-agent on the client
machine, from which identities can be listed.

LIBSSH2_CALLBACK_AUTHAGENT_SIGN
Not called by libssh2. The client is responsible for calling
this method when a SSH2_AGENTC_SIGN_REQUEST message has been
received.

The prototype of the callback:

void sign(LIBSSH2_SESSION* session,
unsigned char *blob, unsigned int blen,
const unsigned char *data, unsigned int dlen,
unsigned char **sig, unsigned int *sig_len,
const char *agent_path,
void **abstract);

When interfacing with an ssh-agent installed on the client
system, this method can call libssh2_agent_sign(3) to perform
signing.

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) libssh2_agent_sign(3)

libssh2 0.15 1 Jun 2007 libssh2_session_callback_set(3)