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);