Defines the guac_user object, which represents a physical connection within a larger, possibly shared, logical connection represented by a guac_client. More...

Data Structures
struct	guac_user_info
	Information exposed by the remote client during the connection handshake which can be used by a client plugin. More...

struct	guac_user
	Representation of a physical connection within a larger logical connection which may be shared. More...

Functions
guac_user *	guac_user_alloc ()
	Allocates a new, blank user, not associated with any specific client or socket.

void	guac_user_free (guac_user *user)
	Frees the given user and all associated resources.

int	guac_user_handle_connection (guac_user *user, int usec_timeout)
	Handles all I/O for the portion of a user's Guacamole connection following the initial "select" instruction, including the rest of the handshake.

int	guac_user_handle_instruction (guac_user user, const char opcode, int argc, char **argv)
	Call the appropriate handler defined by the given user for the given instruction.

guac_stream *	guac_user_alloc_stream (guac_user *user)
	Allocates a new stream.

void	guac_user_free_stream (guac_user user, guac_stream stream)
	Returns the given stream to the pool of available streams, such that it can be reused by any subsequent call to guac_user_alloc_stream().

void	guac_user_stop (guac_user *user)
	Signals the given user that it must disconnect, or advises cooperating services that the given user is no longer connected.

void	guac_user_abort (guac_user user, guac_protocol_status status, const char format,...)
	Signals the given user to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred.

void	vguac_user_abort (guac_user user, guac_protocol_status status, const char format, va_list ap)
	Signals the given user to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred.

void	guac_user_log (guac_user user, guac_client_log_level level, const char format,...)
	Writes a message in the log used by the given user.

void	vguac_user_log (guac_user user, guac_client_log_level level, const char format, va_list ap)
	Writes a message in the log used by the given user.

guac_object *	guac_user_alloc_object (guac_user *user)
	Allocates a new object.

void	guac_user_free_object (guac_user user, guac_object object)
	Returns the given object to the pool of available objects, such that it can be reused by any subsequent call to guac_user_alloc_object().

void	guac_user_stream_argv (guac_user user, guac_socket socket, const char mimetype, const char name, const char *value)
	Streams the given connection parameter value over an argument value stream ("argv" instruction), exposing the current value of the named connection parameter to the given user.

void	guac_user_stream_png (guac_user user, guac_socket socket, guac_composite_mode mode, const guac_layer layer, int x, int y, cairo_surface_t surface)
	Streams the image data of the given surface over an image stream ("img" instruction) as PNG-encoded data.

void	guac_user_stream_jpeg (guac_user user, guac_socket socket, guac_composite_mode mode, const guac_layer layer, int x, int y, cairo_surface_t surface, int quality)
	Streams the image data of the given surface over an image stream ("img" instruction) as JPEG-encoded data at the given quality.

void	guac_user_stream_webp (guac_user user, guac_socket socket, guac_composite_mode mode, const guac_layer layer, int x, int y, cairo_surface_t surface, int quality, int lossless)
	Streams the image data of the given surface over an image stream ("img" instruction) as WebP-encoded data at the given quality.

int	guac_user_supports_msg (guac_user *user)
	Returns whether the given user supports the "msg" instruction.

int	guac_user_supports_required (guac_user *user)
	Returns whether the given user supports the "required" instruction.

int	guac_user_supports_webp (guac_user *user)
	Returns whether the given user supports WebP.

char *	guac_user_parse_args_string (guac_user user, const char arg_names, const char argv, int index, const char default_value)
	Automatically handles a single argument received from a joining user, returning a newly-allocated string containing that value.

int	guac_user_parse_args_int (guac_user user, const char arg_names, const char *argv, int index, int default_value)
	Automatically handles a single integer argument received from a joining user, returning the integer value of that argument.

int	guac_user_parse_args_boolean (guac_user user, const char arg_names, const char *argv, int index, int default_value)
	Automatically handles a single boolean argument received from a joining user, returning the value of that argument (either 1 for true or 0 for false).

Detailed Description

Defines the guac_user object, which represents a physical connection within a larger, possibly shared, logical connection represented by a guac_client.

Function Documentation

◆ guac_user_abort()

void guac_user_abort	(	guac_user *	user,
		guac_protocol_status	status,
		const char *	format,
			... )

Signals the given user to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred.

Note that this is a completely cooperative signal, and can be ignored by the user or the hosting daemon. The message given will be logged to the system logs.

Parameters

user	The user to signal to stop.
status	The status to send over the Guacamole protocol.
format	A printf-style format string to log.
...	Arguments to use when filling the format string for printing.

◆ guac_user_alloc()

guac_user * guac_user_alloc ( )

Allocates a new, blank user, not associated with any specific client or socket.

Returns: The newly allocated guac_user, or NULL if allocation failed.

◆ guac_user_alloc_object()

guac_object * guac_user_alloc_object ( guac_user * user )

Allocates a new object.

An arbitrary index is automatically assigned if no previously-allocated object is available for use.

Parameters

user	The user to allocate the object for.

Returns: The next available object, or a newly allocated object.

◆ guac_user_alloc_stream()

guac_stream * guac_user_alloc_stream ( guac_user * user )

Allocates a new stream.

An arbitrary index is automatically assigned if no previously-allocated stream is available for use.

Parameters

user	The user to allocate the stream for.

Returns: The next available stream, or a newly allocated stream, or NULL if the maximum number of active streams has been reached.

◆ guac_user_free()

void guac_user_free ( guac_user * user )

Frees the given user and all associated resources.

Parameters

user	The guac_user to free.

◆ guac_user_free_object()

void guac_user_free_object	(	guac_user *	user,
		guac_object *	object )

Returns the given object to the pool of available objects, such that it can be reused by any subsequent call to guac_user_alloc_object().

Parameters

user	The user to return the object to.
object	The object to return to the pool of available object.

◆ guac_user_free_stream()

void guac_user_free_stream	(	guac_user *	user,
		guac_stream *	stream )

Returns the given stream to the pool of available streams, such that it can be reused by any subsequent call to guac_user_alloc_stream().

Parameters

user	The user to return the stream to.
stream	The stream to return to the pool of available stream.

◆ guac_user_handle_connection()

int guac_user_handle_connection	(	guac_user *	user,
		int	usec_timeout )

Handles all I/O for the portion of a user's Guacamole connection following the initial "select" instruction, including the rest of the handshake.

The handshake-related properties of the given guac_user are automatically populated, and guac_user_handle_instruction() is invoked for all instructions received after the handshake has completed. This function blocks until the connection/user is aborted or the user disconnects.

Parameters

user	The user whose handshake and entire Guacamole protocol exchange should be handled. The user must already be associated with a guac_socket and guac_client, and the guac_client must already be fully initialized.
usec_timeout	The number of microseconds to wait for instructions from the given user before closing the connection with an error.

Returns: Zero if the user's Guacamole connection was successfully handled and the user has disconnected, or non-zero if an error prevented the user's connection from being handled properly.

◆ guac_user_handle_instruction()

int guac_user_handle_instruction	(	guac_user *	user,
		const char *	opcode,
		int	argc,
		char **	argv )

Call the appropriate handler defined by the given user for the given instruction.

A comparison is made between the instruction opcode and the initial handler lookup table defined in user-handlers.c. The initial handlers will in turn call the user's handler (if defined).

Parameters

user	The user whose handlers should be called.
opcode	The opcode of the instruction to pass to the user via the appropriate handler.
argc	The number of arguments which are part of the instruction.
argv	An array of all arguments which are part of the instruction.

Returns: Non-negative if the instruction was handled successfully, or negative if an error occurred.

◆ guac_user_log()

void guac_user_log	(	guac_user *	user,
		guac_client_log_level	level,
		const char *	format,
			... )

Writes a message in the log used by the given user.

The logger used will normally be defined by guacd (or whichever program loads the user) by setting the logging handlers of the user when it is loaded.

Parameters

user	The user logging this message.
level	The level at which to log this message.
format	A printf-style format string to log.
...	Arguments to use when filling the format string for printing.

◆ guac_user_parse_args_boolean()

int guac_user_parse_args_boolean	(	guac_user *	user,
		const char **	arg_names,
		const char **	argv,
		int	index,
		int	default_value )

Automatically handles a single boolean argument received from a joining user, returning the value of that argument (either 1 for true or 0 for false).

Only "true" and "false" are legitimate values for a boolean argument. If the argument provided by the user is blank or invalid, the default value is returned.

Parameters

user	The user joining the connection and providing the given arguments.
arg_names	A NULL-terminated array of argument names, corresponding to the provided array of argument values. This array must be exactly the same size as the argument value array, with one additional entry for the NULL terminator.
argv	An array of all argument values, corresponding to the provided array of argument names. This array must be exactly the same size as the argument name array, with the exception of the NULL terminator.
index	The index of the entry in both the arg_names and argv arrays which corresponds to the argument being parsed.
default_value	The value to return if the provided argument is blank or invalid.

Returns: true (1) if the provided argument value is "true", false (0) if the provided argument value is "false", or the default value if the provided argument value is blank or invalid.

◆ guac_user_parse_args_int()

int guac_user_parse_args_int	(	guac_user *	user,
		const char **	arg_names,
		const char **	argv,
		int	index,
		int	default_value )

Automatically handles a single integer argument received from a joining user, returning the integer value of that argument.

If the argument provided by the user is blank or invalid, the default value is returned.

Parameters

user	The user joining the connection and providing the given arguments.
arg_names	A NULL-terminated array of argument names, corresponding to the provided array of argument values. This array must be exactly the same size as the argument value array, with one additional entry for the NULL terminator.
argv	An array of all argument values, corresponding to the provided array of argument names. This array must be exactly the same size as the argument name array, with the exception of the NULL terminator.
index	The index of the entry in both the arg_names and argv arrays which corresponds to the argument being parsed.
default_value	The value to return if the provided argument is blank or invalid.

Returns: The integer value parsed from the provided argument value, or the default value if the provided argument value is blank or invalid.

◆ guac_user_parse_args_string()

char * guac_user_parse_args_string	(	guac_user *	user,
		const char **	arg_names,
		const char **	argv,
		int	index,
		const char *	default_value )

Automatically handles a single argument received from a joining user, returning a newly-allocated string containing that value.

If the argument provided by the user is blank, a newly-allocated string containing the default value is returned.

Parameters

user	The user joining the connection and providing the given arguments.
arg_names	A NULL-terminated array of argument names, corresponding to the provided array of argument values. This array must be exactly the same size as the argument value array, with one additional entry for the NULL terminator.
argv	An array of all argument values, corresponding to the provided array of argument names. This array must be exactly the same size as the argument name array, with the exception of the NULL terminator.
index	The index of the entry in both the arg_names and argv arrays which corresponds to the argument being parsed.
default_value	The value to return if the provided argument is blank. If this value is not NULL, the returned value will be a newly-allocated string containing this value.

Returns: A newly-allocated string containing the provided argument value. If the provided argument value is blank, this newly-allocated string will contain the default value. If the default value is NULL and the provided argument value is blank, no string will be allocated and NULL is returned.

◆ guac_user_stop()

void guac_user_stop ( guac_user * user )

Signals the given user that it must disconnect, or advises cooperating services that the given user is no longer connected.

Parameters

user	The user to stop.

◆ guac_user_stream_argv()

void guac_user_stream_argv	(	guac_user *	user,
		guac_socket *	socket,
		const char *	mimetype,
		const char *	name,
		const char *	value )

Streams the given connection parameter value over an argument value stream ("argv" instruction), exposing the current value of the named connection parameter to the given user.

The argument value stream will be automatically allocated and freed.

Parameters

user	The Guacamole user who should receive the connection parameter value.
socket	The socket over which instructions associated with the argument value stream should be sent.
mimetype	The mimetype of the data within the connection parameter value being sent.
name	The name of the connection parameter being sent.
value	The current value of the connection parameter being sent.

◆ guac_user_stream_jpeg()

void guac_user_stream_jpeg	(	guac_user *	user,
		guac_socket *	socket,
		guac_composite_mode	mode,
		const guac_layer *	layer,
		int	x,
		int	y,
		cairo_surface_t *	surface,
		int	quality )

Streams the image data of the given surface over an image stream ("img" instruction) as JPEG-encoded data at the given quality.

The image stream will be automatically allocated and freed.

Parameters

user	The Guacamole user for whom the image stream should be allocated.
socket	The socket over which instructions associated with the image stream should be sent.
mode	The composite mode to use when rendering the image over the given layer.
layer	The destination layer.
x	The X coordinate of the upper-left corner of the destination rectangle within the given layer.
y	The Y coordinate of the upper-left corner of the destination rectangle within the given layer.
surface	A Cairo surface containing the image data to be streamed.
quality	The JPEG image quality, which must be an integer value between 0 and 100 inclusive. Larger values indicate improving quality at the expense of larger file size.

◆ guac_user_stream_png()

void guac_user_stream_png	(	guac_user *	user,
		guac_socket *	socket,
		guac_composite_mode	mode,
		const guac_layer *	layer,
		int	x,
		int	y,
		cairo_surface_t *	surface )

Streams the image data of the given surface over an image stream ("img" instruction) as PNG-encoded data.

The image stream will be automatically allocated and freed.

Parameters

user	The Guacamole user for whom the image stream should be allocated.
socket	The socket over which instructions associated with the image stream should be sent.
mode	The composite mode to use when rendering the image over the given layer.
layer	The destination layer.
x	The X coordinate of the upper-left corner of the destination rectangle within the given layer.
y	The Y coordinate of the upper-left corner of the destination rectangle within the given layer.
surface	A Cairo surface containing the image data to be streamed.

◆ guac_user_stream_webp()

void guac_user_stream_webp	(	guac_user *	user,
		guac_socket *	socket,
		guac_composite_mode	mode,
		const guac_layer *	layer,
		int	x,
		int	y,
		cairo_surface_t *	surface,
		int	quality,
		int	lossless )

Streams the image data of the given surface over an image stream ("img" instruction) as WebP-encoded data at the given quality.

The image stream will be automatically allocated and freed. If the server does not support WebP, this function has no effect, so be sure to check the result of guac_user_supports_webp() or guac_client_supports_webp() prior to calling this function.

Parameters

user	The Guacamole user for whom the image stream should be allocated.
socket	The socket over which instructions associated with the image stream should be sent.
mode	The composite mode to use when rendering the image over the given layer.
layer	The destination layer.
x	The X coordinate of the upper-left corner of the destination rectangle within the given layer.
y	The Y coordinate of the upper-left corner of the destination rectangle within the given layer.
surface	A Cairo surface containing the image data to be streamed.
quality	The WebP image quality, which must be an integer value between 0 and 100 inclusive. For lossy images, larger values indicate improving quality at the expense of larger file size. For lossless images, this dictates the quality of compression, with larger values producing smaller files at the expense of speed.
lossless	Zero to encode a lossy image, non-zero to encode losslessly.

◆ guac_user_supports_msg()

int guac_user_supports_msg ( guac_user * user )

Returns whether the given user supports the "msg" instruction.

Parameters

user	The Guacamole user to check for support of the "msg" instruction.

Returns: Non-zero if the user supports the "msg" instruction, otherwise zero.

◆ guac_user_supports_required()

int guac_user_supports_required ( guac_user * user )

Returns whether the given user supports the "required" instruction.

Parameters

user	The Guacamole user to check for support of the "required" instruction.

Returns: Non-zero if the user supports the "required" instruction, otherwise zero.

◆ guac_user_supports_webp()

int guac_user_supports_webp ( guac_user * user )

Returns whether the given user supports WebP.

If the user does not support WebP, or the server cannot encode WebP images, zero is returned.

Parameters

user	The Guacamole user to check for WebP support.

Returns: Non-zero if the given user claims to support WebP and the server has been built with WebP support, zero otherwise.

◆ vguac_user_abort()

void vguac_user_abort	(	guac_user *	user,
		guac_protocol_status	status,
		const char *	format,
		va_list	ap )

Signals the given user to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred.

Note that this is a completely cooperative signal, and can be ignored by the user or the hosting daemon. The message given will be logged to the system logs.

Parameters

user	The user to signal to stop.
status	The status to send over the Guacamole protocol.
format	A printf-style format string to log.
ap	The va_list containing the arguments to be used when filling the format string for printing.

◆ vguac_user_log()

void vguac_user_log	(	guac_user *	user,
		guac_client_log_level	level,
		const char *	format,
		va_list	ap )

Writes a message in the log used by the given user.

The logger used will normally be defined by guacd (or whichever program loads the user) by setting the logging handlers of the user when it is loaded.

Parameters

user	The user logging this message.
level	The level at which to log this message.
format	A printf-style format string to log.
ap	The va_list containing the arguments to be used when filling the format string for printing.

Data Structures

Functions

Detailed Description

Function Documentation

◆ guac_user_abort()

◆ guac_user_alloc()

◆ guac_user_alloc_object()

◆ guac_user_alloc_stream()

◆ guac_user_free()

◆ guac_user_free_object()

◆ guac_user_free_stream()

◆ guac_user_handle_connection()

◆ guac_user_handle_instruction()

◆ guac_user_log()

◆ guac_user_parse_args_boolean()

◆ guac_user_parse_args_int()

◆ guac_user_parse_args_string()

◆ guac_user_stop()

◆ guac_user_stream_argv()

◆ guac_user_stream_jpeg()

◆ guac_user_stream_png()

◆ guac_user_stream_webp()

◆ guac_user_supports_msg()

◆ guac_user_supports_required()

◆ guac_user_supports_webp()

◆ vguac_user_abort()

◆ vguac_user_log()