1 /*---------------------------------------------------------------------------* 2 Project: Caf� KBD RPL 3 File: kbd.h 4 5 Copyright (C) 2013 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 *---------------------------------------------------------------------------*/ 13 14 15 #ifndef __KBD_H__ 16 #define __KBD_H__ 17 18 #include <types.h> 19 #include <cafe/kbd/kbd_key_defs.h> 20 #include <cafe/kbd/kbd_hid_codes.h> 21 #include <cafe/os.h> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 28 ////////////////////////////////////////////////////////////////////////////// 29 // this symbol only exists for compatibility with old KBD API 30 #define KBD_MEM_SIZE 3264 31 32 ////////////////////////////////////////////////////////////////////////////// 33 34 // Up to 4 keyboards can be attached 35 #define KBD_MAX_CHANNELS (4) // valid channel numbers are 0-3 36 37 typedef enum _KBDEc // function return code 38 { 39 KBD_SUCCESS = 0, 40 KBD_ERR_OTHER = 1, // usually from HID error 41 KBD_ERR_NOT_INITIALIZED = 2, 42 KBD_ERR_ALREADY_INITIALIZED = 3, 43 KBD_ERR_BAD_VALUE = 4, // input argument out of range 44 KBD_ERR_BAD_STATUS = 5, // that is, keyboard disconnected 45 // KBD_ERR_BAD_POINTER = 6, 46 KBD_ERR_BUSY = 7 // for KBDSetLeds 47 } KBDEc; 48 49 typedef enum _KBDChanStatus // status bits may be OR-ed together 50 { 51 KBD_CS_OK = 0x00, 52 KBD_CS_DISCONNECTED = 0x01, 53 KBD_CS_ROLL_OVER = 0x02, 54 KBD_CS_ERROR = 0x04 55 } KBDChanStatus; 56 57 typedef u8 KBDChannel; 58 typedef u8 KBDHIDCode; 59 60 #define KBD_HID_NONE 0 // value returned when queue is empty 61 #define KBD_HID_OVERFLOW 255 // value returned when queue overflows 62 63 typedef enum _KBDKeyMode 64 { 65 KBD_KM_DOWN = 0x01, // 1 = key down, 0 = key up 66 KBD_KM_REPEAT = 0x02, // 1 = repeat key, 0 = initial key press 67 KBD_KM_NULL = 0x00 68 } KBDKeyMode; 69 70 #define KBD_KEY_MODE_UP(_key_mode) (!((_key_mode) & KBD_KM_DOWN)) 71 #define KBD_KEY_MODE_DOWN(_key_mode) ((_key_mode) & KBD_KM_DOWN) 72 #define KBD_KEY_MODE_REPEAT(_key_mode) ((_key_mode) & KBD_KM_REPEAT) 73 74 // xxx Some of these countries may disappear from this list. 75 // Others may be added. Names may be changed. 76 77 typedef enum _KBDCountryCode 78 { 79 KBD_CC_INTERNATIONAL, 80 KBD_CC_CANADIAN_BI, 81 KBD_CC_CANADIAN_FR, 82 KBD_CC_DANISH, 83 KBD_CC_FINNISH, 84 KBD_CC_FRENCH, 85 KBD_CC_GERMAN, 86 KBD_CC_GREEK, 87 KBD_CC_ITALIAN, 88 KBD_CC_JAPANESE, 89 KBD_CC_LATIN_AMERICAN, 90 KBD_CC_NETHERLANDS_DUTCH, 91 KBD_CC_NORWEGIAN, 92 KBD_CC_PORTUGUESE, 93 KBD_CC_SPANISH, 94 KBD_CC_SWEDISH, 95 KBD_CC_UNITED_KINGDOM, 96 KBD_CC_UNITED_STATES, 97 KBD_CC_RUSSIA, 98 KBD_CC_RESERVED 99 } KBDCountryCode; 100 101 #define KBD_NUM_COUNTRY_CODES KBD_CC_RESERVED 102 103 typedef enum _KBDModState // state bits may be OR-ed together 104 { 105 KBD_MS_CTRL = 0x0001, 106 KBD_MS_SHIFT = 0x0002, 107 KBD_MS_ALT = 0x0004, 108 KBD_MS_GUI = 0x0008, 109 KBD_MS_EXTRA = 0x0010, 110 KBD_MS_ALTGR = 0x0020, 111 KBD_MS_LANG1 = 0x0040, // (Hiragana) 112 KBD_MS_LANG2 = 0x0080, // (Katakana) 113 KBD_MS_NUM_LOCK = 0x0100, 114 KBD_MS_CAPS_LOCK = 0x0200, 115 KBD_MS_SCROLL_LOCK = 0x0400, 116 KBD_MS_SHIFTED_KEY = 0x0800, // when CTRL/ALT/GUI/EXTRA is on, allow shifted key to be returned 117 // (the default is that the base/unshifted key is returned) 118 KBD_MS_SET_ALL = 0x1000, // With KBDSetModState, allows setting of all bits 119 KBD_MS_NULL = 0x0000 120 } KBDModState; 121 122 // define alternate names for these 123 #define KBD_MS_HIRAGANA KBD_MS_LANG1 124 #define KBD_MS_KATAKANA KBD_MS_LANG2 125 126 // define convenient groups of state 127 #define KBD_MS_TRANSIENTS (KBD_MS_CTRL|KBD_MS_SHIFT|KBD_MS_ALT|KBD_MS_GUI|KBD_MS_EXTRA|KBD_MS_ALTGR) 128 #define KBD_MS_TOGGLES (KBD_MS_LANG1|KBD_MS_LANG2|KBD_MS_NUM_LOCK|KBD_MS_CAPS_LOCK|KBD_MS_SCROLL_LOCK) 129 130 typedef u16 KBDUnicode; // should it be wchar_t? xxx 131 132 // Indicate if a KBDUnicode value is private to KBD (special KBD internal value) 133 #define KBD_UC_IS_PRIVATE(uc) (((uc)>=0xf000 && (uc)<=0xF1FF) || ((uc)==0xFFFF)) 134 135 // This macro may be used to determine if a KBDUnicode is a modifier key 136 #define KBD_UC_IS_MODIFIER(uc) ((uc)>=0xf000 && (uc)<=0xf01f) 137 138 // These defines may be used to determine if a KBDUnicode 139 // value is a regular ASCII key from the keypad, and if so, to 140 // convert that value to the regular ASCII value 141 #define KBD_UC_IS_KP_REG_KEY(uc) (((uc)>=0xf100) && ((uc)<=0xf13f)) 142 #define KBD_KP_REG_KEY_TO_ASCII(uc) ((uc)&0x3f) 143 144 // Indicate if a key is a keypad number (digit) key with NUM LOCK on 145 #define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9))) 146 // Indicate if a key is a keypad number (digit) key with NUM LOCK off 147 #define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up))) 148 // Convert from NUM LOCK off digit key to NUM LOCK on digit key 149 #define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40)) 150 151 // Indicate if a ModState represents NUM LOCK == on 152 #define KBD_MS_IS_NUMLOCK(ms) (((ms)&KBD_MS_NUM_LOCK) && !((ms)&KBD_MS_SHIFT)) 153 154 // Indicate if a key is a private control Unicode, and convert to ASCII 155 #define KBD_UC_IS_CTRL_KEY(uc) (((uc)>=0xf1c0) && ((uc)<=0xf1df)) 156 #define KBD_CTRL_KEY_TO_ASCII(uc) ((uc)&0x1f) 157 158 typedef enum _KBDLedState 159 { 160 KBD_LED_NUM_LOCK = 0x01, 161 KBD_LED_CAPS_LOCK = 0x02, 162 KBD_LED_SCROLL_LOCK = 0x04, 163 KBD_LED_NULL = 0x00, 164 KBD_LED_RESERVED = 0x10 165 } KBDLedState; 166 167 //----------------------------------------------------------------------------- 168 // Structs: 169 170 typedef struct _KBDDevEvent // kbd attach/detach callbacks 171 { 172 KBDChannel channel; 173 } KBDDevEvent; 174 175 typedef struct _KBDKeyEvent // for key callback/getkey 176 { 177 KBDChannel channel; 178 KBDHIDCode hid; // USB HID code 179 KBDKeyMode mode; // for up/down/etc 180 KBDModState modState; // modifier state 181 KBDUnicode unicode; // unicode, if any 182 } KBDKeyEvent; 183 184 typedef struct _KBDLedEvent // kbd LED callback 185 { 186 KBDChannel channel; 187 KBDLedState leds; 188 KBDEc rc; 189 } KBDLedEvent; 190 191 typedef void (*KBDDevCallbackF) (KBDDevEvent*); 192 typedef void (*KBDKeyCallbackF) (KBDKeyEvent*); 193 typedef void (*KBDLedCallbackF) (KBDLedEvent*, void*); 194 195 196 typedef struct _KBDReport // HID report 197 { 198 u8 modifier; 199 u8 reserved; 200 u8 keycode[6]; 201 202 } KBDReport; 203 204 205 ////////////////////////////////////////////////////////////////////////////// 206 // Function calls 207 ////////////////////////////////////////////////////////////////////////////// 208 209 // for source compatibility, apps using old KBD API 210 void KBDInitRegionUS(void); 211 void KBDInitRegionJP(void); 212 void KBDInitRegionEU(void); 213 214 KBDEc KBDInit( // setup library 215 void*, // KBD mem, no longer required 216 KBDDevCallbackF, // callback for when keyboard is attached 217 KBDDevCallbackF, // callback for when keyboard is detached 218 KBDKeyCallbackF // callback for when key is pressed 219 ); 220 221 KBDEc KBDExit (void); // teardown library 222 223 KBDEc KBDSetLeds( // set LEDs on keyboard 224 KBDChannel, // keyboard number 225 KBDLedState // LED state to set 226 ); 227 228 KBDEc KBDSetLedsAsync( // set LED on keyboard, non-blocking with callback 229 KBDChannel, // keyboard number 230 KBDLedState, // LED state to set 231 KBDLedCallbackF, // completion callback funtion 232 void* // caller supplied parameter to pass to callback function 233 ); 234 235 KBDEc KBDSetLedsRetry( // set LEDs on keyboard with automatic retry 236 KBDChannel, // keyboard number 237 KBDLedState // LED state to set 238 ); 239 240 241 // Setup & Teardown APIs 242 KBDEc KBDSetup( // setup library 243 KBDDevCallbackF, // callback for when keyboard is attached 244 KBDDevCallbackF, // callback for when keyboard is detached 245 KBDKeyCallbackF // callback for when key is pressed 246 ); 247 248 KBDEc KBDTeardown (void); // teardown library 249 250 251 // Runtime APIs 252 KBDEc KBDGetChannelStatus( // get status for keyboard 253 KBDChannel, // keyboard number 254 KBDChanStatus* // pointer to storage for status 255 ); 256 257 KBDEc KBDResetChannel( // reset key press state for keyboard 258 KBDChannel // keyboard number 259 ); 260 261 KBDEc KBDSetCountry( // set country code for keyboard 262 KBDChannel, // keyboard number 263 KBDCountryCode // country code to set 264 ); 265 266 KBDEc KBDGetCountry( // get country code for keyboard 267 KBDChannel, // keyboard number 268 KBDCountryCode* // pointer to storage for country code 269 ); 270 271 KBDEc KBDGetKey( // get key event for keyboard 272 KBDChannel, // keyboard number 273 KBDKeyEvent* // pointer to storage for event 274 ); 275 276 KBDEc KBDEmptyQueue( // empty queue 277 KBDChannel // keyboard number 278 ); 279 280 KBDEc KBDSetLockProcessing( // set lock modifier processing 281 KBDChannel, // keyboard number 282 BOOL // TRUE = On, FALSE = Off 283 ); 284 285 KBDEc KBDGetLockProcessing( // get lock modifier processing 286 KBDChannel, // keyboard number 287 BOOL* // pointer to storage for On/Off 288 ); 289 290 KBDEc KBDSetModState( // set mod state to keyboard 291 KBDChannel, // keyboard number 292 KBDModState // mod state to set 293 ); 294 295 KBDEc KBDGetModState( // get mod state from keyboard 296 KBDChannel, // keyboard number 297 KBDModState* // pointer to storage for mod state 298 ); 299 300 KBDEc KBDSetRepeat( // set repeat rate for keyboard 301 KBDChannel, // keyboard number 302 u16, // delay to set 303 u16 // interval to set 304 ); 305 306 KBDEc KBDGetRepeat( // get repeat rate for keyboard 307 KBDChannel, // keyboard number 308 u16*, // pointer to storage for delay 309 u16* // pointer to storage for interval 310 ); 311 312 KBDEc KBDSetAccessSticky( // set sticky state for modifier keys 313 KBDChannel, // keyboard number 314 BOOL // TRUE = On, FALSE = Off 315 ); 316 317 KBDEc KBDGetAccessSticky( // get sticky state for modifier keys 318 KBDChannel, // keyboard number 319 BOOL* // pointer to storage for On/Off 320 ); 321 322 KBDEc KBDSetLedsEx( // set LEDs on keyboard 323 KBDChannel, // keyboard number 324 KBDLedState // LED state to set 325 ); 326 327 KBDEc KBDSetLedsAsyncEx( // set LED on keyboard, non-blocking with callback 328 KBDChannel, // keyboard number 329 KBDLedState, // LED state to set 330 KBDLedCallbackF, // completion callback function 331 void* // caller supplied parameter to pass to callback function 332 ); 333 334 KBDEc KBDSetLedsRetryEx( // set LEDs on keyboard with automatic retry 335 KBDChannel, // keyboard number 336 KBDLedState // LED state to set 337 ); 338 339 KBDUnicode KBDTranslateHidCode( // returns translated KBD Unicode 340 KBDHIDCode, // HID code to translate 341 KBDModState, // keyboard mod state 342 KBDCountryCode // country code 343 ); 344 345 int OSUTF32to8( // convert UTF32 to UTF8 346 u32*, // pointer to UTF32 to convert 347 char* // pointer to storage for UTF8 output 348 ); 349 350 int OSUTF16to32( // convert UTF16 to UTF32 351 u16*, // pointer to UTF16 to convert 352 u32* // pointer to storage for UTF32 output 353 ); 354 355 ////////////////////////////////////////////////////////////////////////////// 356 #ifdef __cplusplus 357 } 358 #endif 359 360 #endif // __KBD_H__ 361