libguac
0.9.12-incubating
|
Functions and structure contents for the Guacamole proxy client. More...
Go to the source code of this file.
Data Structures | |
struct | guac_client |
Guacamole proxy client. More... | |
Functions | |
guac_client * | guac_client_alloc () |
Returns a new, barebones guac_client. More... | |
void | guac_client_free (guac_client *client) |
Free all resources associated with the given client. More... | |
void | guac_client_log (guac_client *client, guac_client_log_level level, const char *format,...) |
Writes a message in the log used by the given client. More... | |
void | vguac_client_log (guac_client *client, guac_client_log_level level, const char *format, va_list ap) |
Writes a message in the log used by the given client. More... | |
void | guac_client_stop (guac_client *client) |
Signals the given client to stop gracefully. More... | |
void | guac_client_abort (guac_client *client, guac_protocol_status status, const char *format,...) |
Signals the given client to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred. More... | |
void | vguac_client_abort (guac_client *client, guac_protocol_status status, const char *format, va_list ap) |
Signals the given client to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred. More... | |
guac_layer * | guac_client_alloc_buffer (guac_client *client) |
Allocates a new buffer (invisible layer). More... | |
guac_layer * | guac_client_alloc_layer (guac_client *client) |
Allocates a new layer. More... | |
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(). More... | |
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(). More... | |
guac_stream * | guac_client_alloc_stream (guac_client *client) |
Allocates a new stream. More... | |
void | guac_client_free_stream (guac_client *client, guac_stream *stream) |
Returns the given stream to the pool of available streams, such that it can be reused by any subsequent call to guac_client_alloc_stream(). More... | |
int | guac_client_add_user (guac_client *client, guac_user *user, int argc, char **argv) |
Adds the given user to the internal list of connected users. More... | |
void | guac_client_remove_user (guac_client *client, guac_user *user) |
Removes the given user, removing the user from the internally-tracked list of connected users, and calling any appropriate leave handler. More... | |
void | guac_client_foreach_user (guac_client *client, guac_user_callback *callback, void *data) |
Calls the given function on all currently-connected users of the given client. More... | |
void * | guac_client_for_owner (guac_client *client, guac_user_callback *callback, void *data) |
Calls the given function with the currently-connected user that is marked as the owner. More... | |
void * | guac_client_for_user (guac_client *client, guac_user *user, guac_user_callback *callback, void *data) |
Calls the given function with the given user ONLY if they are currently connected. More... | |
int | guac_client_end_frame (guac_client *client) |
Marks the end of the current frame by sending a "sync" instruction to all connected users. More... | |
int | guac_client_load_plugin (guac_client *client, const char *protocol) |
Initializes the given guac_client using the initialization routine provided by the plugin corresponding to the named protocol. More... | |
int | guac_client_get_processing_lag (guac_client *client) |
Calculates and returns the approximate processing lag experienced by the pool of users. More... | |
void | guac_client_stream_png (guac_client *client, guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, int x, int y, cairo_surface_t *surface) |
Streams the image data of the given surface over an image stream ("img" instruction) as PNG-encoded data. More... | |
void | guac_client_stream_jpeg (guac_client *client, guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, int x, int y, cairo_surface_t *surface, int quality) |
Streams the image data of the given surface over an image stream ("img" instruction) as JPEG-encoded data at the given quality. More... | |
void | guac_client_stream_webp (guac_client *client, guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, int x, int y, cairo_surface_t *surface, int quality, int lossless) |
Streams the image data of the given surface over an image stream ("img" instruction) as WebP-encoded data at the given quality. More... | |
int | guac_client_supports_webp (guac_client *client) |
Returns whether all users of the given client support WebP. More... | |
Variables | |
const guac_layer * | GUAC_DEFAULT_LAYER |
The default Guacamole client layer, layer 0. | |
Functions and structure contents for the Guacamole proxy client.
void guac_client_abort | ( | guac_client * | client, |
guac_protocol_status | status, | ||
const char * | format, | ||
... | |||
) |
Signals the given client to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred.
Note that this is a completely cooperative signal, and can be ignored by the client or the hosting daemon. The message given will be logged to the system logs.
client | The proxy client to signal to stop. |
status | The status to send over the Guacamole protocol. |
format | A printf-style format string to log. |
... | Arguments to use when filling the format string for printing. |
int guac_client_add_user | ( | guac_client * | client, |
guac_user * | user, | ||
int | argc, | ||
char ** | argv | ||
) |
Adds the given user to the internal list of connected users.
Future writes to the broadcast socket stored within guac_client will also write to this user. The join handler of this guac_client will be called.
client | The proxy client to add the user to. |
user | The user to add. |
argc | The number of arguments to pass to the new user. |
argv | An array of strings containing the argument values being passed. |
guac_client* guac_client_alloc | ( | ) |
Returns a new, barebones guac_client.
This new guac_client has no handlers set, but is otherwise usable.
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.
client | The proxy client to allocate the buffer for. |
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.
client | The proxy client to allocate the layer buffer for. |
guac_stream* guac_client_alloc_stream | ( | guac_client * | client | ) |
Allocates a new stream.
An arbitrary index is automatically assigned if no previously-allocated stream is available for use.
client | The client to allocate the stream for. |
int guac_client_end_frame | ( | guac_client * | client | ) |
Marks the end of the current frame by sending a "sync" instruction to all connected users.
This instruction will contain the current timestamp. The last_sent_timestamp member of guac_client will be updated accordingly.
If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.
client | The guac_client which has finished a frame. |
void* guac_client_for_owner | ( | guac_client * | client, |
guac_user_callback * | callback, | ||
void * | data | ||
) |
Calls the given function with the currently-connected user that is marked as the owner.
The owner of a connection is the user that established the initial connection that created the connection (the first user to connect and join). The function will be given a reference to the guac_user and the specified arbitrary data. If the owner has since left the connection, the function will instead be invoked with NULL as the guac_user. The value returned by the callback will be returned by this function.
This function is reentrant, but the user list MUST NOT be manipulated within the same thread as a callback to this function.
client | The client to retrieve the owner from. |
callback | The callback to invoke on the user marked as the owner of the connection. NULL will be passed to this callback instead if there is no owner. |
data | Arbitrary data to pass to the given callback. |
void* guac_client_for_user | ( | guac_client * | client, |
guac_user * | user, | ||
guac_user_callback * | callback, | ||
void * | data | ||
) |
Calls the given function with the given user ONLY if they are currently connected.
The function will be given a reference to the guac_user and the specified arbitrary data. If the provided user doesn't exist or has since left the connection, the function will instead be invoked with NULL as the guac_user. The value returned by the callback will be returned by this function.
This function is reentrant, but the user list MUST NOT be manipulated within the same thread as a callback to this function.
client | The client that the given user is expected to be associated with. |
user | The user to provide to the given callback if valid. The pointer need not even point to properly allocated memory; the user will only be passed to the callback function if they are valid, and the provided user pointer will not be dereferenced during this process. |
callback | The callback to invoke on the given user if they are valid. NULL will be passed to this callback instead if the user is not valid. |
data | Arbitrary data to pass to the given callback. |
void guac_client_foreach_user | ( | guac_client * | client, |
guac_user_callback * | callback, | ||
void * | data | ||
) |
Calls the given function on all currently-connected users of the given client.
The function will be given a reference to a guac_user and the specified arbitrary data. The value returned by the callback will be ignored.
This function is reentrant, but the user list MUST NOT be manipulated within the same thread as a callback to this function. Though the callback MAY invoke guac_client_foreach_user(), doing so should not be necessary, and may indicate poor design choices.
client | The client whose users should be iterated. |
callback | The function to call for each user. |
data | Arbitrary data to pass to the callback each time it is invoked. |
void guac_client_free | ( | guac_client * | client | ) |
Free all resources associated with the given client.
client | The 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().
client | The proxy client to return the buffer to. |
layer | The 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().
client | The proxy client to return the layer to. |
layer | The buffer to return to the pool of available layer. |
void guac_client_free_stream | ( | guac_client * | client, |
guac_stream * | stream | ||
) |
Returns the given stream to the pool of available streams, such that it can be reused by any subsequent call to guac_client_alloc_stream().
client | The client to return the stream to. |
stream | The stream to return to the pool of available stream. |
int guac_client_get_processing_lag | ( | guac_client * | client | ) |
Calculates and returns the approximate processing lag experienced by the pool of users.
The processing lag is the difference in time between server and client due purely to data processing and excluding network delays.
client | The guac_client to calculate the processing lag of. |
int guac_client_load_plugin | ( | guac_client * | client, |
const char * | protocol | ||
) |
Initializes the given guac_client using the initialization routine provided by the plugin corresponding to the named protocol.
This will automatically invoke guac_client_init within the plugin for the given protocol.
Note that the connection will likely not be established until the first user (the "owner") is added to the client.
client | The guac_client to initialize. |
protocol | The name of the protocol to use. |
void guac_client_log | ( | guac_client * | client, |
guac_client_log_level | level, | ||
const char * | format, | ||
... | |||
) |
Writes a 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.
client | The proxy client logging this message. |
level | The level at which to log this message. |
format | A printf-style format string to log. |
... | Arguments to use when filling the format string for printing. |
void guac_client_remove_user | ( | guac_client * | client, |
guac_user * | user | ||
) |
Removes the given user, removing the user from the internally-tracked list of connected users, and calling any appropriate leave handler.
client | The proxy client to return the buffer to. |
user | The user to remove. |
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.
client | The proxy client to signal to stop. |
void guac_client_stream_jpeg | ( | guac_client * | client, |
guac_socket * | socket, | ||
guac_composite_mode | mode, | ||
const guac_layer * | layer, | ||
int | x, | ||
int | y, | ||
cairo_surface_t * | surface, | ||
int | quality | ||
) |
Streams the image data of the given surface over an image stream ("img" instruction) as JPEG-encoded data at the given quality.
The image stream will be automatically allocated and freed.
client | The Guacamole client for which the image stream should be allocated. |
socket | The socket over which instructions associated with the image stream should be sent. |
mode | The composite mode to use when rendering the image over the given layer. |
layer | The destination layer. |
x | The X coordinate of the upper-left corner of the destination rectangle within the given layer. |
y | The Y coordinate of the upper-left corner of the destination rectangle within the given layer. |
surface | A Cairo surface containing the image data to be streamed. |
quality | The JPEG image quality, which must be an integer value between 0 and 100 inclusive. Larger values indicate improving quality at the expense of larger file size. |
void guac_client_stream_png | ( | guac_client * | client, |
guac_socket * | socket, | ||
guac_composite_mode | mode, | ||
const guac_layer * | layer, | ||
int | x, | ||
int | y, | ||
cairo_surface_t * | surface | ||
) |
Streams the image data of the given surface over an image stream ("img" instruction) as PNG-encoded data.
The image stream will be automatically allocated and freed.
client | The Guacamole client for which the image stream should be allocated. |
socket | The socket over which instructions associated with the image stream should be sent. |
mode | The composite mode to use when rendering the image over the given layer. |
layer | The destination layer. |
x | The X coordinate of the upper-left corner of the destination rectangle within the given layer. |
y | The Y coordinate of the upper-left corner of the destination rectangle within the given layer. |
surface | A Cairo surface containing the image data to be streamed. |
void guac_client_stream_webp | ( | guac_client * | client, |
guac_socket * | socket, | ||
guac_composite_mode | mode, | ||
const guac_layer * | layer, | ||
int | x, | ||
int | y, | ||
cairo_surface_t * | surface, | ||
int | quality, | ||
int | lossless | ||
) |
Streams the image data of the given surface over an image stream ("img" instruction) as WebP-encoded data at the given quality.
The image stream will be automatically allocated and freed. If the server does not support WebP, this function has no effect, so be sure to check the result of guac_client_supports_webp() prior to calling this function.
client | The Guacamole client for whom the image stream should be allocated. |
socket | The socket over which instructions associated with the image stream should be sent. |
mode | The composite mode to use when rendering the image over the given layer. |
layer | The destination layer. |
x | The X coordinate of the upper-left corner of the destination rectangle within the given layer. |
y | The Y coordinate of the upper-left corner of the destination rectangle within the given layer. |
surface | A Cairo surface containing the image data to be streamed. |
quality | The WebP image quality, which must be an integer value between 0 and 100 inclusive. For lossy images, larger values indicate improving quality at the expense of larger file size. For lossless images, this dictates the quality of compression, with larger values producing smaller files at the expense of speed. |
lossless | Zero to encode a lossy image, non-zero to encode losslessly. |
int guac_client_supports_webp | ( | guac_client * | client | ) |
Returns whether all users of the given client support WebP.
If any user does not support WebP, or the server cannot encode WebP images, zero is returned.
client | The Guacamole client whose users should be checked for WebP support. |
void vguac_client_abort | ( | guac_client * | client, |
guac_protocol_status | status, | ||
const char * | format, | ||
va_list | ap | ||
) |
Signals the given client to stop gracefully, while also signalling via the Guacamole protocol that an error has occurred.
Note that this is a completely cooperative signal, and can be ignored by the client or the hosting daemon. The message given will be logged to the system logs.
client | The proxy client to signal to stop. |
status | The status to send over the Guacamole protocol. |
format | A printf-style format string to log. |
ap | The va_list containing the arguments to be used when filling the format string for printing. |
void vguac_client_log | ( | guac_client * | client, |
guac_client_log_level | level, | ||
const char * | format, | ||
va_list | ap | ||
) |
Writes a 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.
client | The proxy client logging this message. |
level | The level at which to log this message. |
format | A printf-style format string to log. |
ap | The va_list containing the arguments to be used when filling the format string for printing. |