libguac-terminal 1.5.5
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
terminal.h File Reference

Constants, structures, and function definitions defining the core functionality for the terminal library. More...

Go to the source code of this file.

Data Structures

struct  guac_terminal_options
 Configuration options that may be passed when creating a new guac_terminal. More...
 

Macros

#define GUAC_TERMINAL_DEFAULT_FONT_NAME   "monospace"
 The name of the font to use for the terminal if no name is specified.
 
#define GUAC_TERMINAL_DEFAULT_FONT_SIZE   12
 The size of the font to use for the terminal if no font size is specified, in points.
 
#define GUAC_TERMINAL_DEFAULT_MAX_SCROLLBACK   1000
 The default maximum scrollback size in rows.
 
#define GUAC_TERMINAL_DEFAULT_BACKSPACE   127
 The default ASCII code to use for the backspace key.
 
#define GUAC_TERMINAL_DEFAULT_COLOR_SCHEME   ""
 The default (unset) color scheme.
 
#define GUAC_TERMINAL_DEFAULT_DISABLE_COPY   false
 The default value for the "disable copy" flag; by default copying is enabled.
 
#define GUAC_TERMINAL_MAX_ROWS   1024
 The absolute maximum number of rows to allow within the display.
 
#define GUAC_TERMINAL_MAX_COLUMNS   1024
 The absolute maximum number of columns to allow within the display.
 
#define GUAC_TERMINAL_FRAME_DURATION   40
 The maximum duration of a single frame, in milliseconds.
 
#define GUAC_TERMINAL_FRAME_TIMEOUT   10
 The maximum amount of time to wait for more data before declaring a frame complete, in milliseconds.
 
#define GUAC_TERMINAL_MAX_TABS   16
 The maximum number of custom tab stops.
 
#define GUAC_TERMINAL_WHEEL_SCROLL_AMOUNT   3
 The number of rows to scroll per scroll wheel event.
 
#define GUAC_TERMINAL_PIPE_INTERPRET_OUTPUT   1
 Flag which specifies that terminal output should be sent to both the current pipe stream and the user's display.
 
#define GUAC_TERMINAL_PIPE_AUTOFLUSH   2
 Flag which forces the open pipe stream to be flushed automatically, whenever a new frame would be rendered, with only minimal buffering performed between frames.
 

Typedefs

typedef struct guac_terminal guac_terminal
 Represents a terminal emulator which uses a given Guacamole client to render itself.
 
typedef void guac_terminal_upload_path_handler(guac_client *client, char *path)
 Handler that is invoked whenever the necessary terminal codes are sent to to the given terminal to change the path for future file uploads.
 
typedef guac_stream * guac_terminal_file_download_handler(guac_client *client, char *filename)
 Handler that is invoked whenever the necessary terminal codes are sent to initiate a download of a given remote file.
 

Enumerations

enum  guac_terminal_cursor_type { GUAC_TERMINAL_CURSOR_BLANK , GUAC_TERMINAL_CURSOR_IBAR , GUAC_TERMINAL_CURSOR_POINTER }
 All possible mouse cursors used by the terminal emulator. More...
 

Functions

guac_terminalguac_terminal_create (guac_client *client, guac_terminal_options *terminal_options)
 Creates a new guac_terminal, having the given width and height, and rendering to the given client.
 
guac_terminal_optionsguac_terminal_options_create (int width, int height, int dpi)
 Create a new guac_terminal_options struct.
 
void guac_terminal_free (guac_terminal *term)
 Frees all resources associated with the given terminal.
 
void guac_terminal_set_upload_path_handler (guac_terminal *terminal, guac_terminal_upload_path_handler *upload_path_handler)
 Sets the upload path handler for the given terminal.
 
void guac_terminal_set_file_download_handler (guac_terminal *terminal, guac_terminal_file_download_handler *file_download_handler)
 Sets the file download handler for the given terminal.
 
int guac_terminal_render_frame (guac_terminal *terminal)
 Renders a single frame of terminal data.
 
int guac_terminal_read_stdin (guac_terminal *terminal, char *c, int size)
 Reads from this terminal's STDIN.
 
void guac_terminal_start (guac_terminal *term)
 Notifies the terminal that rendering should begin and that user input should now be accepted.
 
void guac_terminal_stop (guac_terminal *term)
 Manually stop the terminal to forcibly unblock any pending reads/writes, e.g.
 
void guac_terminal_notify (guac_terminal *terminal)
 Notifies the terminal that an event has occurred and the terminal should flush itself when reasonable.
 
char * guac_terminal_prompt (guac_terminal *terminal, const char *title, bool echo)
 Reads a single line from this terminal's STDIN, storing the result in a newly-allocated string.
 
int guac_terminal_printf (guac_terminal *terminal, const char *format,...)
 Writes the given format string and arguments to this terminal's STDOUT in the same manner as printf().
 
int guac_terminal_send_key (guac_terminal *term, int keysym, int pressed)
 Handles the given key event, sending data, scrolling, pasting clipboard data, etc.
 
int guac_terminal_send_mouse (guac_terminal *term, guac_user *user, int x, int y, int mask)
 Handles the given mouse event, sending data, scrolling, pasting clipboard data, etc.
 
int guac_terminal_send_data (guac_terminal *term, const char *data, int length)
 Sends the given string as if typed by the user.
 
int guac_terminal_send_string (guac_terminal *term, const char *data)
 Sends the given string as if typed by the user.
 
int guac_terminal_write (guac_terminal *term, const char *buffer, int length)
 Writes the given buffer to the given terminal's STDOUT.
 
int guac_terminal_send_stream (guac_terminal *term, guac_user *user, guac_stream *stream)
 Initializes the handlers of the given guac_stream such that it serves as the source of input to the terminal.
 
int guac_terminal_sendf (guac_terminal *term, const char *format,...)
 Sends data through STDIN as if typed by the user, using the format string given and any args (similar to printf).
 
void guac_terminal_dup (guac_terminal *term, guac_user *user, guac_socket *socket)
 Replicates the current display state to a user that has just joined the connection.
 
void guac_terminal_sync_users (guac_terminal *term, guac_client *client, guac_socket *socket)
 Replicates the current display state to one or more users that are joining the connection.
 
int guac_terminal_resize (guac_terminal *term, int width, int height)
 Resize the client display and terminal to the given pixel dimensions.
 
int guac_terminal_get_available_scroll (guac_terminal *term)
 Returns the number of rows within the buffer of the given terminal which are not currently displayed on screen.
 
int guac_terminal_get_rows (guac_terminal *term)
 Returns the height of the given terminal, in characters.
 
int guac_terminal_get_columns (guac_terminal *term)
 Returns the width of the given terminal, in characters.
 
void guac_terminal_clipboard_reset (guac_terminal *terminal, const char *mimetype)
 Clears the clipboard contents for a given terminal, and assigns a new mimetype for future data.
 
void guac_terminal_clipboard_append (guac_terminal *terminal, const char *data, int length)
 Appends the given data to the contents of the clipboard for the given terminal.
 
void guac_terminal_remove_user (guac_terminal *terminal, guac_user *user)
 Removes the given user from any user-specific resources internal to the given terminal.
 
int guac_terminal_create_typescript (guac_terminal *term, const char *path, const char *name, int create_path)
 Requests that the terminal write all output to a new pair of typescript files within the given path and using the given base name.
 
void guac_terminal_apply_color_scheme (guac_terminal *terminal, const char *color_scheme)
 Immediately applies the given color scheme to the given terminal, overriding the color scheme provided when the terminal was created.
 
const char * guac_terminal_get_color_scheme (guac_terminal *terminal)
 Returns name of the color scheme currently in use by the given terminal.
 
void guac_terminal_apply_font (guac_terminal *terminal, const char *font_name, int font_size, int dpi)
 Alters the font of the terminal.
 
const char * guac_terminal_get_font_name (guac_terminal *terminal)
 Returns the font name currently in use by the given terminal.
 
int guac_terminal_get_font_size (guac_terminal *terminal)
 Returns the font size currently in use by the given terminal.
 
int guac_terminal_get_mod_ctrl (guac_terminal *terminal)
 Returns the current state of the mod_ctrl flag in the given terminal.
 

Detailed Description

Constants, structures, and function definitions defining the core functionality for the terminal library.

Macro Definition Documentation

◆ GUAC_TERMINAL_MAX_COLUMNS

#define GUAC_TERMINAL_MAX_COLUMNS   1024

The absolute maximum number of columns to allow within the display.

This implicitly limits the number of columns allowed within the buffer.

◆ GUAC_TERMINAL_PIPE_AUTOFLUSH

#define GUAC_TERMINAL_PIPE_AUTOFLUSH   2

Flag which forces the open pipe stream to be flushed automatically, whenever a new frame would be rendered, with only minimal buffering performed between frames.

By default, the contents of the pipe stream will be flushed only when the buffer is full or the pipe stream is being closed.

◆ GUAC_TERMINAL_PIPE_INTERPRET_OUTPUT

#define GUAC_TERMINAL_PIPE_INTERPRET_OUTPUT   1

Flag which specifies that terminal output should be sent to both the current pipe stream and the user's display.

By default, terminal output will be sent only to the open pipe.

Typedef Documentation

◆ guac_terminal_file_download_handler

typedef guac_stream * guac_terminal_file_download_handler(guac_client *client, char *filename)

Handler that is invoked whenever the necessary terminal codes are sent to initiate a download of a given remote file.

Parameters
clientThe guac_client associated with the terminal receiving the file download terminal code.
filenameThe 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.
Returns
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.

◆ guac_terminal_upload_path_handler

typedef void guac_terminal_upload_path_handler(guac_client *client, char *path)

Handler that is invoked whenever the necessary terminal codes are sent to to the given terminal to change the path for future file uploads.

Parameters
clientThe guac_client associated with the terminal receiving the upload path change terminal code.
pathThe requested path.

Enumeration Type Documentation

◆ guac_terminal_cursor_type

All possible mouse cursors used by the terminal emulator.

Enumerator
GUAC_TERMINAL_CURSOR_BLANK 

A transparent (blank) cursor.

GUAC_TERMINAL_CURSOR_IBAR 

A standard I-bar cursor for selecting text, etc.

GUAC_TERMINAL_CURSOR_POINTER 

A standard triangular mouse pointer for manipulating non-text objects.

Function Documentation

◆ guac_terminal_apply_color_scheme()

void guac_terminal_apply_color_scheme ( guac_terminal * terminal,
const char * color_scheme )

Immediately applies the given color scheme to the given terminal, overriding the color scheme provided when the terminal was created.

Valid color schemes are those accepted by guac_terminal_parse_color_scheme().

Parameters
terminalThe terminal to apply the color scheme to.
color_schemeThe color scheme to apply.

◆ guac_terminal_apply_font()

void guac_terminal_apply_font ( guac_terminal * terminal,
const char * font_name,
int font_size,
int dpi )

Alters the font of the terminal.

The terminal will automatically be redrawn and resized as necessary. If the terminal size changes, the remote side of the terminal session must be manually informed of that change or graphical artifacts may result.

Parameters
terminalThe terminal whose font family and/or size are being changed.
font_nameThe name of the new font family, or NULL if the font family should remain unchanged.
font_sizeThe new font size, in points, or -1 if the font size should remain unchanged.
dpiThe resolution of the display in DPI. If the font size will not be changed (the font size given is -1), this value is ignored.

◆ guac_terminal_clipboard_append()

void guac_terminal_clipboard_append ( guac_terminal * terminal,
const char * data,
int length )

Appends the given data to the contents of the clipboard for the given terminal.

The data must match the mimetype chosen for the clipboard data by guac_terminal_clipboard_reset().

Parameters
terminalThe terminal whose clipboard is being appended to.
dataThe data to append.
lengthThe number of bytes to append from the data given.

◆ guac_terminal_clipboard_reset()

void guac_terminal_clipboard_reset ( guac_terminal * terminal,
const char * mimetype )

Clears the clipboard contents for a given terminal, and assigns a new mimetype for future data.

Parameters
terminalThe terminal whose clipboard is being reset.
mimetypeThe mimetype of future data.

◆ guac_terminal_create()

guac_terminal * guac_terminal_create ( guac_client * client,
guac_terminal_options * terminal_options )

Creates a new guac_terminal, having the given width and height, and rendering to the given client.

As failover mechanisms and the Guacamole client implementation typically use the receipt of a "sync" message to denote successful connection, rendering of frames (sending of "sync") will be withheld until guac_terminal_start() is called, and user input will be ignored. The guac_terminal_start() function should be invoked only after either the underlying connection has truly succeeded, or until visible terminal output or user input is required.

Parameters
clientThe client to which the terminal will be rendered.
terminal_optionsThe configuration used for instantiating the terminal. For information about the options, see the guac_terminal_options definition.
Returns
A new guac_terminal having the given font, dimensions, and attributes which renders all text to the given client.

◆ guac_terminal_create_typescript()

int guac_terminal_create_typescript ( guac_terminal * term,
const char * path,
const char * name,
int create_path )

Requests that the terminal write all output to a new pair of typescript files within the given path and using the given base name.

Terminal output will be written to these new files, along with timing information. If the create_path flag is non-zero, the given path will be created if it does not yet exist. If creation of the typescript files or path fails, error messages will automatically be logged, and no typescript will be written. The typescript will automatically be closed once the terminal is freed.

Parameters
termThe terminal whose output should be written to a typescript.
pathThe full absolute path to a directory in which the typescript files should be created.
nameThe base name to use for the typescript files created within the specified path.
create_pathZero if the specified path MUST exist for typescript files to be written, or non-zero if the path should be created if it does not yet exist.
Returns
Zero if the typescript files have been successfully created and a typescript will be written, non-zero otherwise.

◆ guac_terminal_dup()

void guac_terminal_dup ( guac_terminal * term,
guac_user * user,
guac_socket * socket )

Replicates the current display state to a user that has just joined the connection.

All instructions necessary to replicate state are sent over the given socket.

Deprecated
The guac_terminal_sync_users method should be used when duplicating display state to a set of users.
Parameters
termThe terminal emulator associated with the connection being joined.
userThe user joining the connection.
socketThe guac_socket specific to the joining user and across which messages synchronizing the current display state should be sent.

◆ guac_terminal_free()

void guac_terminal_free ( guac_terminal * term)

Frees all resources associated with the given terminal.

Parameters
termThe terminal to free.

◆ guac_terminal_get_available_scroll()

int guac_terminal_get_available_scroll ( guac_terminal * term)

Returns the number of rows within the buffer of the given terminal which are not currently displayed on screen.

Adjustments to the desired scrollback size are taken into account, and rows which are within the buffer but unavailable due to being outside the desired scrollback range are ignored.

Parameters
termThe terminal whose off-screen row count should be determined.
Returns
The number of rows within the buffer which are not currently displayed on screen.

◆ guac_terminal_get_color_scheme()

const char * guac_terminal_get_color_scheme ( guac_terminal * terminal)

Returns name of the color scheme currently in use by the given terminal.

Parameters
terminalThe terminal whose color scheme should be returned.
Returns
The name of the color scheme currently in use by the given terminal.

◆ guac_terminal_get_columns()

int guac_terminal_get_columns ( guac_terminal * term)

Returns the width of the given terminal, in characters.

Parameters
termThe terminal whose width should be determined.
Returns
The width of the terminal, in characters.

◆ guac_terminal_get_font_name()

const char * guac_terminal_get_font_name ( guac_terminal * terminal)

Returns the font name currently in use by the given terminal.

Parameters
terminalThe terminal whose font name is being retrieved.
Returns
The name of the font in use by the given terminal.

◆ guac_terminal_get_font_size()

int guac_terminal_get_font_size ( guac_terminal * terminal)

Returns the font size currently in use by the given terminal.

Parameters
terminalThe terminal whose font size is being retrieved.
Returns
The size of the font in use by the given terminal.

◆ guac_terminal_get_mod_ctrl()

int guac_terminal_get_mod_ctrl ( guac_terminal * terminal)

Returns the current state of the mod_ctrl flag in the given terminal.

Parameters
terminalThe terminal for which the mod_ctrl state is being checked.
Returns
The current state of the mod_ctrl flag.

◆ guac_terminal_get_rows()

int guac_terminal_get_rows ( guac_terminal * term)

Returns the height of the given terminal, in characters.

Parameters
termThe terminal whose height should be determined.
Returns
The height of the terminal, in characters.

◆ guac_terminal_notify()

void guac_terminal_notify ( guac_terminal * terminal)

Notifies the terminal that an event has occurred and the terminal should flush itself when reasonable.

Parameters
terminalThe terminal to notify.

◆ guac_terminal_options_create()

guac_terminal_options * guac_terminal_options_create ( int width,
int height,
int dpi )

Create a new guac_terminal_options struct.

All parameters are required. Any options that are not passed in this constructor will be set to default values unless overriden.

The guac_terminal_options struct should only be created using this constructor.

Parameters
widthThe width of the terminal, in pixels.
heightThe height of the terminal, in pixels.
dpiThe DPI of the display. The given font size will be adjusted to produce glyphs at the given DPI.
Returns
A new terminal options struct with all required options populated, ready to have any defaults overriden as needed.

◆ guac_terminal_printf()

int guac_terminal_printf ( guac_terminal * terminal,
const char * format,
... )

Writes the given format string and arguments to this terminal's STDOUT in 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().

Parameters
terminalThe terminal to write to.
formatA printf-style format string describing the data to be written to STDOUT.
...Any arguments to use when filling the format string.
Returns
The number of bytes written to STDOUT, or a negative value if an error occurs preventing the data from being written in its entirety.

◆ guac_terminal_prompt()

char * guac_terminal_prompt ( guac_terminal * terminal,
const char * title,
bool echo )

Reads a single line from this terminal's STDIN, storing the result in a newly-allocated string.

Input is retrieved in the same manner as guac_terminal_read_stdin() and the same restrictions apply. As reading input naturally requires user interaction, this function will implicitly invoke guac_terminal_start().

Parameters
terminalThe terminal to which the provided title should be output, and from whose STDIN the single line of input should be read.
titleThe human-readable title to output to the terminal just prior to reading from STDIN.
echoNon-zero if the characters read from STDIN should be echoed back as terminal output, or zero if asterisks should be displayed instead.
Returns
A newly-allocated string containing a single line of input read from the provided terminal's STDIN. This string must eventually be manually freed with a call to guac_mem_free().

◆ guac_terminal_read_stdin()

int guac_terminal_read_stdin ( guac_terminal * terminal,
char * c,
int size )

Reads from this terminal's STDIN.

Input comes from key and mouse events 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.

Parameters
terminalThe terminal to read from.
cThe buffer that should receive the bytes read.
sizeThe number of bytes available within the buffer.
Returns
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.

◆ guac_terminal_remove_user()

void guac_terminal_remove_user ( guac_terminal * terminal,
guac_user * user )

Removes the given user from any user-specific resources internal to the given terminal.

This function must be called whenever a user leaves a terminal connection.

Parameters
terminalThe terminal that the given user is leaving.
userThe user who is disconnecting.

◆ guac_terminal_render_frame()

int guac_terminal_render_frame ( guac_terminal * terminal)

Renders a single frame of terminal data.

If data is not yet available, this function will block until data is written.

Parameters
terminalThe terminal that should be rendered.
Returns
Zero if the frame was rendered successfully, non-zero if an error occurred.

◆ guac_terminal_resize()

int guac_terminal_resize ( guac_terminal * term,
int width,
int height )

Resize the client display and terminal to the given pixel dimensions.

Parameters
termThe terminal to resize.
widthThe new terminal width, in pixels.
heightThe new terminal height, in pixels.
Returns
Zero if the terminal was successfully resized to the given dimensions, non-zero otherwise.

◆ guac_terminal_send_data()

int guac_terminal_send_data ( guac_terminal * term,
const char * data,
int length )

Sends the given string as if typed by the user.

If terminal input is currently coming from a stream due to a prior call to guac_terminal_send_stream(), any input which would normally result from invoking this function is dropped.

Parameters
termThe terminal which should receive the given data on STDIN.
dataThe data the terminal should receive on STDIN.
lengthThe size of the given data, in bytes.
Returns
The number of bytes written to STDIN, or a negative value if an error occurs preventing the data from being written. This should always be the size of the data given unless data is intentionally dropped.

◆ guac_terminal_send_key()

int guac_terminal_send_key ( guac_terminal * term,
int keysym,
int pressed )

Handles the given key event, sending data, scrolling, pasting clipboard data, etc.

as necessary. If terminal input is currently coming from a stream due to a prior call to guac_terminal_send_stream(), any input which would normally result from the key event is dropped.

Parameters
termThe terminal which should receive the given data on STDIN.
keysymThe X11 keysym of the key that was pressed or released.
pressedNon-zero if the key represented by the given keysym is currently pressed, zero if it is released.
Returns
Zero if the key event was handled successfully, non-zero otherwise.

◆ guac_terminal_send_mouse()

int guac_terminal_send_mouse ( guac_terminal * term,
guac_user * user,
int x,
int y,
int mask )

Handles the given mouse event, sending data, scrolling, pasting clipboard data, etc.

as necessary. If terminal input is currently coming from a stream due to a prior call to guac_terminal_send_stream(), any input which would normally result from the mouse event is dropped.

Parameters
termThe terminal which should receive the given data on STDIN.
userThe user that originated the mouse event.
xThe X coordinate of the mouse within the display when the event occurred, in pixels. This value is not guaranteed to be within the bounds of the display area.
yThe Y coordinate of the mouse within the display when the event occurred, in pixels. This value is not guaranteed to be within the bounds of the display area.
maskAn integer value representing the current state of each button, where the Nth bit within the integer is set to 1 if and only if the Nth mouse button is currently pressed. The lowest-order bit is the left mouse button, followed by the middle button, right button, and finally the up and down buttons of the scroll wheel.
See also
GUAC_CLIENT_MOUSE_LEFT
GUAC_CLIENT_MOUSE_MIDDLE
GUAC_CLIENT_MOUSE_RIGHT
GUAC_CLIENT_MOUSE_SCROLL_UP
GUAC_CLIENT_MOUSE_SCROLL_DOWN
Returns
Zero if the mouse event was handled successfully, non-zero otherwise.

◆ guac_terminal_send_stream()

int guac_terminal_send_stream ( guac_terminal * term,
guac_user * user,
guac_stream * stream )

Initializes the handlers of the given guac_stream such that it serves as the source of input to the terminal.

Other input sources will be temporarily ignored until the stream is closed through receiving an "end" instruction. If input is already being read from a stream due to a prior call to guac_terminal_send_stream(), the prior call will remain in effect and this call will fail.

Calling this function will overwrite the data member of the given guac_stream.

Parameters
termThe terminal emulator which should receive input from the given stream.
userThe user that opened the stream.
streamThe guac_stream which should serve as the source of input for the terminal.
Returns
Zero if the terminal input has successfully been configured to read from the given stream, non-zero otherwise.

◆ guac_terminal_send_string()

int guac_terminal_send_string ( guac_terminal * term,
const char * data )

Sends the given string as if typed by the user.

If terminal input is currently coming from a stream due to a prior call to guac_terminal_send_stream(), any input which would normally result from invoking this function is dropped.

Parameters
termThe terminal which should receive the given data on STDIN.
dataThe data the terminal should receive on STDIN.
Returns
The number of bytes written to STDIN, or a negative value if an error occurs preventing the data from being written. This should always be the size of the data given unless data is intentionally dropped.

◆ guac_terminal_sendf()

int guac_terminal_sendf ( guac_terminal * term,
const char * format,
... )

Sends data through STDIN as if typed by the user, using the format string given and any args (similar to printf).

If terminal input is currently coming from a stream due to a prior call to guac_terminal_send_stream(), any input which would normally result from invoking this function is dropped.

Parameters
termThe terminal which should receive the given data on STDIN.
formatA printf-style format string describing the data to be received on STDIN.
...Any arguments to use when filling the format string.
Returns
The number of bytes written to STDIN, or a negative value if an error occurs preventing the data from being written. This should always be the size of the data given unless data is intentionally dropped.

◆ guac_terminal_set_file_download_handler()

void guac_terminal_set_file_download_handler ( guac_terminal * terminal,
guac_terminal_file_download_handler * file_download_handler )

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.

Parameters
terminalThe terminal to set the file download handler for.
file_download_handlerThe handler to be called whenever the necessary terminal codes are sent to the given terminal to initiate a download of a given remote file.

◆ guac_terminal_set_upload_path_handler()

void guac_terminal_set_upload_path_handler ( guac_terminal * terminal,
guac_terminal_upload_path_handler * upload_path_handler )

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.

Parameters
terminalThe terminal to set the upload path handler for.
upload_path_handlerThe handler to be called whenever the necessary terminal codes are sent to the given terminal to change the path for future file uploads.

◆ guac_terminal_start()

void guac_terminal_start ( guac_terminal * term)

Notifies the terminal that rendering should begin and that user input should now be accepted.

This function must be invoked following terminal creation for the end of frames to be signalled with "sync" messages. Until this function is invoked, "sync" messages will be withheld.

Parameters
termThe terminal to start.

◆ guac_terminal_stop()

void guac_terminal_stop ( guac_terminal * term)

Manually stop the terminal to forcibly unblock any pending reads/writes, e.g.

forcing guac_terminal_read_stdin() to return and cease all terminal I/O.

Parameters
termThe terminal to stop.

◆ guac_terminal_sync_users()

void guac_terminal_sync_users ( guac_terminal * term,
guac_client * client,
guac_socket * socket )

Replicates the current display state to one or more users that are joining the connection.

All instructions necessary to replicate state are sent over the given socket. The set of users receiving these instructions is determined solely by the socket chosen.

Parameters
termThe terminal whose state should be synchronized to the users.
clientThe client associated with the users to be synchronized.
socketThe socket to which the terminal state will be broadcast.

◆ guac_terminal_write()

int guac_terminal_write ( guac_terminal * term,
const char * buffer,
int length )

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().

Parameters
termThe terminal to write to.
bufferA buffer containing the characters to be written to the terminal.
lengthThe number of bytes within the given string to write to the terminal.
Returns
The number of bytes written to STDOUT, or a negative value if an error occurs preventing the data from being written in its entirety.