From cb8fe46328273e64aa161c501b5733eac8469aa8 Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Wed, 2 Mar 2016 14:36:16 -0800 Subject: [PATCH] GUAC-1389: Add missing documentation for connection handling functions. --- src/guacd/connection.c | 62 ++++++++++++++++++++++++++++++++++++++++-- src/guacd/connection.h | 32 ++++++++++++++++++++-- 2 files changed, 88 insertions(+), 6 deletions(-) diff --git a/src/guacd/connection.c b/src/guacd/connection.c index c8cb1a17..2e4f4b84 100644 --- a/src/guacd/connection.c +++ b/src/guacd/connection.c @@ -51,6 +51,20 @@ * Behaves exactly as write(), but writes as much as possible, returning * successfully only if the entire buffer was written. If the write fails for * any reason, a negative value is returned. + * + * @param fd + * The file descriptor to write to. + * + * @param buffer + * The buffer containing the data to be written. + * + * @param length + * The number of bytes in the buffer to write. + * + * @return + * The number of bytes written, or -1 if an error occurs. As this function + * is guaranteed to write ALL bytes, this will always be the number of + * bytes specified by length unless an error occurs. */ static int __write_all(int fd, char* buffer, int length) { @@ -72,7 +86,22 @@ static int __write_all(int fd, char* buffer, int length) { /** * Continuously reads from a guac_socket, writing all data read to a file - * descriptor. + * descriptor. Any data already buffered from that guac_socket by a given + * guac_parser is read first, prior to reading further data from the + * guac_socket. The provided guac_parser will be freed once its buffers have + * been emptied, but the guac_socket will not. + * + * This thread ultimately terminates when no further data can be read from the + * guac_socket. + * + * @param data + * A pointer to a guacd_connection_io_thread_params structure containing + * the guac_socket to read from, the file descriptor to write the read data + * to, and the guac_parser associated with the guac_socket which may have + * unhandled data in its parsing buffers. + * + * @return + * Always NULL. */ static void* guacd_connection_write_thread(void* data) { @@ -81,6 +110,7 @@ static void* guacd_connection_write_thread(void* data) { int length; + /* Read all buffered data from parser first */ while ((length = guac_parser_shift(params->parser, buffer, sizeof(buffer))) > 0) { if (__write_all(params->fd, buffer, length) < 0) break; @@ -136,6 +166,20 @@ void* guacd_connection_io_thread(void* data) { * * If adding the user fails for any reason, non-zero is returned. Zero is * returned upon success. + * + * @param proc + * The existing process to add the user to. + * + * @param parser + * The parser associated with the given guac_socket (used to handle the + * user's connection handshake thus far). + * + * @param socket + * The socket associated with the user to be added to the existing + * process. + * + * @return + * Zero if the user was added successfully, non-zero if an error occurred. */ static int guacd_add_user(guacd_proc* proc, guac_parser* parser, guac_socket* socket) { @@ -175,11 +219,23 @@ static int guacd_add_user(guacd_proc* proc, guac_parser* parser, guac_socket* so /** * Routes the connection on the given socket according to the Guacamole - * protocol on the given socket, adding new users and creating new client - * processes as needed. + * protocol, adding new users and creating new client processes as needed. If a + * new process is created, this function blocks until that process terminates, + * automatically deregistering the process at that point. * * The socket provided will be automatically freed when the connection * terminates unless routing fails, in which case non-zero is returned. + * + * @param map + * The map of existing client processes. + * + * @param socket + * The socket associated with the new connection that must be routed to + * a new or existing process within the given map. + * + * @return + * Zero if the connection was successfully routed, non-zero if routing has + * failed. */ static int guacd_route_connection(guacd_proc_map* map, guac_socket* socket) { diff --git a/src/guacd/connection.h b/src/guacd/connection.h index 1797d951..5a0c9d2f 100644 --- a/src/guacd/connection.h +++ b/src/guacd/connection.h @@ -58,8 +58,22 @@ typedef struct guacd_connection_thread_params { /** * Handles an inbound connection to guacd, allowing guacd to continue listening - * for other connections. It is expected that this thread will operate - * detached. The creating process need not join on the resulting thread. + * for other connections. The file descriptor of the inbound connection will + * either be given to a new process for a new remote desktop connection, or + * will be passed to an existing process for joining an existing remote desktop + * connection. It is expected that this thread will operate detached. The + * creating process need not join on the resulting thread. + * + * @param data + * A pointer to a guacd_connection_thread_params structure containing the + * shared overall map of currently-connected processes, the file + * descriptor associated with the newly-established connection that is to + * be either (1) associated with a new process or (2) passed on to an + * existing process, and the SSL context for the encryption surrounding + * that connection (if any). + * + * @return + * Always NULL. */ void* guacd_connection_thread(void* data); @@ -91,7 +105,19 @@ typedef struct guacd_connection_io_thread_params { /** * Transfers data back and forth between the guacd-side guac_socket and the - * file descriptor used by the process-side guac_socket. + * file descriptor used by the process-side guac_socket. Note that both the + * provided guac_parser and the guac_socket will be freed once this thread + * terminates, which will occur when no further data can be read from the + * guac_socket. + * + * @param data + * A pointer to a guacd_connection_io_thread_params structure containing + * the guac_socket and file descriptor to transfer data between + * (bidirectionally), as well as the guac_parser associated with the + * guac_socket (which may have unhandled data in its parsing buffers). + * + * @return + * Always NULL. */ void* guacd_connection_io_thread(void* data);