Documentation callbacks.h + standardization

include/libssh/callbacks.h

@@ -122,11 +122,27 @@ typedef struct ssh_callbacks_struct *ssh_callbacks;
  * They are called by the socket module when a socket event appears
  */
 struct ssh_socket_callbacks_struct {
+  /**
+   * User-provided data. User is free to set anything he wants here
+   */
+  void *userdata;
+	/**
+	 * This function will be called each time data appears on socket. The data
+	 * not consumed will appear on the next data event.
+	 */
   ssh_callback_data data;
+  /** This function will be called each time a controlflow state changes, i.e.
+   * the socket is available for reading or writing.
+   */
   ssh_callback_int controlflow;
+  /** This function will be called each time an exception appears on socket. An
+   * exception can be a socket problem (timeout, ...) or an end-of-file.
+   */
   ssh_callback_int_int exception;
+  /** This function is called when the ssh_socket_connect was used on the socket
+   * on nonblocking state, and the connection successed.
+   */
   ssh_callback_int_int connected;
-  void *user;
 };
 typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
 
@@ -186,8 +202,12 @@ struct ssh_packet_callbacks_struct {
 	uint8_t n_callbacks;
 	/** A pointer to n_callbacks packet callbacks */
 	ssh_packet_callback *callbacks;
+  /**
+   * User-provided data. User is free to set anything he wants here
+   */
 	void *user;
 };
+
 typedef struct ssh_packet_callbacks_struct *ssh_packet_callbacks;
 
 /**

libssh/client.c

@@ -647,7 +647,7 @@ int ssh_connect(ssh_session session) {
   session->socket_callbacks.connected=socket_callback_connected;
   session->socket_callbacks.data=callback_receive_banner;
   session->socket_callbacks.exception=socket_callback_exception;
-  session->socket_callbacks.user=session;
+  session->socket_callbacks.userdata=session;
   if (session->fd != -1) {
     ssh_socket_set_fd(session->socket, session->fd);
     ret=SSH_OK;

libssh/packet.c

@@ -289,7 +289,7 @@ void ssh_packet_register_socket_callback(ssh_session session, ssh_socket s){
 	session->socket_callbacks.connected=NULL;
 	session->socket_callbacks.controlflow=NULL;
 	session->socket_callbacks.exception=NULL;
-	session->socket_callbacks.user=session;
+	session->socket_callbacks.userdata=session;
 	ssh_socket_set_callbacks(s,&session->socket_callbacks);
 }
 

libssh/socket.c

@@ -150,7 +150,7 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 			s->fd=-1;
 			if(s->callbacks && s->callbacks->connected)
 				s->callbacks->connected(SSH_SOCKET_CONNECTED_ERROR,err,
-						s->callbacks->user);
+						s->callbacks->userdata);
 			return 0;
 		}
 		/* Then we are in a more standard kind of error */
@@ -166,7 +166,7 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 			if(s->callbacks && s->callbacks->exception){
 				s->callbacks->exception(
 						SSH_SOCKET_EXCEPTION_ERROR,
-						s->last_errno,s->callbacks->user);
+						s->last_errno,s->callbacks->userdata);
 			}
 		}
 		if(r==0){
@@ -174,7 +174,7 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 			if(s->callbacks && s->callbacks->exception){
 				s->callbacks->exception(
 						SSH_SOCKET_EXCEPTION_EOF,
-						0,s->callbacks->user);
+						0,s->callbacks->userdata);
 			}
 		}
 		if(r>0){
@@ -183,7 +183,7 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 			if(s->callbacks && s->callbacks->data){
 				r= s->callbacks->data(buffer_get_rest(s->in_buffer),
 						buffer_get_rest_len(s->in_buffer),
-						s->callbacks->user);
+						s->callbacks->userdata);
 				buffer_pass_bytes(s->in_buffer,r);
 			}
 		}
@@ -195,7 +195,7 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 			s->state = SSH_SOCKET_CONNECTED;
 			ssh_poll_set_events(p,POLLOUT | POLLIN | POLLERR);
 			if(s->callbacks && s->callbacks->connected)
-				s->callbacks->connected(SSH_SOCKET_CONNECTED_OK,0,s->callbacks->user);
+				s->callbacks->connected(SSH_SOCKET_CONNECTED_OK,0,s->callbacks->userdata);
 			return 0;
 		}
 		/* So, we can write data */
@@ -208,7 +208,7 @@ int ssh_socket_pollcallback(ssh_poll_handle p, int fd, int revents, void *v_s){
 				buffer_pass_bytes(s->out_buffer,w);
 		} else if(s->callbacks && s->callbacks->controlflow){
 			/* Otherwise advertise the upper level that write can be done */
-			s->callbacks->controlflow(SSH_SOCKET_FLOW_WRITEWONTBLOCK,s->callbacks->user);
+			s->callbacks->controlflow(SSH_SOCKET_FLOW_WRITEWONTBLOCK,s->callbacks->userdata);
 		}
 		ssh_poll_remove_events(p,POLLOUT);
 			/* TODO: Find a way to put back POLLOUT when buffering occurs */