user-fntypes.h (17712B)
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20#ifndef _GUAC_USER_FNTYPES_H 21#define _GUAC_USER_FNTYPES_H 22 23/** 24 * Function type definitions related to the guac_user object. 25 * 26 * @file user-fntypes.h 27 */ 28 29#include "object-types.h" 30#include "protocol-types.h" 31#include "stream-types.h" 32#include "timestamp-types.h" 33#include "user-types.h" 34 35/** 36 * Callback which relates to a single guac_user at a time, along with arbitrary 37 * data. 38 * 39 * @see guac_client_foreach_user() 40 * @see guac_client_for_owner() 41 * 42 * @param user 43 * The user for which this callback was invoked. Depending on whether 44 * guac_client_foreach_user() or guac_client_for_owner() was called, this 45 * will either be the current user as the "foreach" iteration continues, 46 * or the owner of the connection. If guac_client_for_owner() was called 47 * for a connection which has no owner, this may be NULL. 48 * 49 * @param data 50 * The arbitrary data passed to guac_client_foreach_user() or 51 * guac_client_for_owner(). 52 * 53 * @return 54 * An arbitrary return value, the semantics of which are determined by the 55 * implementation of the callback and the manner of its user. In the case 56 * of a callback provided to guac_client_foreach_user(), this value is 57 * always discarded. 58 */ 59typedef void* guac_user_callback(guac_user* user, void* data); 60 61/** 62 * Handler for Guacamole mouse events, invoked when a "mouse" instruction has 63 * been received from a user. 64 * 65 * @param user 66 * The user that sent the mouse event. 67 * 68 * @param x 69 * The X coordinate of the mouse within the display when the event 70 * occurred, in pixels. This value is not guaranteed to be within the 71 * bounds of the display area. 72 * 73 * @param y 74 * The Y coordinate of the mouse within the display when the event 75 * occurred, in pixels. This value is not guaranteed to be within the 76 * bounds of the display area. 77 * 78 * @param button_mask 79 * An integer value representing the current state of each button, where 80 * the Nth bit within the integer is set to 1 if and only if the Nth mouse 81 * button is currently pressed. The lowest-order bit is the left mouse 82 * button, followed by the middle button, right button, and finally the up 83 * and down buttons of the scroll wheel. 84 * 85 * @see GUAC_CLIENT_MOUSE_LEFT 86 * @see GUAC_CLIENT_MOUSE_MIDDLE 87 * @see GUAC_CLIENT_MOUSE_RIGHT 88 * @see GUAC_CLIENT_MOUSE_SCROLL_UP 89 * @see GUAC_CLIENT_MOUSE_SCROLL_DOWN 90 * 91 * @return 92 * Zero if the mouse event was handled successfully, or non-zero if an 93 * error occurred. 94 */ 95typedef int guac_user_mouse_handler(guac_user* user, int x, int y, 96 int button_mask); 97 98/** 99 * Handler for Guacamole touch events, invoked when a "touch" instruction has 100 * been received from a user. 101 * 102 * @param user 103 * The user that sent the touch event. 104 * 105 * @param id 106 * An arbitrary integer ID which uniquely identifies this contact relative 107 * to other active contacts. 108 * 109 * @param x 110 * The X coordinate of the center of the touch contact within the display 111 * when the event occurred, in pixels. This value is not guaranteed to be 112 * within the bounds of the display area. 113 * 114 * @param y 115 * The Y coordinate of the center of the touch contact within the display 116 * when the event occurred, in pixels. This value is not guaranteed to be 117 * within the bounds of the display area. 118 * 119 * @param x_radius 120 * The X radius of the ellipse covering the general area of the touch 121 * contact, in pixels. 122 * 123 * @param y_radius 124 * The Y radius of the ellipse covering the general area of the touch 125 * contact, in pixels. 126 * 127 * @param angle 128 * The rough angle of clockwise rotation of the general area of the touch 129 * contact, in degrees. 130 * 131 * @param force 132 * The relative force exerted by the touch contact, where 0 is no force 133 * (the touch has been lifted) and 1 is maximum force (the maximum amount 134 * of force representable by the device). 135 * 136 * @return 137 * Zero if the touch event was handled successfully, or non-zero if an 138 * error occurred. 139 */ 140typedef int guac_user_touch_handler(guac_user* user, int id, int x, int y, 141 int x_radius, int y_radius, double angle, double force); 142 143/** 144 * Handler for Guacamole key events, invoked when a "key" event has been 145 * received from a user. 146 * 147 * @param user 148 * The user that sent the key event. 149 * 150 * @param keysym 151 * The X11 keysym of the key that was pressed or released. 152 * 153 * @param pressed 154 * Non-zero if the key represented by the given keysym is currently 155 * pressed, zero if it is released. 156 * 157 * @return 158 * Zero if the key event was handled successfully, or non-zero if an error 159 * occurred. 160 */ 161typedef int guac_user_key_handler(guac_user* user, int keysym, int pressed); 162 163/** 164 * Handler for Guacamole audio streams received from a user. Each such audio 165 * stream begins when the user sends an "audio" instruction. To handle received 166 * data along this stream, implementations of this handler must assign blob and 167 * end handlers to the given stream object. 168 * 169 * @param user 170 * The user that opened the audio stream. 171 * 172 * @param stream 173 * The stream object allocated by libguac to represent the audio stream 174 * opened by the user. 175 * 176 * @param mimetype 177 * The mimetype of the data that will be sent along the stream. 178 * 179 * @return 180 * Zero if the opening of the audio stream has been handled successfully, 181 * or non-zero if an error occurs. 182 */ 183typedef int guac_user_audio_handler(guac_user* user, guac_stream* stream, 184 char* mimetype); 185 186/** 187 * Handler for Guacamole clipboard streams received from a user. Each such 188 * clipboard stream begins when the user sends a "clipboard" instruction. To 189 * handle received data along this stream, implementations of this handler 190 * must assign blob and end handlers to the given stream object. 191 * 192 * @param user 193 * The user that opened the clipboard stream. 194 * 195 * @param stream 196 * The stream object allocated by libguac to represent the clipboard stream 197 * opened by the user. 198 * 199 * @param mimetype 200 * The mimetype of the data that will be sent along the stream. 201 * 202 * @return 203 * Zero if the opening of the clipboard stream has been handled 204 * successfully, or non-zero if an error occurs. 205 */ 206typedef int guac_user_clipboard_handler(guac_user* user, guac_stream* stream, 207 char* mimetype); 208 209/** 210 * Handler for Guacamole size events, invoked when a "size" instruction has 211 * been received from a user. A "size" instruction indicates that the desired 212 * display size has changed. 213 * 214 * @param user 215 * The user whose desired display size has changed. 216 * 217 * @param width 218 * The desired width of the display, in pixels. 219 * 220 * @param height 221 * The desired height of the display, in pixels. 222 * 223 * @return 224 * Zero if the size event has been successfully handled, non-zero 225 * otherwise. 226 */ 227typedef int guac_user_size_handler(guac_user* user, 228 int width, int height); 229 230/** 231 * Handler for Guacamole file streams received from a user. Each such file 232 * stream begins when the user sends a "file" instruction. To handle received 233 * data along this stream, implementations of this handler must assign blob and 234 * end handlers to the given stream object. 235 * 236 * @param user 237 * The user that opened the file stream. 238 * 239 * @param stream 240 * The stream object allocated by libguac to represent the file stream 241 * opened by the user. 242 * 243 * @param mimetype 244 * The mimetype of the data that will be sent along the stream. 245 * 246 * @param filename 247 * The name of the file being transferred. 248 * 249 * @return 250 * Zero if the opening of the file stream has been handled successfully, or 251 * non-zero if an error occurs. 252 */ 253typedef int guac_user_file_handler(guac_user* user, guac_stream* stream, 254 char* mimetype, char* filename); 255 256/** 257 * Handler for Guacamole pipe streams received from a user. Pipe streams are 258 * unidirectional, arbitrary, named pipes. Each such pipe stream begins when 259 * the user sends a "pipe" instruction. To handle received data along this 260 * stream, implementations of this handler must assign blob and end handlers to 261 * the given stream object. 262 * 263 * @param user 264 * The user that opened the pipe stream. 265 * 266 * @param stream 267 * The stream object allocated by libguac to represent the pipe stream 268 * opened by the user. 269 * 270 * @param mimetype 271 * The mimetype of the data that will be sent along the stream. 272 * 273 * @param name 274 * The arbitrary name assigned to this pipe. It is up to the implementation 275 * of this handler and the application containing the Guacamole client to 276 * determine the semantics of a pipe stream having this name. 277 * 278 * @return 279 * Zero if the opening of the pipe stream has been handled successfully, or 280 * non-zero if an error occurs. 281 */ 282typedef int guac_user_pipe_handler(guac_user* user, guac_stream* stream, 283 char* mimetype, char* name); 284 285/** 286 * Handler for Guacamole argument value (argv) streams received from a user. 287 * Argument value streams are real-time revisions to the connection parameters 288 * of an in-progress connection. Each such argument value stream begins when 289 * the user sends a "argv" instruction. To handle received data along this 290 * stream, implementations of this handler must assign blob and end handlers to 291 * the given stream object. 292 * 293 * @param user 294 * The user that opened the argument value stream. 295 * 296 * @param stream 297 * The stream object allocated by libguac to represent the argument value 298 * stream opened by the user. 299 * 300 * @param mimetype 301 * The mimetype of the data that will be sent along the stream. 302 * 303 * @param name 304 * The name of the connection parameter being updated. It is up to the 305 * implementation of this handler to decide whether and how to update a 306 * connection parameter. 307 * 308 * @return 309 * Zero if the opening of the argument value stream has been handled 310 * successfully, or non-zero if an error occurs. 311 */ 312typedef int guac_user_argv_handler(guac_user* user, guac_stream* stream, 313 char* mimetype, char* name); 314 315/** 316 * Handler for Guacamole stream blobs. Each blob originates from a "blob" 317 * instruction which was associated with a previously-created stream. 318 * 319 * @param user 320 * The user that is sending this blob of data along the stream. 321 * 322 * @param stream 323 * The stream along which the blob was received. The semantics associated 324 * with this stream are determined by the manner of its creation. 325 * 326 * @param data 327 * The blob of data received. 328 * 329 * @param length 330 * The number of bytes within the blob of data received. 331 * 332 * @return 333 * Zero if the blob of data was successfully handled, non-zero otherwise. 334 */ 335typedef int guac_user_blob_handler(guac_user* user, guac_stream* stream, 336 void* data, int length); 337 338/** 339 * Handler for Guacamole stream "ack" instructions. A user will send "ack" 340 * instructions to acknowledge the successful receipt of blobs along a stream 341 * opened by the server, or to notify of errors. An "ack" with an error status 342 * implicitly closes the stream. 343 * 344 * @param user 345 * The user sending the "ack" instruction. 346 * 347 * @param stream 348 * The stream for which the "ack" was received. 349 * 350 * @param error 351 * An arbitrary, human-readable message describing the error that 352 * occurred, if any. If no error occurs, this will likely be blank, 353 * "SUCCESS", or similar. This value exists for the sake of readability, 354 * not for the sake of data interchange. 355 * 356 * @param status 357 * GUAC_PROTOCOL_STATUS_SUCCESS if the blob was received and handled 358 * successfully, or a different status code describing the problem if an 359 * error occurred and the stream has been implicitly closed. 360 * 361 * @return 362 * Zero if the "ack" message was successfully handled, non-zero otherwise. 363 */ 364typedef int guac_user_ack_handler(guac_user* user, guac_stream* stream, 365 char* error, guac_protocol_status status); 366 367/** 368 * Handler for Guacamole stream "end" instructions. End instructions are sent 369 * by the user when a stream is closing because its end has been reached. 370 * 371 * @param user 372 * The user that sent the "end" instruction. 373 * 374 * @param stream 375 * The stream that is being closed. 376 * 377 * @return 378 * Zero if the end-of-stream condition has been sucessfully handled, 379 * non-zero otherwise. 380 */ 381typedef int guac_user_end_handler(guac_user* user, guac_stream* stream); 382 383/** 384 * Handler for Guacamole join events. A join event is fired by the 385 * guac_client whenever a guac_user joins the connection. There is no 386 * instruction associated with a join event. 387 * 388 * Implementations of the join handler MUST NOT use the client-level 389 * broadcast socket, nor invoke guac_client_foreach_user() or 390 * guac_client_for_owner(). Doing so will result in undefined behavior, 391 * including segfaults. 392 * 393 * @param user 394 * The user joining the connection. The guac_client associated with the 395 * connection will already be populated within the user object. 396 * 397 * @param argc 398 * The number of arguments stored within argv. 399 * 400 * @param argv 401 * An array of all arguments provided by the user when they joined. These 402 * arguments must correspond to the argument names declared when the 403 * guac_client was initialized. If the number of arguments does not match 404 * the number of argument names declared, then the joining user has 405 * violated the Guacamole protocol. 406 * 407 * @return 408 * Zero if the user has been successfully initialized and should be allowed 409 * to join the connection, non-zero otherwise. 410 */ 411typedef int guac_user_join_handler(guac_user* user, int argc, char** argv); 412 413/** 414 * Handler for Guacamole leave events. A leave event is fired by the 415 * guac_client whenever a guac_user leaves the connection. There is no 416 * instruction associated with a leave event. 417 * 418 * Implementations of the leave handler MUST NOT use the client-level 419 * broadcast socket, nor invoke guac_client_foreach_user() or 420 * guac_client_for_owner(). Doing so will result in undefined behavior, 421 * including segfaults. 422 * 423 * @param user 424 * The user that has left the connection. 425 * 426 * @return 427 * Zero if the leave event has been successfully handled, non-zero 428 * otherwise. 429 */ 430typedef int guac_user_leave_handler(guac_user* user); 431 432/** 433 * Handler for Guacamole sync events. A sync event is fired by the 434 * guac_client whenever a guac_user responds to a "sync" instruction. Sync 435 * instructions are sent by the Guacamole server to mark the logical end of a 436 * frame, and to inform the Guacamole client that all data up to a particular 437 * point in time has been sent. The response from the Guacamole client 438 * similarly indicates that all data received up to a particular point in 439 * server time has been handled. 440 * 441 * @param user 442 * The user that sent the "sync" instruction. 443 * 444 * @param timestamp 445 * The timestamp contained within the sync instruction. 446 * 447 * @return 448 * Zero if the sync event has been handled successfully, non-zero 449 * otherwise. 450 */ 451typedef int guac_user_sync_handler(guac_user* user, guac_timestamp timestamp); 452 453/** 454 * Handler for Guacamole object get requests. The semantics of the stream 455 * which will be created in response to the request are determined by the type 456 * of the object and the name of the stream requested. It is up to the 457 * implementation of this handler to then respond with a "body" instruction 458 * that begins the requested stream. 459 * 460 * @param user 461 * The user requesting read access to the stream having the given name. 462 * 463 * @param object 464 * The object from which the given named stream is being requested. 465 * 466 * @param name 467 * The name of the stream being requested. 468 * 469 * @return 470 * Zero if the get request was successfully handled, non-zero otherwise. 471 */ 472typedef int guac_user_get_handler(guac_user* user, guac_object* object, 473 char* name); 474 475/** 476 * Handler for Guacamole object put requests. Put requests implicitly create a 477 * stream, the semantics of which are determined by the type of the object 478 * and the name of the stream requested. 479 * 480 * @param user 481 * The user requesting write access to the stream having the given name. 482 * 483 * @param object 484 * The object from which the given named stream is being requested. 485 * 486 * @param stream 487 * The stream along which the blobs which should be written to the named 488 * stream will be received. 489 * 490 * @param mimetype 491 * The mimetype of the data that will be received along the given stream. 492 * 493 * @param name 494 * The name of the stream being requested. 495 * 496 * @return 497 * Zero if the put request was successfully handled, non-zero otherwise. 498 */ 499typedef int guac_user_put_handler(guac_user* user, guac_object* object, 500 guac_stream* stream, char* mimetype, char* name); 501 502#endif 503