libguac 1.5.5
Loading...
Searching...
No Matches
Functions
protocol.h File Reference

Provides functions and structures required for communicating using the Guacamole protocol over a guac_socket connection, such as that provided by guac_client objects. More...

Go to the source code of this file.

Functions

int guac_protocol_send_ack (guac_socket *socket, guac_stream *stream, const char *error, guac_protocol_status status)
 Sends an ack instruction over the given guac_socket connection.
 
int guac_protocol_send_args (guac_socket *socket, const char **args)
 Sends an args instruction over the given guac_socket connection.
 
int guac_protocol_send_connect (guac_socket *socket, const char **args)
 Sends a connect instruction over the given guac_socket connection.
 
int guac_protocol_send_disconnect (guac_socket *socket)
 Sends a disconnect instruction over the given guac_socket connection.
 
int guac_protocol_send_error (guac_socket *socket, const char *error, guac_protocol_status status)
 Sends an error instruction over the given guac_socket connection.
 
int guac_protocol_send_key (guac_socket *socket, int keysym, int pressed, guac_timestamp timestamp)
 Sends a key instruction over the given guac_socket connection.
 
int guac_protocol_send_log (guac_socket *socket, const char *format,...)
 Sends a log instruction over the given guac_socket connection.
 
int vguac_protocol_send_log (guac_socket *socket, const char *format, va_list args)
 Sends a log instruction over the given guac_socket connection.
 
int guac_protocol_send_msg (guac_socket *socket, guac_message_type msg, const char **args)
 Sends the given string over the socket to be displayed on the client.
 
int guac_protocol_send_mouse (guac_socket *socket, int x, int y, int button_mask, guac_timestamp timestamp)
 Sends a mouse instruction over the given guac_socket connection.
 
int guac_protocol_send_touch (guac_socket *socket, int id, int x, int y, int x_radius, int y_radius, double angle, double force, guac_timestamp timestamp)
 Sends a touch instruction over the given guac_socket connection.
 
int guac_protocol_send_nest (guac_socket *socket, int index, const char *data)
 Sends a nest instruction over the given guac_socket connection.
 
int guac_protocol_send_nop (guac_socket *socket)
 Sends a nop instruction (null-operation) over the given guac_socket connection.
 
int guac_protocol_send_ready (guac_socket *socket, const char *id)
 Sends a ready instruction over the given guac_socket connection.
 
int guac_protocol_send_set (guac_socket *socket, const guac_layer *layer, const char *name, const char *value)
 Sends a set instruction over the given guac_socket connection.
 
int guac_protocol_send_set_int (guac_socket *socket, const guac_layer *layer, const char *name, int value)
 Sends a set instruction over the given guac_socket connection.
 
int guac_protocol_send_select (guac_socket *socket, const char *protocol)
 Sends a select instruction over the given guac_socket connection.
 
int guac_protocol_send_sync (guac_socket *socket, guac_timestamp timestamp)
 Sends a sync instruction over the given guac_socket connection.
 
int guac_protocol_send_body (guac_socket *socket, const guac_object *object, const guac_stream *stream, const char *mimetype, const char *name)
 Sends a body instruction over the given guac_socket connection.
 
int guac_protocol_send_filesystem (guac_socket *socket, const guac_object *object, const char *name)
 Sends a filesystem instruction over the given guac_socket connection.
 
int guac_protocol_send_undefine (guac_socket *socket, const guac_object *object)
 Sends an undefine instruction over the given guac_socket connection.
 
int guac_protocol_send_audio (guac_socket *socket, const guac_stream *stream, const char *mimetype)
 Sends an audio instruction over the given guac_socket connection.
 
int guac_protocol_send_file (guac_socket *socket, const guac_stream *stream, const char *mimetype, const char *name)
 Sends a file instruction over the given guac_socket connection.
 
int guac_protocol_send_pipe (guac_socket *socket, const guac_stream *stream, const char *mimetype, const char *name)
 Sends a pipe instruction over the given guac_socket connection.
 
int guac_protocol_send_blob (guac_socket *socket, const guac_stream *stream, const void *data, int count)
 Writes a block of data to the currently in-progress blob which was already created.
 
int guac_protocol_send_blobs (guac_socket *socket, const guac_stream *stream, const void *data, int count)
 Sends a series of blob instructions, splitting the given data across the number of instructions required to ensure the size of each blob does not exceed GUAC_PROTOCOL_BLOB_MAX_LENGTH.
 
int guac_protocol_send_end (guac_socket *socket, const guac_stream *stream)
 Sends an end instruction over the given guac_socket connection.
 
int guac_protocol_send_video (guac_socket *socket, const guac_stream *stream, const guac_layer *layer, const char *mimetype)
 Sends a video instruction over the given guac_socket connection.
 
int guac_protocol_send_arc (guac_socket *socket, const guac_layer *layer, int x, int y, int radius, double startAngle, double endAngle, int negative)
 Sends an arc instruction over the given guac_socket connection.
 
int guac_protocol_send_cfill (guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, int r, int g, int b, int a)
 Sends a cfill instruction over the given guac_socket connection.
 
int guac_protocol_send_clip (guac_socket *socket, const guac_layer *layer)
 Sends a clip instruction over the given guac_socket connection.
 
int guac_protocol_send_close (guac_socket *socket, const guac_layer *layer)
 Sends a close instruction over the given guac_socket connection.
 
int guac_protocol_send_copy (guac_socket *socket, const guac_layer *srcl, int srcx, int srcy, int w, int h, guac_composite_mode mode, const guac_layer *dstl, int dstx, int dsty)
 Sends a copy instruction over the given guac_socket connection.
 
int guac_protocol_send_cstroke (guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, guac_line_cap_style cap, guac_line_join_style join, int thickness, int r, int g, int b, int a)
 Sends a cstroke instruction over the given guac_socket connection.
 
int guac_protocol_send_cursor (guac_socket *socket, int x, int y, const guac_layer *srcl, int srcx, int srcy, int w, int h)
 Sends a cursor instruction over the given guac_socket connection.
 
int guac_protocol_send_curve (guac_socket *socket, const guac_layer *layer, int cp1x, int cp1y, int cp2x, int cp2y, int x, int y)
 Sends a curve instruction over the given guac_socket connection.
 
int guac_protocol_send_identity (guac_socket *socket, const guac_layer *layer)
 Sends an identity instruction over the given guac_socket connection.
 
int guac_protocol_send_lfill (guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, const guac_layer *srcl)
 Sends an lfill instruction over the given guac_socket connection.
 
int guac_protocol_send_line (guac_socket *socket, const guac_layer *layer, int x, int y)
 Sends a line instruction over the given guac_socket connection.
 
int guac_protocol_send_lstroke (guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, guac_line_cap_style cap, guac_line_join_style join, int thickness, const guac_layer *srcl)
 Sends an lstroke instruction over the given guac_socket connection.
 
int guac_protocol_send_img (guac_socket *socket, const guac_stream *stream, guac_composite_mode mode, const guac_layer *layer, const char *mimetype, int x, int y)
 Sends an img instruction over the given guac_socket connection.
 
int guac_protocol_send_pop (guac_socket *socket, const guac_layer *layer)
 Sends a pop instruction over the given guac_socket connection.
 
int guac_protocol_send_push (guac_socket *socket, const guac_layer *layer)
 Sends a push instruction over the given guac_socket connection.
 
int guac_protocol_send_rect (guac_socket *socket, const guac_layer *layer, int x, int y, int width, int height)
 Sends a rect instruction over the given guac_socket connection.
 
int guac_protocol_send_required (guac_socket *socket, const char **required)
 Sends a "required" instruction over the given guac_socket connection.
 
int guac_protocol_send_reset (guac_socket *socket, const guac_layer *layer)
 Sends a reset instruction over the given guac_socket connection.
 
int guac_protocol_send_start (guac_socket *socket, const guac_layer *layer, int x, int y)
 Sends a start instruction over the given guac_socket connection.
 
int guac_protocol_send_transfer (guac_socket *socket, const guac_layer *srcl, int srcx, int srcy, int w, int h, guac_transfer_function fn, const guac_layer *dstl, int dstx, int dsty)
 Sends a transfer instruction over the given guac_socket connection.
 
int guac_protocol_send_transform (guac_socket *socket, const guac_layer *layer, double a, double b, double c, double d, double e, double f)
 Sends a transform instruction over the given guac_socket connection.
 
int guac_protocol_send_dispose (guac_socket *socket, const guac_layer *layer)
 Sends a dispose instruction over the given guac_socket connection.
 
int guac_protocol_send_distort (guac_socket *socket, const guac_layer *layer, double a, double b, double c, double d, double e, double f)
 Sends a distort instruction over the given guac_socket connection.
 
int guac_protocol_send_move (guac_socket *socket, const guac_layer *layer, const guac_layer *parent, int x, int y, int z)
 Sends a move instruction over the given guac_socket connection.
 
int guac_protocol_send_shade (guac_socket *socket, const guac_layer *layer, int a)
 Sends a shade instruction over the given guac_socket connection.
 
int guac_protocol_send_size (guac_socket *socket, const guac_layer *layer, int w, int h)
 Sends a size instruction over the given guac_socket connection.
 
int guac_protocol_send_argv (guac_socket *socket, guac_stream *stream, const char *mimetype, const char *name)
 Sends an argv instruction over the given guac_socket connection.
 
int guac_protocol_send_clipboard (guac_socket *socket, const guac_stream *stream, const char *mimetype)
 Sends a clipboard instruction over the given guac_socket connection.
 
int guac_protocol_send_name (guac_socket *socket, const char *name)
 Sends a name instruction over the given guac_socket connection.
 
int guac_protocol_decode_base64 (char *base64)
 Decodes the given base64-encoded string in-place.
 
guac_protocol_version guac_protocol_string_to_version (const char *version_string)
 Given a string representation of a protocol version, return the enum value of that protocol version, or GUAC_PROTOCOL_VERSION_UNKNOWN if the value is not a known version.
 
const char * guac_protocol_version_to_string (guac_protocol_version version)
 Given the enum value of the protocol version, return a pointer to the string representation of the version, or NULL if the version is unknown.
 

Detailed Description

Provides functions and structures required for communicating using the Guacamole protocol over a guac_socket connection, such as that provided by guac_client objects.

Function Documentation

◆ guac_protocol_decode_base64()

int guac_protocol_decode_base64 ( char * base64)

Decodes the given base64-encoded string in-place.

The base64 string must be NULL-terminated.

Parameters
base64The base64-encoded string to decode.
Returns
The number of bytes resulting from the decode operation.

◆ guac_protocol_send_ack()

int guac_protocol_send_ack ( guac_socket * socket,
guac_stream * stream,
const char * error,
guac_protocol_status status )

Sends an ack instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
streamThe guac_stream associated with the operation this ack is acknowledging.
errorThe human-readable description associated with the error or status update.
statusThe status code related to the error or status.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_arc()

int guac_protocol_send_arc ( guac_socket * socket,
const guac_layer * layer,
int x,
int y,
int radius,
double startAngle,
double endAngle,
int negative )

Sends an arc instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe destination layer.
xThe X coordinate of the center of the circle containing the arc.
yThe Y coordinate of the center of the circle containing the arc.
radiusThe radius of the circle containing the arc.
startAngleThe starting angle, in radians.
endAngleThe ending angle, in radians.
negativeZero if the arc should be drawn in order of increasing angle, non-zero otherwise.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_args()

int guac_protocol_send_args ( guac_socket * socket,
const char ** args )

Sends an args instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
argsThe NULL-terminated array of argument names (strings).
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_argv()

int guac_protocol_send_argv ( guac_socket * socket,
guac_stream * stream,
const char * mimetype,
const char * name )

Sends an argv instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use to send the connection parameter value.
streamThe stream to use to send the connection parameter value.
mimetypeThe mimetype of the connection parameter value being sent.
nameThe name of the connection parameter whose current value is being sent.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_audio()

int guac_protocol_send_audio ( guac_socket * socket,
const guac_stream * stream,
const char * mimetype )

Sends an audio instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use when sending the audio instruction.
streamThe stream to use for future audio data.
mimetypeThe mimetype of the audio data which will be sent over the given stream.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_blob()

int guac_protocol_send_blob ( guac_socket * socket,
const guac_stream * stream,
const void * data,
int count )

Writes a block of data to the currently in-progress blob which was already created.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
streamThe stream to use.
dataThe file data to write.
countThe number of bytes within the given buffer of file data that must be written.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_blobs()

int guac_protocol_send_blobs ( guac_socket * socket,
const guac_stream * stream,
const void * data,
int count )

Sends a series of blob instructions, splitting the given data across the number of instructions required to ensure the size of each blob does not exceed GUAC_PROTOCOL_BLOB_MAX_LENGTH.

If the size of data provided is zero, no blob instructions are sent.

If an error occurs sending any blob instruction, a non-zero value is returned, guac_error is set appropriately, and no further blobs are sent.

See also
GUAC_PROTOCOL_BLOB_MAX_LENGTH
Parameters
socketThe guac_socket connection to use to send the blob instructions.
streamThe stream to associate with each blob sent.
dataThe data which should be sent using the required number of blob instructions.
countThe number of bytes within the given buffer of data that must be written.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_body()

int guac_protocol_send_body ( guac_socket * socket,
const guac_object * object,
const guac_stream * stream,
const char * mimetype,
const char * name )

Sends a body instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
objectThe object to associated with the stream being used.
streamThe stream to use.
mimetypeThe mimetype of the data being sent.
nameThe name of the stream whose body is being sent, as requested by a "get" instruction.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_cfill()

int guac_protocol_send_cfill ( guac_socket * socket,
guac_composite_mode mode,
const guac_layer * layer,
int r,
int g,
int b,
int a )

Sends a cfill instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
modeThe composite mode to use.
layerThe destination layer.
rThe red component of the color of the rectangle.
gThe green component of the color of the rectangle.
bThe blue component of the color of the rectangle.
aThe alpha (transparency) component of the color of the rectangle.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_clip()

int guac_protocol_send_clip ( guac_socket * socket,
const guac_layer * layer )

Sends a clip instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to set the clipping region of.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_clipboard()

int guac_protocol_send_clipboard ( guac_socket * socket,
const guac_stream * stream,
const char * mimetype )

Sends a clipboard instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
streamThe stream to use.
mimetypeThe mimetype of the clipboard data being sent.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_close()

int guac_protocol_send_close ( guac_socket * socket,
const guac_layer * layer )

Sends a close instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe destination layer.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_connect()

int guac_protocol_send_connect ( guac_socket * socket,
const char ** args )

Sends a connect instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
argsThe NULL-terminated array of argument values (strings).
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_copy()

int guac_protocol_send_copy ( guac_socket * socket,
const guac_layer * srcl,
int srcx,
int srcy,
int w,
int h,
guac_composite_mode mode,
const guac_layer * dstl,
int dstx,
int dsty )

Sends a copy instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
srclThe source layer.
srcxThe X coordinate of the source rectangle.
srcyThe Y coordinate of the source rectangle.
wThe width of the source rectangle.
hThe height of the source rectangle.
modeThe composite mode to use.
dstlThe destination layer.
dstxThe X coordinate of the destination, where the source rectangle should be copied.
dstyThe Y coordinate of the destination, where the source rectangle should be copied.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_cstroke()

int guac_protocol_send_cstroke ( guac_socket * socket,
guac_composite_mode mode,
const guac_layer * layer,
guac_line_cap_style cap,
guac_line_join_style join,
int thickness,
int r,
int g,
int b,
int a )

Sends a cstroke instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
modeThe composite mode to use.
layerThe destination layer.
capThe style of line cap to use when drawing the stroke.
joinThe style of line join to use when drawing the stroke.
thicknessThe thickness of the stroke in pixels.
rThe red component of the color of the rectangle.
gThe green component of the color of the rectangle.
bThe blue component of the color of the rectangle.
aThe alpha (transparency) component of the color of the rectangle.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_cursor()

int guac_protocol_send_cursor ( guac_socket * socket,
int x,
int y,
const guac_layer * srcl,
int srcx,
int srcy,
int w,
int h )

Sends a cursor instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
xThe X coordinate of the cursor hotspot.
yThe Y coordinate of the cursor hotspot.
srclThe source layer.
srcxThe X coordinate of the source rectangle.
srcyThe Y coordinate of the source rectangle.
wThe width of the source rectangle.
hThe height of the source rectangle.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_curve()

int guac_protocol_send_curve ( guac_socket * socket,
const guac_layer * layer,
int cp1x,
int cp1y,
int cp2x,
int cp2y,
int x,
int y )

Sends a curve instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe destination layer.
cp1xThe X coordinate of the first control point.
cp1yThe Y coordinate of the first control point.
cp2xThe X coordinate of the second control point.
cp2yThe Y coordinate of the second control point.
xThe X coordinate of the endpoint of the curve.
yThe Y coordinate of the endpoint of the curve.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_disconnect()

int guac_protocol_send_disconnect ( guac_socket * socket)

Sends a disconnect instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_dispose()

int guac_protocol_send_dispose ( guac_socket * socket,
const guac_layer * layer )

Sends a dispose instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to dispose.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_distort()

int guac_protocol_send_distort ( guac_socket * socket,
const guac_layer * layer,
double a,
double b,
double c,
double d,
double e,
double f )

Sends a distort instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to distort with the given transform matrix.
aThe first value of the affine transform matrix.
bThe second value of the affine transform matrix.
cThe third value of the affine transform matrix.
dThe fourth value of the affine transform matrix.
eThe fifth value of the affine transform matrix.
fThe sixth value of the affine transform matrix.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_end()

int guac_protocol_send_end ( guac_socket * socket,
const guac_stream * stream )

Sends an end instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
streamThe stream to use.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_error()

int guac_protocol_send_error ( guac_socket * socket,
const char * error,
guac_protocol_status status )

Sends an error instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
errorThe human-readable description associated with the error.
statusThe status code related to the error.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_file()

int guac_protocol_send_file ( guac_socket * socket,
const guac_stream * stream,
const char * mimetype,
const char * name )

Sends a file instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
streamThe stream to use.
mimetypeThe mimetype of the data being sent.
nameA name describing the file being sent.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_filesystem()

int guac_protocol_send_filesystem ( guac_socket * socket,
const guac_object * object,
const char * name )

Sends a filesystem instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
objectThe object representing the filesystem being exposed.
nameA name describing the filesystem being exposed.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_identity()

int guac_protocol_send_identity ( guac_socket * socket,
const guac_layer * layer )

Sends an identity instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe destination layer.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_img()

int guac_protocol_send_img ( guac_socket * socket,
const guac_stream * stream,
guac_composite_mode mode,
const guac_layer * layer,
const char * mimetype,
int x,
int y )

Sends an img instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use when sending the img instruction.
streamThe stream over which the image data will be sent.
modeThe composite mode to use when drawing the image over the destination layer.
layerThe destination layer.
mimetypeThe mimetype of the image data being sent.
xThe X coordinate of the upper-left corner of the destination rectangle within the destination layer, in pixels.
yThe Y coordinate of the upper-left corner of the destination rectangle within the destination layer, in pixels.
Returns
Zero if the instruction was successfully sent, non-zero on error.

◆ guac_protocol_send_key()

int guac_protocol_send_key ( guac_socket * socket,
int keysym,
int pressed,
guac_timestamp timestamp )

Sends a key instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
keysymThe X11 keysym of the key that was pressed or released.
pressedNon-zero if the key represented by the given keysym is currently pressed, zero if it is released.
timestampThe server timestamp (in milliseconds) at the point in time this key event was acknowledged.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_lfill()

int guac_protocol_send_lfill ( guac_socket * socket,
guac_composite_mode mode,
const guac_layer * layer,
const guac_layer * srcl )

Sends an lfill instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
modeThe composite mode to use.
layerThe destination layer.
srclThe source layer.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_line()

int guac_protocol_send_line ( guac_socket * socket,
const guac_layer * layer,
int x,
int y )

Sends a line instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe destination layer.
xThe X coordinate of the endpoint of the line.
yThe Y coordinate of the endpoint of the line.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_log()

int guac_protocol_send_log ( guac_socket * socket,
const char * format,
... )

Sends a log instruction over the given guac_socket connection.

This is mainly useful in debugging.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
formatA printf-style format string to log.
...Arguments to use when filling the format string for printing.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_lstroke()

int guac_protocol_send_lstroke ( guac_socket * socket,
guac_composite_mode mode,
const guac_layer * layer,
guac_line_cap_style cap,
guac_line_join_style join,
int thickness,
const guac_layer * srcl )

Sends an lstroke instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
modeThe composite mode to use.
layerThe destination layer.
capThe style of line cap to use when drawing the stroke.
joinThe style of line join to use when drawing the stroke.
thicknessThe thickness of the stroke in pixels.
srclThe source layer.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_mouse()

int guac_protocol_send_mouse ( guac_socket * socket,
int x,
int y,
int button_mask,
guac_timestamp timestamp )

Sends a mouse instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
xThe X coordinate of the current mouse position.
yThe Y coordinate of the current mouse position.
button_maskAn integer value representing the current state of each button, where the Nth bit within the integer is set to 1 if and only if the Nth mouse button is currently pressed. The lowest-order bit is the left mouse button, followed by the middle button, right button, and finally the up and down buttons of the scroll wheel.
See also
GUAC_CLIENT_MOUSE_LEFT
GUAC_CLIENT_MOUSE_MIDDLE
GUAC_CLIENT_MOUSE_RIGHT
GUAC_CLIENT_MOUSE_SCROLL_UP
GUAC_CLIENT_MOUSE_SCROLL_DOWN
Parameters
timestampThe server timestamp (in milliseconds) at the point in time this mouse position was acknowledged.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_move()

int guac_protocol_send_move ( guac_socket * socket,
const guac_layer * layer,
const guac_layer * parent,
int x,
int y,
int z )

Sends a move instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to move.
parentThe parent layer the specified layer will be positioned relative to.
xThe X coordinate of the layer.
yThe Y coordinate of the layer.
zThe Z index of the layer, relative to other layers in its parent.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_msg()

int guac_protocol_send_msg ( guac_socket * socket,
guac_message_type msg,
const char ** args )

Sends the given string over the socket to be displayed on the client.

Returns zero if the message was sent successfully or non-zero if an error occurs.

Parameters
socketThe guac_socket connection to send the message to.
msgThe message code to send to the client.
argsA null-terminated array of strings that will be provided to the client as part of the message, that the client may then place in the message, or null if the message requires no arguments.
Returns
Zero if the message is sent successfully; otherwise non-zero.

◆ guac_protocol_send_name()

int guac_protocol_send_name ( guac_socket * socket,
const char * name )

Sends a name instruction over the given guac_socket connection.

Parameters
socketThe guac_socket connection to use.
nameThe name to send within the name instruction.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_nest()

int guac_protocol_send_nest ( guac_socket * socket,
int index,
const char * data )

Sends a nest instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Deprecated
The "nest" instruction and the corresponding guac_socket implementation are no longer necessary, having been replaced by the streaming instructions ("blob", "ack", "end"). Code using nested sockets or the "nest" instruction should instead write to a normal socket directly.
Parameters
socketThe guac_socket connection to use.
indexThe integer index of the stream to send the protocol data over.
dataA string containing protocol data, which must be UTF-8 encoded and null-terminated.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_nop()

int guac_protocol_send_nop ( guac_socket * socket)

Sends a nop instruction (null-operation) over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_pipe()

int guac_protocol_send_pipe ( guac_socket * socket,
const guac_stream * stream,
const char * mimetype,
const char * name )

Sends a pipe instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
streamThe stream to use.
mimetypeThe mimetype of the data being sent.
nameAn arbitrary name uniquely identifying this pipe.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_pop()

int guac_protocol_send_pop ( guac_socket * socket,
const guac_layer * layer )

Sends a pop instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to set the clipping region of.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_push()

int guac_protocol_send_push ( guac_socket * socket,
const guac_layer * layer )

Sends a push instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to set the clipping region of.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_ready()

int guac_protocol_send_ready ( guac_socket * socket,
const char * id )

Sends a ready instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
idThe connection ID of the connection that is ready.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_rect()

int guac_protocol_send_rect ( guac_socket * socket,
const guac_layer * layer,
int x,
int y,
int width,
int height )

Sends a rect instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe destination layer.
xThe X coordinate of the rectangle.
yThe Y coordinate of the rectangle.
widthThe width of the rectangle.
heightThe height of the rectangle.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_required()

int guac_protocol_send_required ( guac_socket * socket,
const char ** required )

Sends a "required" instruction over the given guac_socket connection.

This instruction indicates to the client that one or more additional parameters are needed to continue the connection.

Parameters
socketThe guac_socket connection to which to send the instruction.
requiredA NULL-terminated array of required parameters.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_reset()

int guac_protocol_send_reset ( guac_socket * socket,
const guac_layer * layer )

Sends a reset instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to set the clipping region of.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_select()

int guac_protocol_send_select ( guac_socket * socket,
const char * protocol )

Sends a select instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
protocolThe protocol to request.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_set()

int guac_protocol_send_set ( guac_socket * socket,
const guac_layer * layer,
const char * name,
const char * value )

Sends a set instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to set the parameter of.
nameThe name of the parameter to set.
valueThe value to set the parameter to.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_set_int()

int guac_protocol_send_set_int ( guac_socket * socket,
const guac_layer * layer,
const char * name,
int value )

Sends a set instruction over the given guac_socket connection.

This function behaves identically to guac_protocol_send_set() except that the provided parameter value is an integer, rather than a string.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to set the parameter of.
nameThe name of the parameter to set.
valueThe value to set the parameter to.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_shade()

int guac_protocol_send_shade ( guac_socket * socket,
const guac_layer * layer,
int a )

Sends a shade instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to shade.
aThe alpha value of the layer.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_size()

int guac_protocol_send_size ( guac_socket * socket,
const guac_layer * layer,
int w,
int h )

Sends a size instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to resize.
wThe new width of the layer.
hThe new height of the layer.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_start()

int guac_protocol_send_start ( guac_socket * socket,
const guac_layer * layer,
int x,
int y )

Sends a start instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe destination layer.
xThe X coordinate of the first point of the subpath.
yThe Y coordinate of the first point of the subpath.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_sync()

int guac_protocol_send_sync ( guac_socket * socket,
guac_timestamp timestamp )

Sends a sync instruction over the given guac_socket connection.

The current time in milliseconds should be passed in as the timestamp.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
timestampThe current timestamp (in milliseconds).
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_touch()

int guac_protocol_send_touch ( guac_socket * socket,
int id,
int x,
int y,
int x_radius,
int y_radius,
double angle,
double force,
guac_timestamp timestamp )

Sends a touch instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
idAn arbitrary integer ID which uniquely identifies this contact relative to other active contacts.
xThe X coordinate of the center of the touch contact.
yThe Y coordinate of the center of the touch contact.
x_radiusThe X radius of the ellipse covering the general area of the touch contact, in pixels.
y_radiusThe Y radius of the ellipse covering the general area of the touch contact, in pixels.
angleThe rough angle of clockwise rotation of the general area of the touch contact, in degrees.
forceThe relative force exerted by the touch contact, where 0 is no force (the touch has been lifted) and 1 is maximum force (the maximum amount of force representable by the device).
timestampThe server timestamp (in milliseconds) at the point in time this touch event was acknowledged.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_transfer()

int guac_protocol_send_transfer ( guac_socket * socket,
const guac_layer * srcl,
int srcx,
int srcy,
int w,
int h,
guac_transfer_function fn,
const guac_layer * dstl,
int dstx,
int dsty )

Sends a transfer instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
srclThe source layer.
srcxThe X coordinate of the source rectangle.
srcyThe Y coordinate of the source rectangle.
wThe width of the source rectangle.
hThe height of the source rectangle.
fnThe transfer function to use.
dstlThe destination layer.
dstxThe X coordinate of the destination, where the source rectangle should be copied.
dstyThe Y coordinate of the destination, where the source rectangle should be copied.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_transform()

int guac_protocol_send_transform ( guac_socket * socket,
const guac_layer * layer,
double a,
double b,
double c,
double d,
double e,
double f )

Sends a transform instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
layerThe layer to apply the given transform matrix to.
aThe first value of the affine transform matrix.
bThe second value of the affine transform matrix.
cThe third value of the affine transform matrix.
dThe fourth value of the affine transform matrix.
eThe fifth value of the affine transform matrix.
fThe sixth value of the affine transform matrix.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_undefine()

int guac_protocol_send_undefine ( guac_socket * socket,
const guac_object * object )

Sends an undefine instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
objectThe object being undefined.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_send_video()

int guac_protocol_send_video ( guac_socket * socket,
const guac_stream * stream,
const guac_layer * layer,
const char * mimetype )

Sends a video instruction over the given guac_socket connection.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use when sending the video instruction.
streamThe stream to use for future video data.
layerThe destination layer on which the streamed video should be played.
mimetypeThe mimetype of the video data which will be sent over the given stream.
Returns
Zero on success, non-zero on error.

◆ guac_protocol_string_to_version()

guac_protocol_version guac_protocol_string_to_version ( const char * version_string)

Given a string representation of a protocol version, return the enum value of that protocol version, or GUAC_PROTOCOL_VERSION_UNKNOWN if the value is not a known version.

Parameters
version_stringThe string representation of the protocol version.
Returns
The enum value of the protocol version, or GUAC_PROTOCOL_VERSION_UNKNOWN if the provided version is not known.

◆ guac_protocol_version_to_string()

const char * guac_protocol_version_to_string ( guac_protocol_version version)

Given the enum value of the protocol version, return a pointer to the string representation of the version, or NULL if the version is unknown.

Parameters
versionThe enum value of the protocol version.
Returns
A pointer to the string representation of the protocol version, or NULL if the version is unknown.

◆ vguac_protocol_send_log()

int vguac_protocol_send_log ( guac_socket * socket,
const char * format,
va_list args )

Sends a log instruction over the given guac_socket connection.

This is mainly useful in debugging.

If an error occurs sending the instruction, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket connection to use.
formatA printf-style format string to log.
argsThe va_list containing the arguments to be used when filling the format string for printing.
Returns
Zero if the instruction was sent successfully, non-zero if an error occurs.