1libssh2_session_callback_set(3) libssh2 libssh2_session_callback_set(3)
2
6 libssh2_session_callback_set - set a callback function
7
9 #include <libssh2.h>
10 void *
12 libssh2_session_callback_set(LIBSSH2_SESSION *session,
13 int cbtype, void *callback);
14
16 Sets a custom callback handler for a previously initialized session ob‐
17 ject. Callbacks are triggered by the receipt of special packets at the
18 Transport layer. To disable a callback, set it to NULL.
19 session - Session instance as returned by libssh2_session_init_ex(3)
21 cbtype - Callback type. One of the types listed in Callback Types.
23 callback - Pointer to custom callback function. The prototype for this
25 function must match the associated callback declaration macro.
26
28 LIBSSH2_CALLBACK_IGNORE
29 Called when a SSH_MSG_IGNORE message is received
30 LIBSSH2_CALLBACK_DEBUG
32 Called when a SSH_MSG_DEBUG message is received
33 LIBSSH2_CALLBACK_DISCONNECT
35 Called when a SSH_MSG_DISCONNECT message is received
36 LIBSSH2_CALLBACK_MACERROR
38 Called when a mismatched MAC has been detected in the transport
39 layer. If the function returns 0, the packet will be accepted
40 nonetheless.
41 LIBSSH2_CALLBACK_X11
43 Called when an X11 connection has been accepted
44 LIBSSH2_CALLBACK_SEND
46 Called when libssh2 wants to send data on the connection. Can
47 be set to a custom function to handle I/O your own way.
48 The prototype of the callback:
50 ssize_t sendcb(libssh2_socket_t sockfd, const void *buffer,
52 size_t length, int flags, void **abstract);
53 sockfd is the socket to write to, buffer points to the data to
55 send, length is the size of the data, flags is the flags that
56 would have been used to a send() call and abstract is a pointer
57 to the abstract pointer set in the libssh2_session_init_ex(3)
58 call.
59 The callback returns the number of bytes sent, or -1 for error.
61 The special return code -EAGAIN can be returned to signal that
62 the send was aborted to prevent getting blocked and it needs to
63 be called again.
64 LIBSSH2_CALLBACK_RECV
66 Called when libssh2 wants to read data from the connection. Can
67 be set to a custom function to handle I/O your own way.
68 The prototype of the callback:
70 ssize_t recvcb(libssh2_socket_t sockfd, void *buffer,
72 size_t length, int flags, void **abstract);
73 sockfd is the socket to read from, buffer where to store re‐
75 ceived data into, length is the size of the buffer, flags is the
76 flags that would have been used to a recv() call and abstract is
77 a pointer to the abstract pointer set in the libssh2_ses‐
78 sion_init_ex(3) call.
79 The callback returns the number of bytes read, or -1 for error.
81 The special return code -EAGAIN can be returned to signal that
82 the read was aborted to prevent getting blocked and it needs to
83 be called again.
84 LIBSSH2_CALLBACK_AUTHAGENT
86 Called during authentication process to allow the client to con‐
87 nect to the ssh-agent and perform any setup, such as configuring
88 the agent or adding keys.
89 The prototype of the callback:
91 void authagent(LIBSSH2_SESSION* session, LIBSSH2_CHANNEL *channel,
93 void **abstract);
94 LIBSSH2_CALLBACK_AUTHAGENT_IDENTITIES
96 Not called by libssh2. The client is responsible for calling
97 this method when a SSH2_AGENTC_REQUEST_IDENTITIES message has
98 been received.
99 The prototype of the callback:
101 void identities(LIBSSH2_SESSION* session, void *buffer,
103 const char *agent_path,
104 void **abstract)
105 buffer must be filled in by the callback. Different clients may
107 implement this differently. For example, one client may pass in
108 an unsigned char ** for this parameter, while another may pass
109 in a pointer to a struct.
110 Regardless of the type of buffer used, the client will need to
112 send back a list of identities in the following format.
113 uint32 buffer length uint32 number of entries entries
115 Where each entry in the entries list is of the format:
117 string data cstring comment
119 agent_path The path to a running ssh-agent on the client ma‐
121 chine, from which identities can be listed.
122 LIBSSH2_CALLBACK_AUTHAGENT_SIGN
124 Not called by libssh2. The client is responsible for calling
125 this method when a SSH2_AGENTC_SIGN_REQUEST message has been re‐
126 ceived.
127 The prototype of the callback:
129 void sign(LIBSSH2_SESSION* session,
131 unsigned char *blob, unsigned int blen,
132 const unsigned char *data, unsigned int dlen,
133 unsigned char **sig, unsigned int *sig_len,
134 const char *agent_path,
135 void **abstract);
136 When interfacing with an ssh-agent installed on the client sys‐
138 tem, this method can call libssh2_agent_sign(3) to perform sign‐
139 ing.
140
143 Pointer to previous callback handler. Returns NULL if no prior callback
144 handler was set or the callback type was unknown.
145
147 libssh2_session_init_ex(3) libssh2_agent_sign(3)
148libssh2 0.15 1 Jun 2007 libssh2_session_callback_set(3)