libguac  0.6.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
client.h File Reference

Provides functions and structures required for defining (and handling) a proxy client. More...

#include <stdarg.h>
#include "socket.h"
#include "protocol.h"

Go to the source code of this file.

Data Structures

struct  guac_client_plugin
 A handle to a client plugin, containing enough information about the plugin to complete the initial protocol handshake and instantiate a new client supporting the protocol provided by the client plugin. More...
struct  guac_client
 Guacamole proxy client. More...

Macros

#define GUAC_PROTOCOL_LIBRARY_PREFIX   "libguac-client-"
 String prefix which begins the library filename of all client plugins.
#define GUAC_PROTOCOL_LIBRARY_SUFFIX   ".so"
 String suffix which ends the library filename of all client plugins.
#define GUAC_PROTOCOL_NAME_LIMIT   256
 The maximum number of characters (COUNTING NULL TERMINATOR) to allow for protocol names within the library filename of client plugins.
#define GUAC_PROTOCOL_LIBRARY_LIMIT
 The maximum number of characters (INCLUDING NULL TERMINATOR) that a character array containing the concatenation of the library prefix, protocol name, and suffix can contain, assuming the protocol name is limited to GUAC_PROTOCOL_NAME_LIMIT characters.
#define GUAC_CLIENT_MOUSE_LEFT   0x01
 The flag set in the mouse button mask when the left mouse button is down.
#define GUAC_CLIENT_MOUSE_MIDDLE   0x02
 The flag set in the mouse button mask when the middle mouse button is down.
#define GUAC_CLIENT_MOUSE_RIGHT   0x04
 The flag set in the mouse button mask when the right mouse button is down.
#define GUAC_CLIENT_MOUSE_SCROLL_UP   0x08
 The flag set in the mouse button mask when the mouse scrollwheel is scrolled up.
#define GUAC_CLIENT_MOUSE_SCROLL_DOWN   0x10
 The flag set in the mouse button mask when the mouse scrollwheel is scrolled down.
#define GUAC_BUFFER_POOL_INITIAL_SIZE   1024
 The minimum number of buffers to create before allowing free'd buffers to be reclaimed.

Typedefs

typedef int guac_client_handle_messages (guac_client *client)
 Handler for server messages (where "server" refers to the server that the proxy client is connected to).
typedef int guac_client_mouse_handler (guac_client *client, int x, int y, int button_mask)
 Handler for Guacamole mouse events.
typedef int guac_client_key_handler (guac_client *client, int keysym, int pressed)
 Handler for Guacamole key events.
typedef int guac_client_clipboard_handler (guac_client *client, char *copied)
 Handler for Guacamole clipboard events.
typedef int guac_client_free_handler (guac_client *client)
 Handler for freeing up any extra data allocated by the client implementation.
typedef void guac_client_log_handler (guac_client *client, const char *format, va_list args)
 Handler for logging messages.
typedef int guac_client_init_handler (guac_client *client, int argc, char **argv)
 Handler which should initialize the given guac_client.

Enumerations

enum  guac_client_state { GUAC_CLIENT_RUNNING, GUAC_CLIENT_STOPPING }
 Possible current states of the Guacamole client. More...

Functions

guac_client_pluginguac_client_plugin_open (const char *protocol)
 Open the plugin which provides support for the given protocol, if it exists.
int guac_client_plugin_close (guac_client_plugin *plugin)
 Close the given plugin, releasing all associated resources.
guac_clientguac_client_plugin_get_client (guac_client_plugin *plugin, guac_socket *socket, int argc, char **argv, guac_client_log_handler *log_info_handler, guac_client_log_handler *log_error_handler)
 Initialize and return a new guac_client.
void guac_client_free (guac_client *client)
 Free all resources associated with the given client.
int guac_client_handle_instruction (guac_client *client, guac_instruction *instruction)
 Call the appropriate handler defined by the given client for the given instruction.
guac_layerguac_client_alloc_buffer (guac_client *client)
 Allocates a new buffer (invisible layer).
guac_layerguac_client_alloc_layer (guac_client *client)
 Allocates a new layer.
void guac_client_free_buffer (guac_client *client, guac_layer *layer)
 Returns the given buffer to the pool of available buffers, such that it can be reused by any subsequent call to guac_client_allow_buffer().
void guac_client_free_layer (guac_client *client, guac_layer *layer)
 Returns the given layer to the pool of available layers, such that it can be reused by any subsequent call to guac_client_allow_layer().
void guac_client_log_info (guac_client *client, const char *format,...)
 Logs an informational message in the log used by the given client.
void guac_client_log_error (guac_client *client, const char *format,...)
 Logs an error message in the log used by the given client.
void vguac_client_log_info (guac_client *client, const char *format, va_list ap)
 Logs an informational message in the log used by the given client.
void vguac_client_log_error (guac_client *client, const char *format, va_list ap)
 Logs an error message in the log used by the given client.
void guac_client_stop (guac_client *client)
 Signals the given client to stop gracefully.

Variables

const guac_layerGUAC_DEFAULT_LAYER
 The default Guacamole client layer, layer 0.

Detailed Description

Provides functions and structures required for defining (and handling) a proxy client.

Macro Definition Documentation

#define GUAC_BUFFER_POOL_INITIAL_SIZE   1024

The minimum number of buffers to create before allowing free'd buffers to be reclaimed.

In the case a protocol rapidly creates, uses, and destroys buffers, this can prevent unnecessary reuse of the same buffer (which would make draw operations unnecessarily synchronous).

#define GUAC_CLIENT_MOUSE_SCROLL_DOWN   0x10

The flag set in the mouse button mask when the mouse scrollwheel is scrolled down.

Note that mouse scrollwheels are actually sets of two buttons. One button is pressed and released for an upward scroll, and the other is pressed and released for a downward scroll. Some mice may actually implement these as separate buttons, not a wheel.

#define GUAC_CLIENT_MOUSE_SCROLL_UP   0x08

The flag set in the mouse button mask when the mouse scrollwheel is scrolled up.

Note that mouse scrollwheels are actually sets of two buttons. One button is pressed and released for an upward scroll, and the other is pressed and released for a downward scroll. Some mice may actually implement these as separate buttons, not a wheel.

#define GUAC_PROTOCOL_LIBRARY_LIMIT
Value:
( \
\
sizeof(GUAC_PROTOCOL_LIBRARY_PREFIX) - 1 /* "libguac-client-" */ \
+ GUAC_PROTOCOL_NAME_LIMIT - 1 /* [up to 256 chars] */ \
+ sizeof(GUAC_PROTOCOL_LIBRARY_SUFFIX) - 1 /* ".so" */ \
+ 1 /* NULL terminator */ \
\
)

The maximum number of characters (INCLUDING NULL TERMINATOR) that a character array containing the concatenation of the library prefix, protocol name, and suffix can contain, assuming the protocol name is limited to GUAC_PROTOCOL_NAME_LIMIT characters.

Enumeration Type Documentation

Possible current states of the Guacamole client.

Currently, the only two states are GUAC_CLIENT_RUNNING and GUAC_CLIENT_STOPPING.

Enumerator:
GUAC_CLIENT_RUNNING 

The state of the client from when it has been allocated by the main daemon until it is killed or disconnected.

GUAC_CLIENT_STOPPING 

The state of the client when a stop has been requested, signalling the I/O threads to shutdown.

Function Documentation

guac_layer* guac_client_alloc_buffer ( guac_client client)

Allocates a new buffer (invisible layer).

An arbitrary index is automatically assigned if no existing buffer is available for use.

Parameters
clientThe proxy client to allocate the buffer for.
Returns
The next available buffer, or a newly allocated buffer.
guac_layer* guac_client_alloc_layer ( guac_client client)

Allocates a new layer.

An arbitrary index is automatically assigned if no existing layer is available for use.

Parameters
clientThe proxy client to allocate the layer buffer for.
Returns
The next available layer, or a newly allocated layer.
void guac_client_free ( guac_client client)

Free all resources associated with the given client.

Parameters
clientThe proxy client to free all reasources of.
void guac_client_free_buffer ( guac_client client,
guac_layer layer 
)

Returns the given buffer to the pool of available buffers, such that it can be reused by any subsequent call to guac_client_allow_buffer().

Parameters
clientThe proxy client to return the buffer to.
layerThe buffer to return to the pool of available buffers.
void guac_client_free_layer ( guac_client client,
guac_layer layer 
)

Returns the given layer to the pool of available layers, such that it can be reused by any subsequent call to guac_client_allow_layer().

Parameters
clientThe proxy client to return the layer to.
layerThe buffer to return to the pool of available layer.
int guac_client_handle_instruction ( guac_client client,
guac_instruction instruction 
)

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

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

Parameters
clientThe proxy client whose handlers should be called.
instructionThe instruction to pass to the proxy client via the appropriate handler.
void guac_client_log_error ( guac_client client,
const char *  format,
  ... 
)

Logs an error message in the log used by the given client.

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

Parameters
clientThe proxy client to log an error for.
formatA printf-style format string to log.
...Arguments to use when filling the format string for printing.
void guac_client_log_info ( guac_client client,
const char *  format,
  ... 
)

Logs an informational message in the log used by the given client.

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

Parameters
clientThe proxy client to log an informational message for.
formatA printf-style format string to log.
...Arguments to use when filling the format string for printing.
int guac_client_plugin_close ( guac_client_plugin plugin)

Close the given plugin, releasing all associated resources.

This function must be called after use of a client plugin is finished.

Parameters
pluginThe client plugin to close.
Returns
Zero on success, non-zero if an error occurred while releasing the resources associated with the plugin.
guac_client* guac_client_plugin_get_client ( guac_client_plugin plugin,
guac_socket socket,
int  argc,
char **  argv,
guac_client_log_handler log_info_handler,
guac_client_log_handler log_error_handler 
)

Initialize and return a new guac_client.

The pluggable client will be initialized using the arguments provided.

Parameters
pluginThe client plugin to use to create the new client.
socketThe guac_socket the client should use for communication.
argcThe number of arguments being passed to the client.
argvAll arguments to be passed to the client.
log_info_handlerInfo logging handler to provide to the client before initializing.
log_error_handlerError logging handler to provide to the client before initializing.
Returns
A pointer to the newly initialized client.
guac_client_plugin* guac_client_plugin_open ( const char *  protocol)

Open the plugin which provides support for the given protocol, if it exists.

Parameters
protocolThe name of the protocol to retrieve the client plugin for.
Returns
The client plugin supporting the given protocol, or NULL if an error occurs or no such plugin exists.
void guac_client_stop ( guac_client client)

Signals the given client to stop gracefully.

This is a completely cooperative signal, and can be ignored by the client or the hosting daemon.

Parameters
clientThe proxy client to signal to stop.
void vguac_client_log_error ( guac_client client,
const char *  format,
va_list  ap 
)

Logs an error message in the log used by the given client.

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

Parameters
clientThe proxy client to log an error for.
formatA printf-style format string to log.
apThe va_list containing the arguments to be used when filling the format string for printing.
void vguac_client_log_info ( guac_client client,
const char *  format,
va_list  ap 
)

Logs an informational message in the log used by the given client.

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

Parameters
clientThe proxy client to log an informational message for.
formatA printf-style format string to log.
apThe va_list containing the arguments to be used when filling the format string for printing.