libssh2_session_callback_set.3 (5029B)
1.TH libssh2_session_callback_set 3 "1 Jun 2007" "libssh2 0.15" "libssh2" 2.SH NAME 3libssh2_session_callback_set - set a callback function 4.SH SYNOPSIS 5.nf 6#include <libssh2.h> 7 8void * 9libssh2_session_callback_set(LIBSSH2_SESSION *session, 10 int cbtype, void *callback); 11.fi 12.SH DESCRIPTION 13Sets a custom callback handler for a previously initialized session 14object. Callbacks are triggered by the receipt of special packets at the 15Transport layer. To disable a callback, set it to NULL. 16 17\fIsession\fP - Session instance as returned by 18.BR libssh2_session_init_ex(3) 19 20\fIcbtype\fP - Callback type. One of the types listed in Callback Types. 21 22\fIcallback\fP - Pointer to custom callback function. The prototype for 23this function must match the associated callback declaration macro. 24.SH CALLBACK TYPES 25.IP LIBSSH2_CALLBACK_IGNORE 26Called when a SSH_MSG_IGNORE message is received 27.IP LIBSSH2_CALLBACK_DEBUG 28Called when a SSH_MSG_DEBUG message is received 29.IP LIBSSH2_CALLBACK_DISCONNECT 30Called when a SSH_MSG_DISCONNECT message is received 31.IP LIBSSH2_CALLBACK_MACERROR 32Called when a mismatched MAC has been detected in the transport layer. If the 33function returns 0, the packet will be accepted nonetheless. 34.IP LIBSSH2_CALLBACK_X11 35Called when an X11 connection has been accepted 36.IP LIBSSH2_CALLBACK_SEND 37Called when libssh2 wants to send data on the connection. Can be set to a 38custom function to handle I/O your own way. 39 40The prototype of the callback: 41 42.nf 43ssize_t sendcb(libssh2_socket_t sockfd, const void *buffer, 44 size_t length, int flags, void **abstract); 45.fi 46 47\fBsockfd\fP is the socket to write to, \fBbuffer\fP points to the data to 48send, \fBlength\fP is the size of the data, \fBflags\fP is the flags that 49would have been used to a \fIsend()\fP call and \fBabstract\fP is a pointer 50to the abstract pointer set in the \fIlibssh2_session_init_ex(3)\fP call. 51 52The callback returns the number of bytes sent, or -1 for error. The special 53return code \fB-EAGAIN\fP can be returned to signal that the send was aborted 54to prevent getting blocked and it needs to be called again. 55.IP LIBSSH2_CALLBACK_RECV 56Called when libssh2 wants to read data from the connection. Can be set to a 57custom function to handle I/O your own way. 58 59The prototype of the callback: 60 61.nf 62ssize_t recvcb(libssh2_socket_t sockfd, void *buffer, 63 size_t length, int flags, void **abstract); 64.fi 65 66\fBsockfd\fP is the socket to read from, \fBbuffer\fP where to store received 67data into, \fBlength\fP is the size of the buffer, \fBflags\fP is the flags 68that would have been used to a \fIrecv()\fP call and \fBabstract\fP is a pointer 69to the abstract pointer set in the \fIlibssh2_session_init_ex(3)\fP call. 70 71The callback returns the number of bytes read, or -1 for error. The special 72return code \fB-EAGAIN\fP can be returned to signal that the read was aborted 73to prevent getting blocked and it needs to be called again. 74.IP LIBSSH2_CALLBACK_AUTHAGENT 75Called during authentication process to allow the client to connect to the 76ssh-agent and perform any setup, such as configuring the agent or adding keys. 77 78The prototype of the callback: 79 80.nf 81void authagent(LIBSSH2_SESSION* session, LIBSSH2_CHANNEL *channel, 82 void **abstract); 83.fi 84.IP LIBSSH2_CALLBACK_AUTHAGENT_IDENTITIES 85Not called by libssh2. The client is responsible for calling this method when 86a SSH2_AGENTC_REQUEST_IDENTITIES message has been received. 87 88The prototype of the callback: 89 90.nf 91void identities(LIBSSH2_SESSION* session, void *buffer, 92 const char *agent_path, 93 void **abstract) 94.fi 95 96\fBbuffer\fP must be filled in by the callback. Different clients may implement 97this differently. For example, one client may pass in an unsigned char ** for 98this parameter, while another may pass in a pointer to a struct. 99 100Regardless of the type of buffer used, the client will need to send back a list 101of identities in the following format. 102 103uint32 buffer length 104uint32 number of entries 105entries 106 107Where each entry in the entries list is of the format: 108 109string data 110cstring comment 111 112\fBagent_path\fP The path to a running ssh-agent on the client machine, from 113which identities can be listed. 114.IP LIBSSH2_CALLBACK_AUTHAGENT_SIGN 115Not called by libssh2. The client is responsible for calling this method when 116a SSH2_AGENTC_SIGN_REQUEST message has been received. 117 118The prototype of the callback: 119 120.nf 121void sign(LIBSSH2_SESSION* session, 122 unsigned char *blob, unsigned int blen, 123 const unsigned char *data, unsigned int dlen, 124 unsigned char **sig, unsigned int *sig_len, 125 const char *agent_path, 126 void **abstract); 127.fi 128 129When interfacing with an ssh-agent installed on the client system, this method 130can call libssh2_agent_sign(3) to perform signing. 131 132.SH RETURN VALUE 133Pointer to previous callback handler. Returns NULL if no prior callback 134handler was set or the callback type was unknown. 135.SH SEE ALSO 136.BR libssh2_session_init_ex(3) 137.BR libssh2_agent_sign(3)