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

user	The user sending the "ack" instruction.
stream	The stream for which the "ack" was received.
error	An 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.
status	GUAC_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

user	The user that opened the audio stream.
stream	The stream object allocated by libguac to represent the audio stream opened by the user.
mimetype	The 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

user	The user that is sending this blob of data along the stream.
stream	The stream along which the blob was received. The semantics associated with this stream are determined by the manner of its creation.
data	The blob of data received.
length	The 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

user	The 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.
data	The 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

user	The user that opened the clipboard stream.
stream	The stream object allocated by libguac to represent the clipboard stream opened by the user.
mimetype	The 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

user	The user that sent the "end" instruction.
stream	The 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

user	The user that opened the file stream.
stream	The stream object allocated by libguac to represent the file stream opened by the user.
mimetype	The mimetype of the data that will be sent along the stream.
filename	The 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

user	The user requesting read access to the stream having the given name.
object	The object from which the given named stream is being requested.
name	The 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

user	The user joining the connection. The guac_client associated with the connection will already be populated within the user object.
argc	The number of arguments stored within argv.
argv	An 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

user	The user that sent the key event.
keysym	The X11 keysym of the key that was pressed or released.
pressed	Non-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

user	The 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

user	The user that sent the mouse event.
x	The 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.
y	The 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_mask	An 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

user	The user that opened the pipe stream.
stream	The stream object allocated by libguac to represent the pipe stream opened by the user.
mimetype	The mimetype of the data that will be sent along the stream.
name	The 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

user	The user requesting write access to the stream having the given name.
object	The object from which the given named stream is being requested.
stream	The stream along which the blobs which should be written to the named stream will be received.
mimetype	The mimetype of the data that will be received along the given stream.
name	The 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

user	The user whose desired display size has changed.
width	The desired width of the display, in pixels.
height	The 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

user	The user that sent the "sync" instruction.
timestamp	The timestamp contained within the sync instruction.

Returns

Zero if the sync event has been handled successfully, non-zero otherwise.