GUACAMOLE-1538: Document parameters of libguac-terminal handlers.

This commit is contained in:
Mike Jumper 2023-01-04 12:40:21 -08:00
parent d90e0e97fe
commit 8ef60bfa9d
2 changed files with 47 additions and 11 deletions

View File

@ -29,6 +29,22 @@
#include "terminal.h" #include "terminal.h"
#include "typescript.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 { struct guac_terminal {
/** /**

View File

@ -141,19 +141,35 @@ typedef enum guac_terminal_cursor_type {
} guac_terminal_cursor_type; } guac_terminal_cursor_type;
/** /**
* Handler for characters printed to the terminal. When a character is printed, * Handler that is invoked whenever the necessary terminal codes are sent to
* the current char handler for the terminal is called and given that * to the given terminal to change the path for future file uploads.
* character. *
*/ * @param client
typedef int guac_terminal_char_handler(guac_terminal* term, unsigned char c); * The guac_client associated with the terminal receiving the upload path
* change terminal code.
/** *
* Handler for setting the destination path for file uploads. * @param path
* The requested path.
*/ */
typedef void guac_terminal_upload_path_handler(guac_client* client, char* 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); 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); 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 * @param terminal
* The terminal to set the upload path handler for. * 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); 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 * @param terminal
* The terminal to set the file download handler for. * The terminal to set the file download handler for.