recording.h (9309B)
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_RECORDING_H 21#define GUAC_RECORDING_H 22 23#include <guacamole/client.h> 24 25/** 26 * Provides functions and structures to be use for session recording. 27 * 28 * @file recording.h 29 */ 30 31/** 32 * The maximum numeric value allowed for the .1, .2, .3, etc. suffix appended 33 * to the end of the session recording filename if a recording having the 34 * requested name already exists. 35 */ 36#define GUAC_COMMON_RECORDING_MAX_SUFFIX 255 37 38/** 39 * The maximum length of the string containing a sequential numeric suffix 40 * between 1 and GUAC_COMMON_RECORDING_MAX_SUFFIX inclusive, in bytes, 41 * including NULL terminator. 42 */ 43#define GUAC_COMMON_RECORDING_MAX_SUFFIX_LENGTH 4 44 45/** 46 * The maximum overall length of the full path to the session recording file, 47 * including any additional suffix and NULL terminator, in bytes. 48 */ 49#define GUAC_COMMON_RECORDING_MAX_NAME_LENGTH 2048 50 51/** 52 * An in-progress session recording, attached to a guac_client instance such 53 * that output Guacamole instructions may be dynamically intercepted and 54 * written to a file. 55 */ 56typedef struct guac_recording { 57 58 /** 59 * The guac_socket which writes directly to the recording file, rather than 60 * to any particular user. 61 */ 62 guac_socket* socket; 63 64 /** 65 * Non-zero if output which is broadcast to each connected client 66 * (graphics, streams, etc.) should be included in the session recording, 67 * zero otherwise. Including output is necessary for any recording which 68 * must later be viewable as video. 69 */ 70 int include_output; 71 72 /** 73 * Non-zero if changes to mouse state, such as position and buttons pressed 74 * or released, should be included in the session recording, zero 75 * otherwise. Including mouse state is necessary for the mouse cursor to be 76 * rendered in any resulting video. 77 */ 78 int include_mouse; 79 80 /** 81 * Non-zero if multi-touch events should be included in the session 82 * recording, zero otherwise. Depending on whether the remote desktop will 83 * automatically provide graphical feedback for touches, including touch 84 * events may be necessary for multi-touch interactions to be rendered in 85 * any resulting video. 86 */ 87 int include_touch; 88 89 /** 90 * Non-zero if keys pressed and released should be included in the session 91 * recording, zero otherwise. Including key events within the recording may 92 * be necessary in certain auditing contexts, but should only be done with 93 * caution. Key events can easily contain sensitive information, such as 94 * passwords, credit card numbers, etc. 95 */ 96 int include_keys; 97 98} guac_recording; 99 100/** 101 * Replaces the socket of the given client such that all further Guacamole 102 * protocol output will be copied into a file within the given path and having 103 * the given name. If the create_path flag is non-zero, the given path will be 104 * created if it does not yet exist. If creation of the recording file or path 105 * fails, error messages will automatically be logged, and no recording will be 106 * written. The recording will automatically be closed once the client is 107 * freed. 108 * 109 * @param client 110 * The client whose output should be copied to a recording file. 111 * 112 * @param path 113 * The full absolute path to a directory in which the recording file should 114 * be created. 115 * 116 * @param name 117 * The base name to use for the recording file created within the specified 118 * path. 119 * 120 * @param create_path 121 * Zero if the specified path MUST exist for the recording file to be 122 * written, or non-zero if the path should be created if it does not yet 123 * exist. 124 * 125 * @param include_output 126 * Non-zero if output which is broadcast to each connected client 127 * (graphics, streams, etc.) should be included in the session recording, 128 * zero otherwise. Including output is necessary for any recording which 129 * must later be viewable as video. 130 * 131 * @param include_mouse 132 * Non-zero if changes to mouse state, such as position and buttons pressed 133 * or released, should be included in the session recording, zero 134 * otherwise. Including mouse state is necessary for the mouse cursor to be 135 * rendered in any resulting video. 136 * 137 * @param include_touch 138 * Non-zero if touch events should be included in the session recording, 139 * zero otherwise. Depending on whether the remote desktop will 140 * automatically provide graphical feedback for touches, including touch 141 * events may be necessary for multi-touch interactions to be rendered in 142 * any resulting video. 143 * 144 * @param include_keys 145 * Non-zero if keys pressed and released should be included in the session 146 * recording, zero otherwise. Including key events within the recording may 147 * be necessary in certain auditing contexts, but should only be done with 148 * caution. Key events can easily contain sensitive information, such as 149 * passwords, credit card numbers, etc. 150 * 151 * @return 152 * A new guac_recording structure representing the in-progress 153 * recording if the recording file has been successfully created and a 154 * recording will be written, NULL otherwise. 155 */ 156guac_recording* guac_recording_create(guac_client* client, 157 const char* path, const char* name, int create_path, 158 int include_output, int include_mouse, int include_touch, 159 int include_keys); 160 161/** 162 * Frees the resources associated with the given in-progress recording. Note 163 * that, due to the manner that recordings are attached to the guac_client, the 164 * underlying guac_socket is not freed. The guac_socket will be automatically 165 * freed when the guac_client is freed. 166 * 167 * @param recording 168 * The guac_recording to free. 169 */ 170void guac_recording_free(guac_recording* recording); 171 172/** 173 * Reports the current mouse position and button state within the recording. 174 * 175 * @param recording 176 * The guac_recording associated with the mouse that has moved. 177 * 178 * @param x 179 * The new X coordinate of the mouse cursor, in pixels. 180 * 181 * @param y 182 * The new Y coordinate of the mouse cursor, in pixels. 183 * 184 * @param button_mask 185 * An integer value representing the current state of each button, where 186 * the Nth bit within the integer is set to 1 if and only if the Nth mouse 187 * button is currently pressed. The lowest-order bit is the left mouse 188 * button, followed by the middle button, right button, and finally the up 189 * and down buttons of the scroll wheel. 190 * 191 * @see GUAC_CLIENT_MOUSE_LEFT 192 * @see GUAC_CLIENT_MOUSE_MIDDLE 193 * @see GUAC_CLIENT_MOUSE_RIGHT 194 * @see GUAC_CLIENT_MOUSE_SCROLL_UP 195 * @see GUAC_CLIENT_MOUSE_SCROLL_DOWN 196 */ 197void guac_recording_report_mouse(guac_recording* recording, 198 int x, int y, int button_mask); 199 200/** 201 * Reports the current state of a touch contact within the recording. 202 * 203 * @param recording 204 * The guac_recording associated with the touch contact that 205 * has changed state. 206 * 207 * @param id 208 * An arbitrary integer ID which uniquely identifies this contact relative 209 * to other active contacts. 210 * 211 * @param x 212 * The X coordinate of the center of the touch contact. 213 * 214 * @param y 215 * The Y coordinate of the center of the touch contact. 216 * 217 * @param x_radius 218 * The X radius of the ellipse covering the general area of the touch 219 * contact, in pixels. 220 * 221 * @param y_radius 222 * The Y radius of the ellipse covering the general area of the touch 223 * contact, in pixels. 224 * 225 * @param angle 226 * The rough angle of clockwise rotation of the general area of the touch 227 * contact, in degrees. 228 * 229 * @param force 230 * The relative force exerted by the touch contact, where 0 is no force 231 * (the touch has been lifted) and 1 is maximum force (the maximum amount 232 * of force representable by the device). 233 */ 234void guac_recording_report_touch(guac_recording* recording, 235 int id, int x, int y, int x_radius, int y_radius, 236 double angle, double force); 237 238/** 239 * Reports a change in the state of an individual key within the recording. 240 * 241 * @param recording 242 * The guac_recording associated with the key that was pressed or 243 * released. 244 * 245 * @param keysym 246 * The X11 keysym of the key that was pressed or released. 247 * 248 * @param pressed 249 * Non-zero if the key represented by the given keysym is currently 250 * pressed, zero if it is released. 251 */ 252void guac_recording_report_key(guac_recording* recording, 253 int keysym, int pressed); 254 255#endif 256