GUAC-1389: Add missing parameter comments to user-specific handlers. Clarify purpose of handlers.
This commit is contained in:
parent
c3a487f9ec
commit
dd0cecc7ea
@ -41,97 +41,365 @@
|
||||
*
|
||||
* @see guac_client_foreach_user()
|
||||
* @see guac_client_for_owner()
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @param data
|
||||
* The arbitrary data passed to guac_client_foreach_user() or
|
||||
* guac_client_for_owner().
|
||||
*
|
||||
* @return
|
||||
* 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.
|
||||
*/
|
||||
typedef void* guac_user_callback(guac_user* user, void* data);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole mouse events.
|
||||
* Handler for Guacamole mouse events, invoked when a "mouse" instruction has
|
||||
* been received from a user.
|
||||
*
|
||||
* @param user
|
||||
* The user that sent the mouse event.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @param 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 GUAC_CLIENT_MOUSE_LEFT
|
||||
* @see GUAC_CLIENT_MOUSE_MIDDLE
|
||||
* @see GUAC_CLIENT_MOUSE_RIGHT
|
||||
* @see GUAC_CLIENT_MOUSE_SCROLL_UP
|
||||
* @see GUAC_CLIENT_MOUSE_SCROLL_DOWN
|
||||
*
|
||||
* @return
|
||||
* Zero if the mouse event was handled successfully, or non-zero if an
|
||||
* error occurred.
|
||||
*/
|
||||
typedef int guac_user_mouse_handler(guac_user* user, int x, int y,
|
||||
int button_mask);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole key events.
|
||||
* Handler for Guacamole key events, invoked when a "key" event has been
|
||||
* received from a user.
|
||||
*
|
||||
* @param user
|
||||
* The user that sent the key event.
|
||||
*
|
||||
* @param keysym
|
||||
* The X11 keysym of the key that was pressed or released.
|
||||
*
|
||||
* @param pressed
|
||||
* Non-zero if the key represented by the given keysym is currently
|
||||
* pressed, zero if it is released.
|
||||
*
|
||||
* @return
|
||||
* Zero if the key event was handled successfully, or non-zero if an error
|
||||
* occurred.
|
||||
*/
|
||||
typedef int guac_user_key_handler(guac_user* user, int keysym, int pressed);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole clipboard events.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user that opened the clipboard stream.
|
||||
*
|
||||
* @param stream
|
||||
* The stream object allocated by libguac to represent the clipboard stream
|
||||
* opened by the user.
|
||||
*
|
||||
* @param mimetype
|
||||
* The mimetype of the data that will be sent along the stream.
|
||||
*
|
||||
* @return
|
||||
* Zero if the opening of the clipboard stream has been handled
|
||||
* successfully, or non-zero if an error occurs.
|
||||
*/
|
||||
typedef int guac_user_clipboard_handler(guac_user* user, guac_stream* stream,
|
||||
char* mimetype);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole screen size events.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user whose desired display size has changed.
|
||||
*
|
||||
* @param width
|
||||
* The desired width of the display, in pixels.
|
||||
*
|
||||
* @param height
|
||||
* The desired height of the display, in pixels.
|
||||
*
|
||||
* @return
|
||||
* Zero if the size event has been successfully handled, non-zero
|
||||
* otherwise.
|
||||
*/
|
||||
typedef int guac_user_size_handler(guac_user* user,
|
||||
int width, int height);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole file transfer events.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user that opened the file stream.
|
||||
*
|
||||
* @param stream
|
||||
* The stream object allocated by libguac to represent the file stream
|
||||
* opened by the user.
|
||||
*
|
||||
* @param mimetype
|
||||
* The mimetype of the data that will be sent along the stream.
|
||||
*
|
||||
* @param filename
|
||||
* The name of the file being transferred.
|
||||
*
|
||||
* @return
|
||||
* Zero if the opening of the file stream has been handled successfully, or
|
||||
* non-zero if an error occurs.
|
||||
*/
|
||||
typedef int guac_user_file_handler(guac_user* user, guac_stream* stream,
|
||||
char* mimetype, char* filename);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole pipe events.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user that opened the pipe stream.
|
||||
*
|
||||
* @param stream
|
||||
* The stream object allocated by libguac to represent the pipe stream
|
||||
* opened by the user.
|
||||
*
|
||||
* @param mimetype
|
||||
* The mimetype of the data that will be sent along the stream.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @return
|
||||
* Zero if the opening of the pipe stream has been handled successfully, or
|
||||
* non-zero if an error occurs.
|
||||
*/
|
||||
typedef int guac_user_pipe_handler(guac_user* user, guac_stream* stream,
|
||||
char* mimetype, char* name);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole stream blob events.
|
||||
* Handler for Guacamole stream blobs. Each blob originates from a "blob"
|
||||
* instruction which was associated with a previously-created stream.
|
||||
*
|
||||
* @param user
|
||||
* The user that is sending this blob of data along the stream.
|
||||
*
|
||||
* @param stream
|
||||
* The stream along which the blob was received. The semantics associated
|
||||
* with this stream are determined by the manner of its creation.
|
||||
*
|
||||
* @param data
|
||||
* The blob of data received.
|
||||
*
|
||||
* @param length
|
||||
* The number of bytes within the blob of data received.
|
||||
*
|
||||
* @return
|
||||
* Zero if the blob of data was successfully handled, non-zero otherwise.
|
||||
*/
|
||||
typedef int guac_user_blob_handler(guac_user* user, guac_stream* stream,
|
||||
void* data, int length);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole stream ack events.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user sending the "ack" instruction.
|
||||
*
|
||||
* @param stream
|
||||
* The stream for which the "ack" was received.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @return
|
||||
* Zero if the "ack" message was successfully handled, non-zero otherwise.
|
||||
*/
|
||||
typedef int guac_user_ack_handler(guac_user* user, guac_stream* stream,
|
||||
char* error, guac_protocol_status status);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole stream end events.
|
||||
* Handler for Guacamole stream "end" instructions. End instructions are sent
|
||||
* by the user when a stream is closing because its end has been reached.
|
||||
*
|
||||
* @param user
|
||||
* The user that sent the "end" instruction.
|
||||
*
|
||||
* @param stream
|
||||
* The stream that is being closed.
|
||||
*
|
||||
* @return
|
||||
* Zero if the end-of-stream condition has been sucessfully handled,
|
||||
* non-zero otherwise.
|
||||
*/
|
||||
typedef int guac_user_end_handler(guac_user* user, guac_stream* stream);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole audio format events.
|
||||
*/
|
||||
typedef int guac_user_audio_handler(guac_user* user, char* mimetype);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole video format events.
|
||||
*/
|
||||
typedef int guac_user_video_handler(guac_user* user, char* mimetype);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole join events. A join event is fired by the
|
||||
* guac_client whenever a guac_user joins the connection.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user joining the connection. The guac_client associated with the
|
||||
* connection will already be populated within the user object.
|
||||
*
|
||||
* @param argc
|
||||
* The number of arguments stored within argv.
|
||||
*
|
||||
* @param 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.
|
||||
*
|
||||
* @return
|
||||
* Zero if the user has been successfully initialized and should be allowed
|
||||
* to join the connection, non-zero otherwise.
|
||||
*/
|
||||
typedef int guac_user_join_handler(guac_user* user, int argc, char** argv);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole leave events. A leave event is fired by the
|
||||
* guac_client whenever a guac_user leaves the connection.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user that has left the connection.
|
||||
*
|
||||
* @return
|
||||
* Zero if the leave event has been successfully handled, non-zero
|
||||
* otherwise.
|
||||
*/
|
||||
typedef int guac_user_leave_handler(guac_user* user);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole sync events. A sync event is fired by the
|
||||
* guac_client whenever a guac_user responds to a sync instruction.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user that sent the "sync" instruction.
|
||||
*
|
||||
* @param timestamp
|
||||
* The timestamp contained within the sync instruction.
|
||||
*
|
||||
* @return
|
||||
* Zero if the sync event has been handled successfully, non-zero
|
||||
* otherwise.
|
||||
*/
|
||||
typedef int guac_user_sync_handler(guac_user* user, guac_timestamp timestamp);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole object get events.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user requesting read access to the stream having the given name.
|
||||
*
|
||||
* @param object
|
||||
* The object from which the given named stream is being requested.
|
||||
*
|
||||
* @param name
|
||||
* The name of the stream being requested.
|
||||
*
|
||||
* @return
|
||||
* Zero if the get request was successfully handled, non-zero otherwise.
|
||||
*/
|
||||
typedef int guac_user_get_handler(guac_user* user, guac_object* object,
|
||||
char* name);
|
||||
|
||||
/**
|
||||
* Handler for Guacamole object put events.
|
||||
* 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.
|
||||
*
|
||||
* @param user
|
||||
* The user requesting write access to the stream having the given name.
|
||||
*
|
||||
* @param object
|
||||
* The object from which the given named stream is being requested.
|
||||
*
|
||||
* @param stream
|
||||
* The stream along which the blobs which should be written to the named
|
||||
* stream will be received.
|
||||
*
|
||||
* @param mimetype
|
||||
* The mimetype of the data that will be received along the given stream.
|
||||
*
|
||||
* @param name
|
||||
* The name of the stream being requested.
|
||||
*
|
||||
* @return
|
||||
* Zero if the put request was successfully handled, non-zero otherwise.
|
||||
*/
|
||||
typedef int guac_user_put_handler(guac_user* user, guac_object* object,
|
||||
guac_stream* stream, char* mimetype, char* name);
|
||||
|
Loading…
Reference in New Issue
Block a user