From ec7964e8fb970b2ea74393c5071464aad4fd9c06 Mon Sep 17 00:00:00 2001 From: Mike Jumper Date: Wed, 4 Jan 2023 12:05:02 -0800 Subject: [PATCH 1/3] GUACAMOLE-1538: Return number of bytes written for guac_terminal_write() and guac_terminal_printf(). --- src/terminal/terminal.c | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/terminal/terminal.c b/src/terminal/terminal.c index cb21e93f..52f90cda 100644 --- a/src/terminal/terminal.c +++ b/src/terminal/terminal.c @@ -852,14 +852,13 @@ void guac_terminal_commit_cursor(guac_terminal* term) { } -int guac_terminal_write(guac_terminal* term, const char* c, int size) { +int guac_terminal_write(guac_terminal* term, const char* buffer, int length) { guac_terminal_lock(term); - while (size > 0) { + for (int written = 0; written < length; written++) { /* Read and advance to next character */ - char current = *(c++); - size--; + char current = *(buffer++); /* Write character to typescript, if any */ if (term->typescript != NULL) @@ -872,7 +871,7 @@ int guac_terminal_write(guac_terminal* term, const char* c, int size) { guac_terminal_unlock(term); guac_terminal_notify(term); - return 0; + return length; } @@ -2104,4 +2103,4 @@ void guac_terminal_remove_user(guac_terminal* terminal, guac_user* user) { /* Remove the user from the terminal cursor */ guac_common_cursor_remove_user(terminal->cursor, user); -} \ No newline at end of file +} From d90e0e97fea7de0d9b671a540daed582c3164828 Mon Sep 17 00:00:00 2001 From: Mike Jumper Date: Wed, 4 Jan 2023 12:22:02 -0800 Subject: [PATCH 2/3] GUACAMOLE-1538: Add missing documentation for libguac-terminal functions. --- src/terminal/terminal/terminal.h | 78 +++++++++++++++++++++++++++++--- 1 file changed, 72 insertions(+), 6 deletions(-) diff --git a/src/terminal/terminal/terminal.h b/src/terminal/terminal/terminal.h index 47f4d623..678942cc 100644 --- a/src/terminal/terminal/terminal.h +++ b/src/terminal/terminal/terminal.h @@ -276,6 +276,9 @@ guac_terminal_options* guac_terminal_options_create( /** * Frees all resources associated with the given terminal. + * + * @param term + * The terminal to free. */ void guac_terminal_free(guac_terminal* term); @@ -298,7 +301,7 @@ void guac_terminal_set_upload_path_handler(guac_terminal* terminal, * @param terminal * The terminal to set the file download handler for. * - * @param upload_path_handler + * @param file_download_handler * The handler to be called whenever the necessary terminal codes are sent to * the given terminal to initiate a download of a given remote file. */ @@ -308,6 +311,13 @@ void guac_terminal_set_file_download_handler(guac_terminal* terminal, /** * Renders a single frame of terminal data. If data is not yet available, * this function will block until data is written. + * + * @param terminal + * The terminal that should be rendered. + * + * @return + * Zero if the frame was rendered successfully, non-zero if an error + * occurred. */ int guac_terminal_render_frame(guac_terminal* terminal); @@ -316,6 +326,19 @@ int guac_terminal_render_frame(guac_terminal* terminal); * supplied by calls to guac_terminal_send_key(), * guac_terminal_send_mouse(), and guac_terminal_send_stream(). If input is not * yet available, this function will block. + * + * @param terminal + * The terminal to read from. + * + * @param c + * The buffer that should receive the bytes read. + * + * @param size + * The number of bytes available within the buffer. + * + * @return + * The number of bytes read into the buffer, zero if end-of-file is reached + * (STDIN has been closed), or a negative value if an error occurs. */ int guac_terminal_read_stdin(guac_terminal* terminal, char* c, int size); @@ -377,8 +400,23 @@ char* guac_terminal_prompt(guac_terminal* terminal, const char* title, /** * Writes the given format string and arguments to this terminal's STDOUT in - * the same manner as printf(). This function may block until space is + * the same manner as printf(). The entire populated format string will always + * be written unless an error occurs. This function may block until space is * freed in the output buffer by guac_terminal_render_frame(). + * + * @param terminal + * The terminal to write to. + * + * @param format + * A printf-style format string describing the data to be written to + * STDOUT. + * + * @param ... + * Any arguments to use when filling the format string. + * + * @return + * The number of bytes written to STDOUT, or a negative value if an error + * occurs preventing the data from being written in its entirety. */ int guac_terminal_printf(guac_terminal* terminal, const char* format, ...); @@ -486,9 +524,24 @@ int guac_terminal_send_data(guac_terminal* term, const char* data, int length); int guac_terminal_send_string(guac_terminal* term, const char* data); /** - * Writes the given string of characters to the terminal. + * Writes the given buffer to the given terminal's STDOUT. All requested bytes + * will be written unless an error occurs. This function may block until space + * is freed in the output buffer by guac_terminal_render_frame(). + * + * @param term + * The terminal to write to. + * + * @param buffer + * A buffer containing the characters to be written to the terminal. + * + * @param length + * The number of bytes within the given string to write to the terminal. + * + * @return + * The number of bytes written to STDOUT, or a negative value if an error + * occurs preventing the data from being written in its entirety. */ -int guac_terminal_write(guac_terminal* term, const char* c, int size); +int guac_terminal_write(guac_terminal* term, const char* buffer, int length); /** * Initializes the handlers of the given guac_stream such that it serves as the @@ -532,7 +585,7 @@ int guac_terminal_send_stream(guac_terminal* term, guac_user* user, * STDIN. * * @param ... - * Any srguments to use when filling the format string. + * Any arguments to use when filling the format string. * * @return * The number of bytes written to STDIN, or a negative value if an error @@ -560,7 +613,20 @@ void guac_terminal_dup(guac_terminal* term, guac_user* user, guac_socket* socket); /** - * Resize the terminal to the given dimensions. + * Resize the client display and terminal to the given pixel dimensions. + * + * @param term + * The terminal to resize. + * + * @param width + * The new terminal width, in pixels. + * + * @param height + * The new terminal height, in pixels. + * + * @return + * Zero if the terminal was successfully resized to the given dimensions, + * non-zero otherwise. */ int guac_terminal_resize(guac_terminal* term, int width, int height); From 8ef60bfa9d3240b46bf7f640b3abf1a616267d28 Mon Sep 17 00:00:00 2001 From: Mike Jumper Date: Wed, 4 Jan 2023 12:40:21 -0800 Subject: [PATCH 3/3] GUACAMOLE-1538: Document parameters of libguac-terminal handlers. --- src/terminal/terminal/terminal-priv.h | 16 ++++++++++ src/terminal/terminal/terminal.h | 42 ++++++++++++++++++++------- 2 files changed, 47 insertions(+), 11 deletions(-) diff --git a/src/terminal/terminal/terminal-priv.h b/src/terminal/terminal/terminal-priv.h index 4fe85500..24cbfec9 100644 --- a/src/terminal/terminal/terminal-priv.h +++ b/src/terminal/terminal/terminal-priv.h @@ -29,6 +29,22 @@ #include "terminal.h" #include "typescript.h" +/** + * Handler for characters printed to the terminal. When a character is printed, + * the current char handler for the terminal is called and given that + * character. + * + * @param term + * The terminal receiving the character. + * + * @param c + * The received character. + * + * @return + * Zero if the character was handled successfully, non-zero otherwise. + */ +typedef int guac_terminal_char_handler(guac_terminal* term, unsigned char c); + struct guac_terminal { /** diff --git a/src/terminal/terminal/terminal.h b/src/terminal/terminal/terminal.h index 678942cc..082a3d23 100644 --- a/src/terminal/terminal/terminal.h +++ b/src/terminal/terminal/terminal.h @@ -141,19 +141,35 @@ typedef enum guac_terminal_cursor_type { } guac_terminal_cursor_type; /** - * Handler for characters printed to the terminal. When a character is printed, - * the current char handler for the terminal is called and given that - * character. - */ -typedef int guac_terminal_char_handler(guac_terminal* term, unsigned char c); - -/** - * Handler for setting the destination path for file uploads. + * Handler that is invoked whenever the necessary terminal codes are sent to + * to the given terminal to change the path for future file uploads. + * + * @param client + * The guac_client associated with the terminal receiving the upload path + * change terminal code. + * + * @param path + * The requested path. */ typedef void guac_terminal_upload_path_handler(guac_client* client, char* path); /** - * Handler for creating an outbound file download stream for a specified file. + * Handler that is invoked whenever the necessary terminal codes are sent to + * initiate a download of a given remote file. + * + * @param client + * The guac_client associated with the terminal receiving the file download + * terminal code. + * + * @param filename + * The name of the requested file. This may be a relative or absolute path, + * and it is up to the implementation to define how this value is + * interpreted. + * + * @return + * The file stream created for the file download, already configured to + * properly handle "ack" responses, etc. from the client, or NULL if the + * stream could not be created. */ typedef guac_stream* guac_terminal_file_download_handler(guac_client* client, char* filename); @@ -283,7 +299,9 @@ guac_terminal_options* guac_terminal_options_create( void guac_terminal_free(guac_terminal* term); /** - * Set the upload path handler for the given terminal. + * Sets the upload path handler for the given terminal. The upload path handler + * is invoked whenever the terminal codes requesting an upload path change are + * sent. * * @param terminal * The terminal to set the upload path handler for. @@ -296,7 +314,9 @@ void guac_terminal_set_upload_path_handler(guac_terminal* terminal, guac_terminal_upload_path_handler* upload_path_handler); /** - * Set the file download handler for the given terminal. + * Sets the file download handler for the given terminal. The file download + * handler is invoked whenever the terminal codes requesting download of a + * given remote file are sent. * * @param terminal * The terminal to set the file download handler for.