guac_client Struct Reference

Guacamole proxy client. More...

Data Fields
guac_socket *	socket
	The guac_socket structure to be used to communicate with all connected web-clients (users). More...
guac_client_state	state
	The current state of the client. More...
void *	data
	Arbitrary reference to proxy client-specific data. More...
guac_timestamp	last_sent_timestamp
	The time (in milliseconds) that the last sync message was sent to the client.
guac_client_free_handler *	free_handler
	Handler for freeing data when the client is being unloaded. More...
guac_client_log_handler *	log_handler
	Logging handler. More...
char *	connection_id
	The unique identifier allocated for the connection, which may be used within the Guacamole protocol to refer to this connection. More...
int	connected_users
	The number of currently-connected users. More...
guac_user_join_handler *	join_handler
	Handler for join events, called whenever a new user is joining an active connection. More...
guac_user_leave_handler *	leave_handler
	Handler for leave events, called whenever a new user is leaving an active connection. More...
const char **	args
	NULL-terminated array of all arguments accepted by this client , in order. More...

Detailed Description

Guacamole proxy client.

Represents a Guacamole proxy client (the client which communicates to a server on behalf of Guacamole, on behalf of the web-client).

Field Documentation

args

const char** guac_client::args

NULL-terminated array of all arguments accepted by this client , in order.

New users will specify these arguments when they join the connection, and the values of those arguments will be made available to the function initializing newly-joined users.

The guac_client_init entry point is expected to initialize this, if arguments are expected.

Example:

const char* __my_args[] = {
    "hostname",
    "port",
    "username",
    "password",
    NULL
};

int guac_client_init(guac_client* client) {
    client->args = __my_args;
}

connected_users

int guac_client::connected_users

The number of currently-connected users.

This value may include inactive users if cleanup of those users has not yet finished.

connection_id

char* guac_client::connection_id

The unique identifier allocated for the connection, which may be used within the Guacamole protocol to refer to this connection.

This identifier is guaranteed to be unique from all existing connections and will not collide with any available protocol names.

data

void* guac_client::data

Arbitrary reference to proxy client-specific data.

Implementors of a Guacamole proxy client can store any data they want here, which can then be retrieved as necessary in the message handlers.

free_handler

guac_client_free_handler* guac_client::free_handler

Handler for freeing data when the client is being unloaded.

This handler will be called when the client needs to be unloaded by the proxy, and any data allocated by the proxy client should be freed.

Note that this handler will NOT be called if the client's guac_client_init() function fails.

Implement this handler if you store data inside the client.

Example:

int free_handler(guac_client* client);

int guac_client_init(guac_client* client) {
    client->free_handler = free_handler;
}

join_handler

guac_user_join_handler* guac_client::join_handler

Handler for join events, called whenever a new user is joining an active connection.

Note that because users may leave the connection at any time, a reference to a guac_user can become invalid at any time and should never be maintained outside the scope of a function invoked by libguac to which that guac_user was passed (the scope in which the guac_user reference is guaranteed to be valid) UNLESS that reference is properly invalidated within the leave_handler.

The handler is given a pointer to a newly-allocated guac_user which must then be initialized, if needed.

Example:

int join_handler(guac_user* user, int argc, char** argv);

int guac_client_init(guac_client* client) {
    client->join_handler = join_handler;
}

leave_handler

guac_user_leave_handler* guac_client::leave_handler

Handler for leave events, called whenever a new user is leaving an active connection.

The handler is given a pointer to the leaving guac_user whose custom data and associated resources must now be freed, if any.

Example:

int leave_handler(guac_user* user);

int guac_client_init(guac_client* client) {
    client->leave_handler = leave_handler;
}

log_handler

guac_client_log_handler* guac_client::log_handler

Logging handler.

This handler will be called via guac_client_log() when the client needs to log messages of any type.

In general, only programs loading the client should implement this handler, as those are the programs that would provide the logging facilities.

Client implementations should expect these handlers to already be set.

Example:

void log_handler(guac_client* client, guac_client_log_level level, const char* format, va_list args);

void function_of_daemon() {

    guac_client* client = [pass log_handler to guac_client_plugin_get_client()];

}

socket

guac_socket* guac_client::socket

The guac_socket structure to be used to communicate with all connected web-clients (users).

Unlike the user-level guac_socket, this guac_socket will broadcast instructions to all connected users simultaneously. It is expected that the implementor of any Guacamole proxy client will provide their own mechanism of I/O for their protocol. The guac_socket structure is used only to communicate conveniently with the Guacamole web-client.

state

guac_client_state guac_client::state

The current state of the client.

When the client is first allocated, this will be initialized to GUAC_CLIENT_RUNNING. It will remain at GUAC_CLIENT_RUNNING until an event occurs which requires the client to shutdown, at which point the state becomes GUAC_CLIENT_STOPPING.

---

The documentation for this struct was generated from the following file:

• guacamole/client.h