libguac  1.0.0
Typedefs
user-fntypes.h File Reference

Function type definitions related to the guac_user object. More...

Go to the source code of this file.

Typedefs

typedef void * guac_user_callback(guac_user *user, void *data)
 Callback which relates to a single guac_user at a time, along with arbitrary data. More...
 
typedef int guac_user_mouse_handler(guac_user *user, int x, int y, int button_mask)
 Handler for Guacamole mouse events, invoked when a "mouse" instruction has been received from a user. More...
 
typedef int guac_user_key_handler(guac_user *user, int keysym, int pressed)
 Handler for Guacamole key events, invoked when a "key" event has been received from a user. More...
 
typedef int guac_user_audio_handler(guac_user *user, guac_stream *stream, char *mimetype)
 Handler for Guacamole audio streams received from a user. More...
 
typedef int guac_user_clipboard_handler(guac_user *user, guac_stream *stream, char *mimetype)
 Handler for Guacamole clipboard streams received from a user. More...
 
typedef int guac_user_size_handler(guac_user *user, int width, int height)
 Handler for Guacamole size events, invoked when a "size" instruction has been received from a user. More...
 
typedef int guac_user_file_handler(guac_user *user, guac_stream *stream, char *mimetype, char *filename)
 Handler for Guacamole file streams received from a user. More...
 
typedef int guac_user_pipe_handler(guac_user *user, guac_stream *stream, char *mimetype, char *name)
 Handler for Guacamole pipe streams received from a user. More...
 
typedef int guac_user_blob_handler(guac_user *user, guac_stream *stream, void *data, int length)
 Handler for Guacamole stream blobs. More...
 
typedef int guac_user_ack_handler(guac_user *user, guac_stream *stream, char *error, guac_protocol_status status)
 Handler for Guacamole stream "ack" instructions. More...
 
typedef int guac_user_end_handler(guac_user *user, guac_stream *stream)
 Handler for Guacamole stream "end" instructions. More...
 
typedef int guac_user_join_handler(guac_user *user, int argc, char **argv)
 Handler for Guacamole join events. More...
 
typedef int guac_user_leave_handler(guac_user *user)
 Handler for Guacamole leave events. More...
 
typedef int guac_user_sync_handler(guac_user *user, guac_timestamp timestamp)
 Handler for Guacamole sync events. More...
 
typedef int guac_user_get_handler(guac_user *user, guac_object *object, char *name)
 Handler for Guacamole object get requests. More...
 
typedef int guac_user_put_handler(guac_user *user, guac_object *object, guac_stream *stream, char *mimetype, char *name)
 Handler for Guacamole object put requests. More...
 

Detailed Description

Function type definitions related to the guac_user object.

Typedef Documentation

◆ guac_user_ack_handler

typedef int guac_user_ack_handler(guac_user *user, guac_stream *stream, char *error, guac_protocol_status status)

Handler for Guacamole stream "ack" instructions.

A user will send "ack" instructions to acknowledge the successful receipt of blobs along a stream opened by the server, or to notify of errors. An "ack" with an error status implicitly closes the stream.

Parameters
userThe user sending the "ack" instruction.
streamThe stream for which the "ack" was received.
errorAn arbitrary, human-readable message describing the error that occurred, if any. If no error occurs, this will likely be blank, "SUCCESS", or similar. This value exists for the sake of readability, not for the sake of data interchange.
statusGUAC_PROTOCOL_STATUS_SUCCESS if the blob was received and handled successfully, or a different status code describing the problem if an error occurred and the stream has been implicitly closed.
Returns
Zero if the "ack" message was successfully handled, non-zero otherwise.

◆ guac_user_audio_handler

typedef int guac_user_audio_handler(guac_user *user, guac_stream *stream, char *mimetype)

Handler for Guacamole audio streams received from a user.

Each such audio stream begins when the user sends an "audio" instruction. To handle received data along this stream, implementations of this handler must assign blob and end handlers to the given stream object.

Parameters
userThe user that opened the audio stream.
streamThe stream object allocated by libguac to represent the audio stream opened by the user.
mimetypeThe mimetype of the data that will be sent along the stream.
Returns
Zero if the opening of the audio stream has been handled successfully, or non-zero if an error occurs.

◆ guac_user_blob_handler

typedef int guac_user_blob_handler(guac_user *user, guac_stream *stream, void *data, int length)

Handler for Guacamole stream blobs.

Each blob originates from a "blob" instruction which was associated with a previously-created stream.

Parameters
userThe user that is sending this blob of data along the stream.
streamThe stream along which the blob was received. The semantics associated with this stream are determined by the manner of its creation.
dataThe blob of data received.
lengthThe number of bytes within the blob of data received.
Returns
Zero if the blob of data was successfully handled, non-zero otherwise.

◆ guac_user_callback

typedef void* guac_user_callback(guac_user *user, void *data)

Callback which relates to a single guac_user at a time, along with arbitrary data.

See also
guac_client_foreach_user()
guac_client_for_owner()
Parameters
userThe user for which this callback was invoked. Depending on whether guac_client_foreach_user() or guac_client_for_owner() was called, this will either be the current user as the "foreach" iteration continues, or the owner of the connection. If guac_client_for_owner() was called for a connection which has no owner, this may be NULL.
dataThe arbitrary data passed to guac_client_foreach_user() or guac_client_for_owner().
Returns
An arbitrary return value, the semantics of which are determined by the implementation of the callback and the manner of its user. In the case of a callback provided to guac_client_foreach_user(), this value is always discarded.

◆ guac_user_clipboard_handler

typedef int guac_user_clipboard_handler(guac_user *user, guac_stream *stream, char *mimetype)

Handler for Guacamole clipboard streams received from a user.

Each such clipboard stream begins when the user sends a "clipboard" instruction. To handle received data along this stream, implementations of this handler must assign blob and end handlers to the given stream object.

Parameters
userThe user that opened the clipboard stream.
streamThe stream object allocated by libguac to represent the clipboard stream opened by the user.
mimetypeThe mimetype of the data that will be sent along the stream.
Returns
Zero if the opening of the clipboard stream has been handled successfully, or non-zero if an error occurs.

◆ guac_user_end_handler

typedef int guac_user_end_handler(guac_user *user, guac_stream *stream)

Handler for Guacamole stream "end" instructions.

End instructions are sent by the user when a stream is closing because its end has been reached.

Parameters
userThe user that sent the "end" instruction.
streamThe stream that is being closed.
Returns
Zero if the end-of-stream condition has been sucessfully handled, non-zero otherwise.

◆ guac_user_file_handler

typedef int guac_user_file_handler(guac_user *user, guac_stream *stream, char *mimetype, char *filename)

Handler for Guacamole file streams received from a user.

Each such file stream begins when the user sends a "file" instruction. To handle received data along this stream, implementations of this handler must assign blob and end handlers to the given stream object.

Parameters
userThe user that opened the file stream.
streamThe stream object allocated by libguac to represent the file stream opened by the user.
mimetypeThe mimetype of the data that will be sent along the stream.
filenameThe name of the file being transferred.
Returns
Zero if the opening of the file stream has been handled successfully, or non-zero if an error occurs.

◆ guac_user_get_handler

typedef int guac_user_get_handler(guac_user *user, guac_object *object, char *name)

Handler for Guacamole object get requests.

The semantics of the stream which will be created in response to the request are determined by the type of the object and the name of the stream requested. It is up to the implementation of this handler to then respond with a "body" instruction that begins the requested stream.

Parameters
userThe user requesting read access to the stream having the given name.
objectThe object from which the given named stream is being requested.
nameThe name of the stream being requested.
Returns
Zero if the get request was successfully handled, non-zero otherwise.

◆ guac_user_join_handler

typedef int guac_user_join_handler(guac_user *user, int argc, char **argv)

Handler for Guacamole join events.

A join event is fired by the guac_client whenever a guac_user joins the connection. There is no instruction associated with a join event.

Implementations of the join handler MUST NOT use the client-level broadcast socket, nor invoke guac_client_foreach_user() or guac_client_for_owner(). Doing so will result in undefined behavior, including segfaults.

Parameters
userThe user joining the connection. The guac_client associated with the connection will already be populated within the user object.
argcThe number of arguments stored within argv.
argvAn array of all arguments provided by the user when they joined. These arguments must correspond to the argument names declared when the guac_client was initialized. If the number of arguments does not match the number of argument names declared, then the joining user has violated the Guacamole protocol.
Returns
Zero if the user has been successfully initialized and should be allowed to join the connection, non-zero otherwise.

◆ guac_user_key_handler

typedef int guac_user_key_handler(guac_user *user, int keysym, int pressed)

Handler for Guacamole key events, invoked when a "key" event has been received from a user.

Parameters
userThe user that sent the key event.
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.
Returns
Zero if the key event was handled successfully, or non-zero if an error occurred.

◆ guac_user_leave_handler

typedef int guac_user_leave_handler(guac_user *user)

Handler for Guacamole leave events.

A leave event is fired by the guac_client whenever a guac_user leaves the connection. There is no instruction associated with a leave event.

Implementations of the leave handler MUST NOT use the client-level broadcast socket, nor invoke guac_client_foreach_user() or guac_client_for_owner(). Doing so will result in undefined behavior, including segfaults.

Parameters
userThe user that has left the connection.
Returns
Zero if the leave event has been successfully handled, non-zero otherwise.

◆ guac_user_mouse_handler

typedef int guac_user_mouse_handler(guac_user *user, int x, int y, int button_mask)

Handler for Guacamole mouse events, invoked when a "mouse" instruction has been received from a user.

Parameters
userThe user that sent the mouse event.
xThe X coordinate of the mouse within the display when the event occurred, in pixels. This value is not guaranteed to be within the bounds of the display area.
yThe Y coordinate of the mouse within the display when the event occurred, in pixels. This value is not guaranteed to be within the bounds of the display area.
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
Returns
Zero if the mouse event was handled successfully, or non-zero if an error occurred.

◆ guac_user_pipe_handler

typedef int guac_user_pipe_handler(guac_user *user, guac_stream *stream, char *mimetype, char *name)

Handler for Guacamole pipe streams received from a user.

Pipe streams are unidirectional, arbitrary, named pipes. Each such pipe stream begins when the user sends a "pipe" instruction. To handle received data along this stream, implementations of this handler must assign blob and end handlers to the given stream object.

Parameters
userThe user that opened the pipe stream.
streamThe stream object allocated by libguac to represent the pipe stream opened by the user.
mimetypeThe mimetype of the data that will be sent along the stream.
nameThe arbitrary name assigned to this pipe. It is up to the implementation of this handler and the application containing the Guacamole client to determine the semantics of a pipe stream having this name.
Returns
Zero if the opening of the pipe stream has been handled successfully, or non-zero if an error occurs.

◆ guac_user_put_handler

typedef int guac_user_put_handler(guac_user *user, guac_object *object, guac_stream *stream, char *mimetype, char *name)

Handler for Guacamole object put requests.

Put requests implicitly create a stream, the semantics of which are determined by the type of the object and the name of the stream requested.

Parameters
userThe user requesting write access to the stream having the given name.
objectThe object from which the given named stream is being requested.
streamThe stream along which the blobs which should be written to the named stream will be received.
mimetypeThe mimetype of the data that will be received along the given stream.
nameThe name of the stream being requested.
Returns
Zero if the put request was successfully handled, non-zero otherwise.

◆ guac_user_size_handler

typedef int guac_user_size_handler(guac_user *user, int width, int height)

Handler for Guacamole size events, invoked when a "size" instruction has been received from a user.

A "size" instruction indicates that the desired display size has changed.

Parameters
userThe user whose desired display size has changed.
widthThe desired width of the display, in pixels.
heightThe desired height of the display, in pixels.
Returns
Zero if the size event has been successfully handled, non-zero otherwise.

◆ guac_user_sync_handler

typedef int guac_user_sync_handler(guac_user *user, guac_timestamp timestamp)

Handler for Guacamole sync events.

A sync event is fired by the guac_client whenever a guac_user responds to a "sync" instruction. Sync instructions are sent by the Guacamole server to mark the logical end of a frame, and to inform the Guacamole client that all data up to a particular point in time has been sent. The response from the Guacamole client similarly indicates that all data received up to a particular point in server time has been handled.

Parameters
userThe user that sent the "sync" instruction.
timestampThe timestamp contained within the sync instruction.
Returns
Zero if the sync event has been handled successfully, non-zero otherwise.