Standardize callbacks style and add documentation

6 files changed, 81 insertions, 45 deletions

diff --git a/include/libssh/callbacks.h b/include/libssh/callbacks.h
index fdd20a5b..19a4c461 100644
--- a/include/libssh/callbacks.h
+++ b/include/libssh/callbacks.h
@@ -32,21 +32,29 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
-typedef void (*ssh_callback_int) (void *user, int code);
+
+/** @internal
+ * @brief callback to process simple codes
+ * @param code value to transmit
+ * @param user Userdata to pass in callback
+ */
+typedef void (*ssh_callback_int) (int code, void *user);
+
 /** @internal
  * @brief callback for data received messages.
- * @param user user-supplied pointer sent along with all callback messages
  * @param data data retrieved from the socket or stream
  * @param len number of bytes available from this stream
+ * @param user user-supplied pointer sent along with all callback messages
  * @returns number of bytes processed by the callee. The remaining bytes will
  * be sent in the next callback message, when more data is available.
  */
-typedef int (*ssh_callback_data) (void *user, const void *data, size_t len);
+typedef int (*ssh_callback_data) (const void *data, size_t len, void *user);
+
 typedef void (*ssh_callback_int_int) (void *user, int code, int errno_code);
 
-typedef int (*ssh_message_callback) (ssh_session, void *user, ssh_message message);
-typedef int (*ssh_channel_callback_int) (ssh_channel channel, void *user, int code);
-typedef int (*ssh_channel_callback_data) (ssh_channel channel, void *user, int code, void *data, size_t len);
+typedef int (*ssh_message_callback) (ssh_session, ssh_message message, void *user);
+typedef int (*ssh_channel_callback_int) (ssh_channel channel, int code, void *user);
+typedef int (*ssh_channel_callback_data) (ssh_channel channel, int code, void *data, size_t len, void *user);
 /**
  * @brief SSH authentication callback.
  *
@@ -60,12 +68,26 @@ typedef int (*ssh_channel_callback_data) (ssh_channel channel, void *user, int c
  *
  * @return              0 on success, < 0 on error.
  */
+
 typedef int (*ssh_auth_callback) (const char *prompt, char *buf, size_t len,
     int echo, int verify, void *userdata);
+/**
+ * @brief SSH log callback. All logging messages will go through this callback
+ * @param session Current session handler
+ * @param priority Priority of the log, the smaller being the more important
+ * @param message the actual message
+ * @param userdata Userdata to be passed to the callback function.
+ */
 typedef void (*ssh_log_callback) (ssh_session session, int priority,
     const char *message, void *userdata);
-/** this callback will be called with status going from 0.0 to 1.0 during
- * connection */
+
+/**
+ * @brief SSH Connection status callback.
+ * @param session Current session handler
+ * @param status Percentage of connection status, going from 0.0 to 1.0
+ * once connection is done.
+ * @param userdata Userdata to be passed to the callback function.
+ */
 typedef void (*ssh_status_callback) (ssh_session session, float status,
 		void *userdata);
 
@@ -82,17 +104,10 @@ struct ssh_callbacks_struct {
 	 * of connection steps completed.
 	 */
   void (*connect_status_function)(void *userdata, float status);
-/* To be cleaned up */
-  ssh_callback_int connection_progress;
-  void *connection_progress_user;
-  ssh_channel_callback_int channel_write_confirm;
-  void *channel_write_confirm_user;
-  ssh_channel_callback_data channel_read_available;
-  void *channel_read_available_user;
 };
 typedef struct ssh_callbacks_struct *ssh_callbacks;
 
-/* This are the callbacks exported by the socket structure
+/** These are the callbacks exported by the socket structure
  * They are called by the socket module when a socket event appears
  */
 struct ssh_socket_callbacks_struct {
@@ -123,10 +138,34 @@ typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
 	(p)->size=sizeof(*(p)); \
 } while(0);
 
-/* These are the callback exported by the packet layer
+/** @brief Prototype for a packet callback, to be called when a new packet arrives
+ * @param session The current session of the packet
+ * @param type packet type (see ssh2.h)
+ * @param packet buffer containing the packet, excluding size, type and padding fields
+ * @param user user argument to the callback
  * and are called each time a packet shows up
- * */
-typedef int (*ssh_packet_callback) (ssh_session, void *user, uint8_t code, ssh_buffer packet);
+ * @returns SSH_PACKET_USED Packet was parsed and used
+ * @returns SSH_PACKET_NOT_USED Packet was not used or understood, processing must continue
+ */
+typedef int (*ssh_packet_callback) (ssh_session session, uint8_t type, ssh_buffer packet, void *user);
+
+/** return values for a ssh_packet_callback */
+/** Packet was used and should not be parsed by another callback */
+#define SSH_PACKET_USED 1
+/** Packet was not used and should be passed to any other callback
+ * available */
+#define SSH_PACKET_NOT_USED 2
+
+
+/** @brief This macro declares a packet callback handler
+ * @code
+ * SSH_PACKET_CALLBACK(mycallback){
+ * ...
+ * }
+ * @endcode
+ */
+#define SSH_PACKET_CALLBACK(name) \
+	int name (ssh_session session, uint8_t type, ssh_buffer packet, void *user)
 
 struct ssh_packet_callbacks_struct {
 	/** Index of the first packet type being handled */
@@ -138,6 +177,7 @@ struct ssh_packet_callbacks_struct {
 	void *user;
 };
 typedef struct ssh_packet_callbacks_struct *ssh_packet_callbacks;
+
 /**
  * @brief Set the callback functions.
  *
@@ -162,12 +202,6 @@ typedef struct ssh_packet_callbacks_struct *ssh_packet_callbacks;
  */
 LIBSSH_API int ssh_set_callbacks(ssh_session session, ssh_callbacks cb);
 
-/** return values for a ssh_packet_callback */
-/** Packet was used and should not be parsed by another callback */
-#define SSH_PACKET_USED 1
-/** Packet was not used and should be passed to any other callback
- * available */
-#define SSH_PACKET_NOT_USED 2
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/libssh/priv.h b/include/libssh/priv.h
index 8bce949e..90c700d5 100644
--- a/include/libssh/priv.h
+++ b/include/libssh/priv.h
@@ -120,8 +120,8 @@ void ssh_socket_set_callbacks(struct socket *s, ssh_socket_callbacks callbacks);
 int ssh_socket_pollcallback(struct ssh_poll_handle_struct *p, int fd, int revents, void *s);
 void ssh_socket_register_pollcallback(struct socket *s, struct ssh_poll_handle_struct *p);
 
-int ssh_packet_disconnect_callback(ssh_session session, void *user, u_int8_t type, ssh_buffer packet);
-int ssh_packet_ignore_callback(ssh_session session, void *user, u_int8_t type, ssh_buffer packet);
+SSH_PACKET_CALLBACK(ssh_packet_disconnect_callback);
+SSH_PACKET_CALLBACK(ssh_packet_ignore_callback);
 
 /* client.c */
 
@@ -143,7 +143,7 @@ unsigned char *packet_encrypt(ssh_session session,void *packet,unsigned int len)
  /* it returns the hmac buffer if exists*/
 int packet_hmac_verify(ssh_session session,ssh_buffer buffer,unsigned char *mac);
 
-int ssh_packet_socket_callback(void *user, const void *data, size_t len);
+int ssh_packet_socket_callback(const void *data, size_t len, void *user);
 void ssh_packet_register_socket_callback(ssh_session session, struct socket *s);
 void ssh_packet_set_callbacks(ssh_session session, ssh_packet_callbacks callbacks);
 void ssh_packet_set_default_callbacks(ssh_session session);
@@ -166,11 +166,12 @@ char **space_tokenize(const char *chain);
 int ssh_get_kex1(ssh_session session);
 char *ssh_find_matching(const char *in_d, const char *what_d);
 
-int channel_rcv_change_window(ssh_session session, void *user, uint8_t type, ssh_buffer packet);
-int channel_rcv_eof(ssh_session session, void *user, uint8_t type, ssh_buffer packet);
-int channel_rcv_close(ssh_session session, void *user, uint8_t type, ssh_buffer packet);
-int channel_rcv_request(ssh_session session, void *user, uint8_t type, ssh_buffer packet);
-int channel_rcv_data(ssh_session session, void *user, uint8_t type, ssh_buffer packet);
+SSH_PACKET_CALLBACK(channel_rcv_change_window);
+SSH_PACKET_CALLBACK(channel_rcv_eof);
+SSH_PACKET_CALLBACK(channel_rcv_close);
+SSH_PACKET_CALLBACK(channel_rcv_request);
+SSH_PACKET_CALLBACK(channel_rcv_data);
+
 /* in base64.c */
 ssh_buffer base64_to_bin(const char *source);
 unsigned char *bin_to_base64(const unsigned char *source, int len);
diff --git a/libssh/channels.c b/libssh/channels.c
index 8af3a037..afd17717 100644
--- a/libssh/channels.c
+++ b/libssh/channels.c
@@ -314,7 +314,7 @@ static ssh_channel channel_from_msg(ssh_session session) {
   return channel;
 }
 
-int channel_rcv_change_window(ssh_session session, void *user, u_int8_t type, ssh_buffer packet) {
+SSH_PACKET_CALLBACK(channel_rcv_change_window) {
   ssh_channel channel;
   uint32_t bytes;
   int rc;
@@ -351,7 +351,7 @@ int channel_rcv_change_window(ssh_session session, void *user, u_int8_t type, ss
 }
 
 /* is_stderr is set to 1 if the data are extended, ie stderr */
-int channel_rcv_data(ssh_session session, void *user, u_int8_t type, ssh_buffer packet) {
+SSH_PACKET_CALLBACK(channel_rcv_data){
   ssh_channel channel;
   ssh_string str;
   size_t len;
@@ -424,7 +424,7 @@ int channel_rcv_data(ssh_session session, void *user, u_int8_t type, ssh_buffer
   return SSH_PACKET_USED;
 }
 
-int channel_rcv_eof(ssh_session session, void *user, u_int8_t type, ssh_buffer packet) {
+SSH_PACKET_CALLBACK(channel_rcv_eof) {
   ssh_channel channel;
   (void)user;
   (void)type;
@@ -449,7 +449,7 @@ int channel_rcv_eof(ssh_session session, void *user, u_int8_t type, ssh_buffer p
   return SSH_PACKET_USED;
 }
 
-int channel_rcv_close(ssh_session session, void *user, u_int8_t type, ssh_buffer packet) {
+SSH_PACKET_CALLBACK(channel_rcv_close) {
 	ssh_channel channel;
 	(void)user;
 	(void)type;
@@ -491,7 +491,7 @@ int channel_rcv_close(ssh_session session, void *user, u_int8_t type, ssh_buffer
 	return SSH_PACKET_USED;
 }
 
-int channel_rcv_request(ssh_session session, void *user, u_int8_t type, ssh_buffer packet) {
+SSH_PACKET_CALLBACK(channel_rcv_request) {
 	ssh_channel channel;
 	ssh_string request_s;
 	char *request;
diff --git a/libssh/packet.c b/libssh/packet.c
index 0c023239..2a5f1b39 100644
--- a/libssh/packet.c
+++ b/libssh/packet.c
@@ -111,7 +111,7 @@ static int macsize=SHA_DIGEST_LEN;
  * @len length of data received. It might not be enough for a complete packet
  * @returns number of bytes read and processed.
  */
-int ssh_packet_socket_callback(void *user, const void *data, size_t receivedlen){
+int ssh_packet_socket_callback(const void *data, size_t receivedlen, void *user){
   ssh_session session=(ssh_session) user;
   unsigned int blocksize = (session->current_crypto ?
       session->current_crypto->in_cipher->blocksize : 8);
@@ -331,7 +331,7 @@ void ssh_packet_process(ssh_session session, u_int8_t type){
 			continue;
 		if(cb->callbacks[type - cb->start]==NULL)
 			continue;
-		r=cb->callbacks[type - cb->start](session,cb->user,type,session->in_buffer);
+		r=cb->callbacks[type - cb->start](session,type,session->in_buffer,cb->user);
 		if(r==SSH_PACKET_USED)
 			break;
 	}
diff --git a/libssh/session.c b/libssh/session.c
index ede83ebe..8145a3cf 100644
--- a/libssh/session.c
+++ b/libssh/session.c
@@ -369,7 +369,7 @@ int ssh_get_version(ssh_session session) {
  * @internal
  * @brief handles a SSH_DISCONNECT packet
  */
-int ssh_packet_disconnect_callback(ssh_session session, void *user, u_int8_t type, ssh_buffer packet){
+SSH_PACKET_CALLBACK(ssh_packet_disconnect_callback){
 	u_int32_t code;
 	char *error;
 	ssh_string error_s;
@@ -396,7 +396,7 @@ int ssh_packet_disconnect_callback(ssh_session session, void *user, u_int8_t typ
  * @internal
  * @brief handles a SSH_IGNORE and SSH_DEBUG packet
  */
-int ssh_packet_ignore_callback(ssh_session session, void *user, u_int8_t type, ssh_buffer packet){
+SSH_PACKET_CALLBACK(ssh_packet_ignore_callback){
 	(void)user;
 	(void)type;
 	(void)packet;
diff --git a/libssh/socket.c b/libssh/socket.c
index cb96e8da..8acc76ce 100644
--- a/libssh/socket.c
+++ b/libssh/socket.c
@@ -153,8 +153,9 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 			/* Bufferize the data and then call the callback */
 			buffer_add_data(s->in_buffer,buffer,r);
 			if(s->callbacks){
-				r= s->callbacks->data(s->callbacks->user,
-						buffer_get_rest(s->in_buffer), buffer_get_rest_len(s->in_buffer));
+				r= s->callbacks->data(buffer_get_rest(s->in_buffer),
+						buffer_get_rest_len(s->in_buffer),
+						s->callbacks->user);
 				buffer_pass_bytes(s->in_buffer,r);
 			}
 		}
@@ -167,7 +168,7 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 		          buffer_get_rest_len(s->out_buffer));
 		} else if(s->callbacks){
 			/* Otherwise advertise the upper level that write can be done */
-			s->callbacks->controlflow(s->callbacks->user,SSH_SOCKET_FLOW_WRITEWONTBLOCK);
+			s->callbacks->controlflow(SSH_SOCKET_FLOW_WRITEWONTBLOCK,s->callbacks->user);
 			ssh_poll_set_events(p,ssh_poll_get_events(p) & ~POLLOUT);
 			/* TODO: Find a way to put back POLLOUT when buffering occurs */
 		}