keyboard.h (11103B)
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_RDP_KEYBOARD_H 21#define GUAC_RDP_KEYBOARD_H 22 23#include "keymap.h" 24 25#include <freerdp/freerdp.h> 26#include <guacamole/client.h> 27 28/** 29 * The maximum number of distinct keysyms that any particular keyboard may support. 30 */ 31#define GUAC_RDP_KEYBOARD_MAX_KEYSYMS 1024 32 33/** 34 * The maximum number of unique modifier variations that any particular keysym 35 * may define. For example, on a US English keyboard, an uppercase "A" may be 36 * typed by pressing Shift+A with Caps Lock unset, or by pressing A with Caps 37 * Lock set (two variations). 38 */ 39#define GUAC_RDP_KEY_MAX_DEFINITIONS 4 40 41/** 42 * All possible sources of RDP key events tracked by guac_rdp_keyboard. 43 */ 44typedef enum guac_rdp_key_source { 45 46 /** 47 * The key event was received directly from the Guacamole client via a 48 * "key" instruction. 49 */ 50 GUAC_RDP_KEY_SOURCE_CLIENT = 0, 51 52 /** 53 * The key event is being synthesized internally within the RDP support. 54 */ 55 GUAC_RDP_KEY_SOURCE_SYNTHETIC = 1 56 57} guac_rdp_key_source; 58 59/** 60 * A representation of a single key within the overall local keyboard, 61 * including the definition of that key within the RDP server's keymap and 62 * whether the key is currently pressed locally. 63 */ 64typedef struct guac_rdp_key { 65 66 /** 67 * All definitions of this key within the RDP server's keymap (keyboard 68 * layout). Each definition describes which scancode corresponds to this 69 * key from the perspective of the RDP server, as well as which other 70 * scancodes must be pressed/released for this key to have the desired 71 * meaning. 72 */ 73 const guac_rdp_keysym_desc* definitions[GUAC_RDP_KEY_MAX_DEFINITIONS]; 74 75 /** 76 * The number of definitions within the definitions array. If this key does 77 * not exist within the RDP server's keymap, this will be 0. 78 */ 79 int num_definitions; 80 81 /** 82 * The definition of this key that is currently pressed. If this key is not 83 * currently pressed, this will be NULL. 84 */ 85 const guac_rdp_keysym_desc* pressed; 86 87 /** 88 * Whether this key is currently pressed by the user, and is included among 89 * the total tracked by user_pressed_keys within guac_rdp_keyboard. 90 */ 91 int user_pressed; 92 93} guac_rdp_key; 94 95/** 96 * The current keyboard state of an RDP session. 97 */ 98typedef struct guac_rdp_keyboard { 99 100 /** 101 * The guac_client associated with the RDP session whose keyboard state is 102 * being managed by this guac_rdp_keyboard. 103 */ 104 guac_client* client; 105 106 /** 107 * The local state of all known lock keys, as a bitwise OR of all RDP lock 108 * key flags. Legal flags are KBD_SYNC_SCROLL_LOCK, KBD_SYNC_NUM_LOCK, 109 * KBD_SYNC_CAPS_LOCK, and KBD_SYNC_KANA_LOCK. 110 */ 111 UINT32 lock_flags; 112 113 /** 114 * Whether the states of remote lock keys (Caps lock, Num lock, etc.) have 115 * been synchronized with local lock key states. 116 */ 117 int synchronized; 118 119 /** 120 * The number of keys stored within the keys array. 121 */ 122 unsigned int num_keys; 123 124 /** 125 * The local state of all keys, as well as the necessary information to 126 * translate received keysyms into scancodes or sequences of scancodes for 127 * RDP. The state of each key is updated based on received Guacamole key 128 * events, while the information describing the behavior and scancode 129 * mapping of each key is populated based on an associated keymap. 130 * 131 * Keys within this array are in arbitrary order. 132 */ 133 guac_rdp_key keys[GUAC_RDP_KEYBOARD_MAX_KEYSYMS]; 134 135 /** 136 * Lookup table into the overall keys array, locating the guac_rdp_key 137 * associated with any particular keysym. If a keysym has no corresponding 138 * guac_rdp_key within the keys array, its entry within this lookuptable 139 * will be NULL. 140 * 141 * The index of the key for a given keysym is determined based on a 142 * simple transformation of the keysym itself. Keysyms between 0x0000 and 143 * 0xFFFF inclusive are mapped to 0x00000 through 0x0FFFF, while keysyms 144 * between 0x1000000 and 0x100FFFF inclusive (keysyms which are derived 145 * from Unicode) are mapped to 0x10000 through 0x1FFFF. 146 */ 147 guac_rdp_key* keys_by_keysym[0x20000]; 148 149 /** 150 * The total number of keys that the user of the connection is currently 151 * holding down. This value indicates only the client-side keyboard state. 152 * It DOES NOT indicate the number of keys currently pressed within the RDP 153 * server. 154 */ 155 int user_pressed_keys; 156 157} guac_rdp_keyboard; 158 159/** 160 * Allocates a new guac_rdp_keyboard which manages the keyboard state of the 161 * RDP session associated with the given guac_client. Keyboard events will be 162 * dynamically translated from keysym to RDP scancode according to the provided 163 * keymap. The returned guac_rdp_keyboard must eventually be freed with 164 * guac_rdp_keyboard_free(). 165 * 166 * @param client 167 * The guac_client associated with the RDP session whose keyboard state is 168 * to be managed by the newly-allocated guac_rdp_keyboard. 169 * 170 * @param keymap 171 * The keymap which should be used to translate keyboard events. 172 * 173 * @return 174 * A newly-allocated guac_rdp_keyboard which manages the keyboard state 175 * for the RDP session associated given guac_client. 176 */ 177guac_rdp_keyboard* guac_rdp_keyboard_alloc(guac_client* client, 178 const guac_rdp_keymap* keymap); 179 180/** 181 * Frees all memory allocated for the given guac_rdp_keyboard. The 182 * guac_rdp_keyboard must have been previously allocated via 183 * guac_rdp_keyboard_alloc(). 184 * 185 * @param keyboard 186 * The guac_rdp_keyboard instance which should be freed. 187 */ 188void guac_rdp_keyboard_free(guac_rdp_keyboard* keyboard); 189 190/** 191 * Returns whether the given keysym is defined for the keyboard layout 192 * associated with the given keyboard. 193 * 194 * @param keyboard 195 * The guac_rdp_keyboard instance to check. 196 * 197 * @param keysym 198 * The keysym of the key being checked against the keyboard layout of the 199 * given keyboard. 200 * 201 * @return 202 * Non-zero if the key is explicitly defined within the keyboard layout of 203 * the given keyboard, zero otherwise. 204 */ 205int guac_rdp_keyboard_is_defined(guac_rdp_keyboard* keyboard, int keysym); 206 207/** 208 * Returns whether the key having the given keysym is currently pressed. 209 * 210 * @param keyboard 211 * The guac_rdp_keyboard instance to check. 212 * 213 * @param keysym 214 * The keysym of the key being checked. 215 * 216 * @return 217 * Non-zero if the key is currently pressed, zero otherwise. 218 */ 219int guac_rdp_keyboard_is_pressed(guac_rdp_keyboard* keyboard, int keysym); 220 221/** 222 * Returns the local state of all known modifier keys, as a bitwise OR of the 223 * modifier flags used by the keymaps. Alternative methods of producing the 224 * effect of certain modifiers, such as holding Ctrl+Alt for AltGr when a 225 * dedicated AltGr key is unavailable, are taken into account. 226 * 227 * @see GUAC_RDP_KEYMAP_MODIFIER_SHIFT 228 * @see GUAC_RDP_KEYMAP_MODIFIER_ALTGR 229 * 230 * @param keyboard 231 * The guac_rdp_keyboard associated with the current RDP session. 232 * 233 * @return 234 * The local state of all known modifier keys. 235 */ 236unsigned int guac_rdp_keyboard_get_modifier_flags(guac_rdp_keyboard* keyboard); 237 238/** 239 * Updates the local state of the lock keys (such as Caps lock or Num lock), 240 * synchronizing the remote state of those keys if it is expected to differ. 241 * 242 * @param keyboard 243 * The guac_rdp_keyboard associated with the current RDP session. 244 * 245 * @param set_flags 246 * The lock key flags which should be set. Legal flags are 247 * KBD_SYNC_SCROLL_LOCK, KBD_SYNC_NUM_LOCK, KBD_SYNC_CAPS_LOCK, and 248 * KBD_SYNC_KANA_LOCK. 249 * 250 * @param clear_flags 251 * The lock key flags which should be cleared. Legal flags are 252 * KBD_SYNC_SCROLL_LOCK, KBD_SYNC_NUM_LOCK, KBD_SYNC_CAPS_LOCK, and 253 * KBD_SYNC_KANA_LOCK. 254 */ 255void guac_rdp_keyboard_update_locks(guac_rdp_keyboard* keyboard, 256 unsigned int set_flags, unsigned int clear_flags); 257 258/** 259 * Updates the local state of the modifier keys (such as Shift or AltGr), 260 * synchronizing the remote state of those keys if it is expected to differ. 261 * Valid modifier flags are defined by keymap.h. 262 * 263 * @see GUAC_RDP_KEYMAP_MODIFIER_SHIFT 264 * @see GUAC_RDP_KEYMAP_MODIFIER_ALTGR 265 * 266 * @param keyboard 267 * The guac_rdp_keyboard associated with the current RDP session. 268 * 269 * @param set_flags 270 * The modifier key flags which should be set. 271 * 272 * @param clear_flags 273 * The modifier key flags which should be cleared. 274 */ 275void guac_rdp_keyboard_update_modifiers(guac_rdp_keyboard* keyboard, 276 unsigned int set_flags, unsigned int clear_flags); 277 278/** 279 * Updates the local state of the given keysym, sending the key events required 280 * to replicate that state remotely (on the RDP server). The key events sent 281 * will depend on the current keymap. 282 * 283 * @param keyboard 284 * The guac_rdp_keyboard associated with the current RDP session. 285 * 286 * @param keysym 287 * The keysym being pressed or released. 288 * 289 * @param pressed 290 * Zero if the keysym is being released, non-zero otherwise. 291 * 292 * @param source 293 * The source of the key event represented by this call to 294 * guac_rdp_keyboard_update_keysym(). 295 * 296 * @return 297 * Zero if the keys were successfully sent, non-zero otherwise. 298 */ 299int guac_rdp_keyboard_update_keysym(guac_rdp_keyboard* keyboard, 300 int keysym, int pressed, guac_rdp_key_source source); 301 302/** 303 * Releases all currently pressed keys, sending key release events to the RDP 304 * server as necessary. Lock states (Caps Lock, etc.) are not affected. 305 * 306 * @param keyboard 307 * The guac_rdp_keyboard associated with the current RDP session. 308 */ 309void guac_rdp_keyboard_reset(guac_rdp_keyboard* keyboard); 310 311/** 312 * Callback which is invoked by FreeRDP when the RDP server reports changes to 313 * keyboard lock status using a Server Set Keyboard Indicators PDU. 314 * 315 * @param context 316 * The rdpContext associated with the current RDP session. 317 * 318 * @param flags 319 * The remote state of all lock keys, as a bitwise OR of all RDP lock key 320 * flags. Legal flags are KBD_SYNC_SCROLL_LOCK, KBD_SYNC_NUM_LOCK, 321 * KBD_SYNC_CAPS_LOCK, and KBD_SYNC_KANA_LOCK. 322 * 323 * @return 324 * TRUE if successful, FALSE otherwise. 325 */ 326BOOL guac_rdp_keyboard_set_indicators(rdpContext* context, UINT16 flags); 327 328#endif 329