GUACAMOLE-1538: Merge add missing documentation for libguac-terminal.

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++);
+        char current = *(buffer++);
-        size--;
 
         /* 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);
-}
+}

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 {
 
     /**

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,
+ * 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);
 
 /**
- * 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);
 
@@ -276,11 +292,16 @@ 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);
 
 /**
- * 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.
@@ -293,12 +314,14 @@ 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.
  *
- * @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 +331,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 +346,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 +420,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 +544,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 +605,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 +633,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);