Most functions within libguac handle errors by returning a zero or non-zero value, whichever is appropriate for the function at hand. If an error is encountered, the guac_error variable is set appropriately, and guac_error_message contains a statically-allocated human-readable string describing the context of the error. These variables intentionally mimic the functionality provided by errno and errno.h.

Both guac_error and guac_error_message are defined within error.h. A human-readable string describing the error indicated by guac_error can be retrieved using guac_status_string(), which is also statically allocated.

If functions defined within client plugins set guac_error and guac_error_message appropriately when errors are encountered, the messages logged to syslog by guacd will be more meaningful for both users and developers.

Client plugins are libraries which follow specific conventions such that they can be loaded dynamically by guacd. All client plugins must:

int join_handler(guac_user* user, int argc, char** argv) {
    /* Synchronize display state, init the user, etc. */
}

...

/* Within guac_client_init  */
client->join_handler = join_handler;

int leave_handler(guac_user* user) {
    /* Free user-specific data and clean up */
}

...

/* Within guac_client_init  */
client->leave_handler = leave_handler;

int free_handler(guac_client* client) {
    /* Disconnect, free client-specific data, etc. */
}

...

/* Within guac_client_init  */
client->free_handler = free_handler;

The main operand of all drawing instructions is the layer, represented within libguac by the guac_layer structure. Each guac_layer is normally allocated using guac_client_alloc_layer() or guac_client_alloc_buffer(), depending on whether a layer or buffer is desired, and freed with guac_client_free_layer() or guac_client_free_buffer().

Using these layer management functions allows you to reuse existing layers or buffers after their original purpose has expired, thus conserving resources on the client side, as allocation of new layers within the remote client is a relatively expensive operation.

It is through layers and buffers that Guacamole provides support for hardware-accelerated compositing and cached updates. Creative use of layers and buffers leads to efficient updates on the client side, which usually translates into speed and responsiveness.

Regardless of whether you allocate new layers or buffers, there is always one layer guaranteed to be present: the default layer, represented by libguac as GUAC_DEFAULT_LAYER. If you only wish to affect to the main display of the connected client somehow, this is the layer you want to use as the operand of your drawing instruction.

In addition to drawing, the Guacamole protocol supports streaming of arbitrary data. The main operand of all streaming instructions is the stream, represented within libguac by the guac_stream structure. Each guac_stream exists either at the user or client levels, depending on whether the stream is intended to be broadcast to all users or just one, and is thus allocated using either guac_client_alloc_stream() or guac_user_alloc_stream(). Explicitly-allocated streams must eventually be freed with guac_client_free_stream() or guac_user_free_stream().

Streams are the means by which data is transmitted for clipboard (via the "clipboard" instruction), audio (via the "audio" instruction), and even the images which make up typical drawing operations (via the "img" instruction). They will either be allocated for you, when an inbound stream is received from a user, or allocated manually, when an outbound stream needs to be sent to a user. As with guac_client and guac_user, each guac_stream has a set of handlers which correspond to instructions received related to streams. These instructions are documented in more detail in the section called “Streams and objects” and Appendix B, Guacamole protocol reference.

All drawing in Guacamole is accomplished through the sending of instructions to the connected client using the Guacamole protocol. The same goes for streaming audio, video, or file content. All features and content supported by Guacamole ultimately reduce to one or more instructions which are part of the documented protocol.

Most drawing using libguac is done using Cairo functions on a cairo_surface_t (see the Cairo API documentation) which is later streamed to the client using an img instruction and subsequent blob instructions, sent via guac_client_stream_png(). Cairo was chosen as a dependency of libguac to provide developers an existing and stable means of drawing to image buffers which will ultimately be sent as easy-to-digest PNG images.

The Guacamole protocol also supports drawing primitives similar to those present in the Cairo API and HTML5's canvas tag. These instructions are documented individually in the Guacamole Protocol Reference in a section dedicated to drawing instructions, and like all Guacamole protocol instructions, each instruction has a corresponding function in libguac following the naming convention guac_protocol_send_OPCODE().

Each protocol function takes a guac_socket as an argument, which is the buffered I/O object used by libguac. For each active connection, there are two important types of guac_socket instance: the broadcast socket, which exists at the client level within the guac_client, and the per-user socket, which is accessible within each guac_user. Data sent along the client-level broadcast socket will be sent to all connected users beneath that guac_client, while data sent along a user-level socket will be sent only to that user.

For example, to send a "size" instruction to all connected users via the client-level broadcast socket, you could invoke:

guac_protocol_send_size(client->socket, GUAC_DEFAULT_LAYER, 1024, 768);

Or, if the instruction is only relevant to a particular user, the socket associated with that user can be used instead:

guac_protocol_send_size(user->socket, GUAC_DEFAULT_LAYER, 1024, 768);

The sockets provided by libguac are threadsafe at the protocol level. Instructions written to a socket by multiple threads are guaranteed to be written atomically with respect to that socket.

Generally, as guacd receives instructions from the connected client, it invokes event handlers if set within the associated guac_user or guac_client, depending on the nature of the event. Most events are user-specific, and thus the event handlers reside within the guac_user structure, but there are client-specific events as well, such as a user joining or leaving the current connection. Event handlers typically correspond to Guacamole protocol instructions received over the socket by a connected user, which in turn correspond to events which occur on the client side.

int key_handler(guac_user* user, int keysym, int pressed) {
    /* Do something */
}

...

/* Within the "join" handler of guac_client */
user->key_handler = key_handler;

int mouse_handler(guac_user* user, int x, int y, int button_mask) {
    /* Do something */
}

...

/* Within the "join" handler of guac_client */
user->mouse_handler = mouse_handler;

int clipboard_handler(guac_user* user, guac_stream* stream, char* mimetype) {
    /* Do something */
}

...

/* Within the "join" handler of guac_client */
user->clipboard_handler = clipboard_handler;

int file_handler(guac_user* user, guac_stream* stream,
        char* mimetype, char* filename) {
    /* Do something */
}

...

/* Within the "join" handler of guac_client */
user->file_handler = file_handler;