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 loaded dynamically using the functions of libdl. Each client plugin is required to follow a naming convention, where the name of the library is libguac-client-PROTOCOL. Failing to do this means that guacd will be unable to find the library when the client plugin needs to be loaded.

To load a client plugin, guacd calls the guac_client_plugin_open() function with the name of the protocol corresponding to the plugin to be loaded. Upon success, guac_client_plugin_open() returns a handle to the library containing the client plugin within an instance of guac_client_plugin. This instance will eventually be cleaned up by guac_client_plugin_close() when guacd is finished using it. While these functions are intended to be used by guacd, there is no reason they cannot be used in another proxy implementation, even if that proxy implementation resides within another client plugin.

Once the client plugin is successfully loaded, guacd makes a call to guac_client_plugin_init_client() to initialize the client. This function calls the guac_client_init() function within the client plugin which absolutely all client plugins must define. This function is the entry point of all client plugins, similar to the main() function of a C program.

As guacd handles the handshake procedure required by the Guacamole protocol, it reads a statically-allocated, NULL-terminated set of argument names declared within the client plugin: GUAC_CLIENT_ARGS. As with guac_client_init(), all client plugins must define this variable if they are to work. As the handshake procedure is completed, guacd will initialize and populate a guac_client structure, including the guac_client_info structure contained within it, and pass it to guac_client_init() along with the argument count and argument values received by the connecting client.

It is the duty of the client plugin implementation to populate the event handlers of the guac_client it receives as applicable. Once this is done, and the guac_client_init() function returns successfully, communication with the connected client begins, and guacd will invoke the event handlers of the guac_client as necessary for any instruction received.

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.

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 reduces 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. The guac_socket corresponding to the connected client is stored within the socket member of the guac_client object in use, for example:

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

When large instructions need to be sent, particularly those associated with audio or video, it is best to send those instructions broken into individual packets using nest instructions, such that the larger instruction can be interleaved with the smaller instructions such that normal responsiveness is not lessened. As future instructions cannot be parsed until the earlier instructions finish parsing, avoiding large instructions is important if the user is expected to interact with their display in real-time.

libguac provides rudimentary means of automatically nesting instructions using the guac_socket_nest() function. This function returns a new guac_socket which writes data to nest instructions to its parent guac_socket, rather than to the client's stream directly. By using this and the piecemeal versions of the instruction-sending functions required, audio or video data can be stretched over multiple instructions rather than one single instruction:

/* Get nested socket */
guac_socket* nested_socket = guac_socket_nest(client->socket, 0);

/* Write audio header */
guac_protocol_send_audio_header(nested_socket,
    0, "audio/ogg", 250, buffer_size);

...

/* Write data packets */
guac_protocol_send_audio_data(nested_socket, data, sizeof(data));

...

/* Finish audio instruction */
guac_protocol_send_audio_end(nested_socket);

/* When done, close the socket */
guac_socket_close(nested_socket);

Providing that calls to guac_protocol_send_audio_data() (or the similar video functions) are made interleaved with calls to smaller instructions, those smaller instructions will not be blocked by the size of the audio data that must be sent.

Generally, as guacd receives instructions from the connected client, it invokes event handlers if set within the associated guac_client instance. These handlers correspond to the instructions received, which in turn correspond to events which occur on the client side. The only exception to this is when guacd wishes to give the client plugin control and allow it to handle any messages that may have arrived from the remote desktop server, in which case it invokes a specific event handler dedicated to this purpose.

int key_handler(guac_client* client, int keysym, int pressed) {
    /* Do something */
}

...

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

int mouse_handler(guac_client* client, int x, int y, int button_mask) {
    /* Do something */
}

...

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

int clipboard_handler(guac_client* client, char* text) {
    /* Do something */
}

...

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

int message_handler(guac_client* client) {
    /* Handle server messages */
}

...

/* Within guac_client_init */
client->handle_messages = message_handler;