GUACAMOLE-1538: Add missing documentation for libguac-terminal functions.

This commit is contained in:
Mike Jumper 2023-01-04 12:22:02 -08:00
parent ec7964e8fb
commit d90e0e97fe

View File

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