libguac  0.9.11-incubating
Data Fields
guac_client Struct Reference

Guacamole proxy client. More...

Data Fields

guac_socketsocket
 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_handlerfree_handler
 Handler for freeing data when the client is being unloaded. More...
 
guac_client_log_handlerlog_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_handlerjoin_handler
 Handler for join events, called whenever a new user is joining an active connection. More...
 
guac_user_leave_handlerleave_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

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;
}
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.

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.

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.

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 guac_client_init(guac_client* client) {
}
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) {
}
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 guac_client_init(guac_client* client) {
}
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()];
}
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.

Because this socket broadcasts to all connected users, this socket MUST NOT be used within the same thread as a "leave" or "join" handler. Doing so results in undefined behavior, including possible segfaults.

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: