libguac  1.0.0
Data Structures | Functions
user.h File Reference

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

Go to the source code of this file.

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_userguac_user_alloc ()
 Allocates a new, blank user, not associated with any specific client or socket. More...
 
void guac_user_free (guac_user *user)
 Frees the given user and all associated resources. More...
 
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. More...
 
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. More...
 
guac_streamguac_user_alloc_stream (guac_user *user)
 Allocates a new stream. More...
 
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(). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
guac_objectguac_user_alloc_object (guac_user *user)
 Allocates a new object. More...
 
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(). More...
 
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. More...
 
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. More...
 
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. More...
 
int guac_user_supports_webp (guac_user *user)
 Returns whether the given user supports WebP. More...
 
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. More...
 
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. More...
 
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). More...
 

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
userThe user to signal to stop.
statusThe status to send over the Guacamole protocol.
formatA 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
userThe 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
userThe user to allocate the stream for.
Returns
The next available stream, or a newly allocated stream.

◆ guac_user_free()

void guac_user_free ( guac_user user)

Frees the given user and all associated resources.

Parameters
userThe 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
userThe user to return the object to.
objectThe 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
userThe user to return the stream to.
streamThe 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
userThe 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_timeoutThe 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 intial handlers will in turn call the user's handler (if defined).

Parameters
userThe user whose handlers should be called.
opcodeThe opcode of the instruction to pass to the user via the appropriate handler.
argcThe number of arguments which are part of the instruction.
argvAn 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
userThe user logging this message.
levelThe level at which to log this message.
formatA 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
userThe user joining the connection and providing the given arguments.
arg_namesA 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.
argvAn 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.
indexThe index of the entry in both the arg_names and argv arrays which corresponds to the argument being parsed.
default_valueThe 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
userThe user joining the connection and providing the given arguments.
arg_namesA 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.
argvAn 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.
indexThe index of the entry in both the arg_names and argv arrays which corresponds to the argument being parsed.
default_valueThe 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
userThe user joining the connection and providing the given arguments.
arg_namesA 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.
argvAn 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.
indexThe index of the entry in both the arg_names and argv arrays which corresponds to the argument being parsed.
default_valueThe 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
userThe user to stop.

◆ 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
userThe Guacamole user for whom the image stream should be allocated.
socketThe socket over which instructions associated with the image stream should be sent.
modeThe composite mode to use when rendering the image over the given layer.
layerThe destination layer.
xThe X coordinate of the upper-left corner of the destination rectangle within the given layer.
yThe Y coordinate of the upper-left corner of the destination rectangle within the given layer.
surfaceA Cairo surface containing the image data to be streamed.
qualityThe 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
userThe Guacamole user for whom the image stream should be allocated.
socketThe socket over which instructions associated with the image stream should be sent.
modeThe composite mode to use when rendering the image over the given layer.
layerThe destination layer.
xThe X coordinate of the upper-left corner of the destination rectangle within the given layer.
yThe Y coordinate of the upper-left corner of the destination rectangle within the given layer.
surfaceA 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
userThe Guacamole user for whom the image stream should be allocated.
socketThe socket over which instructions associated with the image stream should be sent.
modeThe composite mode to use when rendering the image over the given layer.
layerThe destination layer.
xThe X coordinate of the upper-left corner of the destination rectangle within the given layer.
yThe Y coordinate of the upper-left corner of the destination rectangle within the given layer.
surfaceA Cairo surface containing the image data to be streamed.
qualityThe 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.
losslessZero to encode a lossy image, non-zero to encode losslessly.

◆ 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
userThe 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
userThe user to signal to stop.
statusThe status to send over the Guacamole protocol.
formatA printf-style format string to log.
apThe 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
userThe user logging this message.
levelThe level at which to log this message.
formatA printf-style format string to log.
apThe va_list containing the arguments to be used when filling the format string for printing.