1 /*---------------------------------------------------------------------------* 2 Project: Revolution USB keyboard library 3 File: kbd.h 4 5 Copyright 2007 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 $Log: kbd.h,v $ 14 Revision 1.17 2007/07/13 23:49:11 carlmu 15 Added KBDSetLedsRetry. 16 Changed API for LED callback. 17 18 Revision 1.16 2007/07/12 01:38:05 dante.treglia 19 KBD: Removed unsupported languages from typedef enum _KBDCountryCode. 20 21 Revision 1.15 2007/06/21 22:40:38 carlmu 22 Updated for 1.4 API (changed LED handling). 23 24 Revision 1.14 2007/05/29 21:56:06 carlmu 25 Changed macro indicating NumLock state. 26 27 Revision 1.13 2007/05/22 00:43:30 carlmu 28 Changed #ifdef USBKBD to #ifndef USE_PPC_HID, etc. 29 30 Revision 1.12 2007/05/17 21:57:58 carlmu 31 Added ability to set PPC HID lib memory. 32 33 Revision 1.11 2007/05/11 23:21:07 carlmu 34 Added US_International map code. 35 Added macros related to CTRL keys. 36 37 Revision 1.10 2007/05/05 01:58:13 carlmu 38 Changes for 0.8 API 39 40 Revision 1.9 2007/05/01 21:38:13 carlmu 41 Stripped dead-key-related code. 42 Changed KBD_MS_BASE_KEY to KBD_MS_SHIFTED_KEY. 43 44 Revision 1.8 2007/04/25 19:17:22 carlmu 45 Added macros related to keypad digit keys. 46 47 Revision 1.7 2007/04/18 00:01:32 carlmu 48 Updated for 0.5 API. 49 50 Revision 1.6 2007/04/10 18:43:20 carlmu 51 New 0.4 API structure. 52 53 Revision 1.5 2007/04/05 21:56:59 carlmu 54 Changed kbd_usb_codes.h to kbd_hid_codes.h. 55 56 Revision 1.4 2007/04/04 19:39:50 carlmu 57 Added KBD_HID_NONE. 58 59 Revision 1.3 2007/04/02 19:11:24 carlmu 60 Get/Set LED calls now private. 61 Set callback functions return old callback. 62 Added scroll lock modifier state. 63 64 Revision 1.2 2007/03/28 00:27:45 carlmu 65 Updated to 0.2 API. 66 67 Revision 1.1 2007/03/21 18:06:02 carlmu 68 Initial version. 69 70 $NoKeywords: $ 71 *---------------------------------------------------------------------------*/ 72 73 #ifndef __KBD_H__ 74 #define __KBD_H__ 75 76 #include <revolution/types.h> 77 #include <revolution/kbd/kbd_key_defs.h> 78 #include <revolution/kbd/kbd_hid_codes.h> 79 80 #ifdef __cplusplus 81 extern "C" { 82 #endif 83 84 // Low-level key press API 85 86 //----------------------------------------------------------------------------- 87 // Types: 88 89 // Up to 4 keyboards can be attached 90 #define KBD_MAX_CHANNELS (4) // valid channel numbers are 0-3 91 92 typedef enum _KBDEc { // function return code 93 KBD_SUCCESS = 0, 94 KBD_ERR_OTHER = 1, // usually from HID error 95 KBD_ERR_NOT_INITIALIZED = 2, 96 KBD_ERR_ALREADY_INITIALIZED = 3, 97 KBD_ERR_BAD_VALUE = 4, // input argument out of range 98 KBD_ERR_BAD_STATUS = 5, // ie, keyboard disconnected 99 KBD_ERR_BAD_POINTER = 6, 100 KBD_ERR_BUSY = 7 // for KBDSetLeds 101 } KBDEc; 102 103 typedef enum _KBDChanStatus { // status bits may be OR-ed together 104 KBD_CS_OK = 0x00, 105 KBD_CS_DISCONNECTED = 0x01, 106 KBD_CS_ROLL_OVER = 0x02, 107 KBD_CS_ERROR = 0x04 108 } KBDChanStatus; 109 110 typedef u8 KBDChannel; 111 typedef u8 KBDHIDCode; 112 113 #define KBD_HID_NONE 0 // value returned when queue is empty 114 #define KBD_HID_OVERFLOW 255 // value returned when queue overflows 115 116 typedef enum _KBDKeyMode { 117 KBD_KM_DOWN = 0x01, // on=key down; off=key up 118 KBD_KM_REPEAT = 0x02, // on=repeat key; off=initial key press 119 KBD_KM_NULL = 0x00 120 } KBDKeyMode; 121 122 #define KBD_KEY_MODE_UP(_key_mode) (!((_key_mode) & KBD_KM_DOWN)) 123 #define KBD_KEY_MODE_DOWN(_key_mode) ((_key_mode) & KBD_KM_DOWN) 124 #define KBD_KEY_MODE_REPEAT(_key_mode) ((_key_mode) & KBD_KM_REPEAT) 125 126 // xxx Some of these countries may disappear from this list. 127 // Others may be added. Names may be changed. 128 129 typedef enum _KBDCountryCode { 130 KBD_CC_INTERNATIONAL, 131 KBD_CC_CANADIAN_BI, 132 KBD_CC_CANADIAN_FR, 133 KBD_CC_DANISH, 134 KBD_CC_FINNISH, 135 KBD_CC_FRENCH, 136 KBD_CC_GERMAN, 137 KBD_CC_GREEK, 138 KBD_CC_ITALIAN, 139 KBD_CC_JAPANESE, 140 KBD_CC_LATIN_AMERICAN, 141 KBD_CC_NETHERLANDS_DUTCH, 142 KBD_CC_NORWEGIAN, 143 KBD_CC_PORTUGUESE, 144 KBD_CC_SPANISH, 145 KBD_CC_SWEDISH, 146 KBD_CC_UNITED_KINGDOM, 147 KBD_CC_UNITED_STATES, 148 KBD_CC_RESERVED 149 } KBDCountryCode; 150 151 #define KBD_NUM_COUNTRY_CODES KBD_CC_RESERVED 152 153 typedef enum _KBDModState { // state bits may be OR-ed together 154 KBD_MS_CTRL = 0x0001, 155 KBD_MS_SHIFT = 0x0002, 156 KBD_MS_ALT = 0x0004, 157 KBD_MS_GUI = 0x0008, 158 KBD_MS_EXTRA = 0x0010, 159 KBD_MS_ALTGR = 0x0020, 160 KBD_MS_LANG1 = 0x0040, // (Hiragana) 161 KBD_MS_LANG2 = 0x0080, // (Katakana) 162 KBD_MS_NUM_LOCK = 0x0100, 163 KBD_MS_CAPS_LOCK = 0x0200, 164 KBD_MS_SCROLL_LOCK = 0x0400, 165 KBD_MS_SHIFTED_KEY = 0x0800, // when CTRL/ALT/GUI/EXTRA is on, allow shifted key to be returned 166 // (the default is that the base/unshifted key is returned) 167 KBD_MS_SET_ALL = 0x1000, // With KBDSetModState, allows setting of all bits 168 KBD_MS_NULL = 0x0000 169 } KBDModState; 170 171 // define alternate names for these 172 #define KBD_MS_HIRAGANA KBD_MS_LANG1 173 #define KBD_MS_KATAKANA KBD_MS_LANG2 174 175 // define convenient groups of state 176 #define KBD_MS_TRANSIENTS (KBD_MS_CTRL|KBD_MS_SHIFT|KBD_MS_ALT|KBD_MS_GUI|KBD_MS_EXTRA|KBD_MS_ALTGR) 177 #define KBD_MS_TOGGLES (KBD_MS_LANG1|KBD_MS_LANG2|KBD_MS_NUM_LOCK|KBD_MS_CAPS_LOCK|KBD_MS_SCROLL_LOCK) 178 179 typedef u16 KBDUnicode; // should it be wchar_t? xxx 180 181 // Indicate if a KBDUnicode value is private to KBD (special KBD internal value) 182 #define KBD_UC_IS_PRIVATE(uc) (((uc)>=0xf000 && (uc)<=0xF1FF) || ((uc)==0xFFFF)) 183 184 // This macro may be used to determine if a KBDUnicode is a modifier key 185 #define KBD_UC_IS_MODIFIER(uc) ((uc)>=0xf000 && (uc)<=0xf01f) 186 187 // These defines may be used to determine if a KBDUnicode 188 // value is a regular ASCII key from the keypad, and if so, to 189 // convert that value to the regular ASCII value 190 #define KBD_UC_IS_KP_REG_KEY(uc) (((uc)>=0xf100) && ((uc)<=0xf13f)) 191 #define KBD_KP_REG_KEY_TO_ASCII(uc) ((uc)&0x3f) 192 193 // Indicate if a key is a keypad number (digit) key with NumLock on 194 #define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9))) 195 // Indicate if a key is a keypad number (digit) key with NumLock off 196 #define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up))) 197 // Convert from NumLock off digit key to NumLock on digit key 198 #define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40)) 199 200 // Indicate if a ModState represents NumLock == on 201 #define KBD_MS_IS_NUMLOCK(ms) (((ms)&KBD_MS_NUM_LOCK) && !((ms)&KBD_MS_SHIFT)) 202 203 // Indicate if a key is a private control Unicode, and convert to ASCII 204 #define KBD_UC_IS_CTRL_KEY (((uc)>=0xf1c0) && ((uc)<=0xf1df)) 205 #define KBD_CTRL_KEY_TO_ASCII(uc) ((uc)&0x1f) 206 207 typedef enum _KBDLedState { 208 KBD_LED_NUM_LOCK = 0x01, 209 KBD_LED_CAPS_LOCK = 0x02, 210 KBD_LED_SCROLL_LOCK = 0x04, 211 KBD_LED_NULL = 0x00, 212 KBD_LED_RESERVED = 0x10 213 } KBDLedState; 214 215 //----------------------------------------------------------------------------- 216 // Structs: 217 218 typedef struct _KBDDevEvent { // kbd attach/detach callbacks 219 KBDChannel channel; 220 } KBDDevEvent; 221 222 typedef struct _KBDKeyEvent { // for key callback/getkey 223 KBDChannel channel; 224 KBDHIDCode hid; // USB HID code 225 KBDKeyMode mode; // for up/down/etc 226 KBDModState modState; // modifier state 227 KBDUnicode unicode; // unicode, if any 228 } KBDKeyEvent; 229 230 typedef struct _KBDLedEvent { // kbd LED callback 231 KBDChannel channel; 232 KBDLedState leds; 233 KBDEc rc; 234 } KBDLedEvent; 235 236 typedef void (*KBDDevCallbackF) (KBDDevEvent *ev); 237 typedef void (*KBDKeyCallbackF) (KBDKeyEvent *ev); 238 typedef void (*KBDLedCallbackF) (KBDLedEvent *ev, void *cbArg); 239 240 //----------------------------------------------------------------------------- 241 // Function calls 242 243 // One of these MUST be called before KBDInit: 244 void KBDInitRegionUS(void); 245 void KBDInitRegionJP(void); 246 void KBDInitRegionEU(void); 247 248 KBDEc KBDInit (void); // init library 249 KBDEc KBDExit (void); // terminate library 250 251 KBDDevCallbackF KBDSetAttachCallback (KBDDevCallbackF fn); // set kbd attach callback 252 KBDDevCallbackF KBDSetDetachCallback (KBDDevCallbackF fn); // set kbd detach callback 253 254 KBDEc KBDGetChannelStatus (KBDChannel ch, KBDChanStatus *chanStatus); 255 KBDEc KBDResetChannel (KBDChannel ch); // reset key press state 256 257 KBDEc KBDSetCountry (KBDChannel ch, KBDCountryCode country); // set country 258 KBDEc KBDGetCountry (KBDChannel ch, KBDCountryCode *country); // get country 259 260 KBDKeyCallbackF KBDSetKeyCallback (KBDKeyCallbackF fn); // set key callback 261 KBDEc KBDGetKey(KBDChannel ch, KBDKeyEvent *keyEvent); // synch key API 262 263 KBDEc KBDSetLockProcessing(KBDChannel ch, BOOL enable); 264 KBDEc KBDGetLockProcessing(KBDChannel ch, BOOL *enable); 265 266 KBDEc KBDSetModState(KBDChannel ch, KBDModState modState); 267 KBDEc KBDGetModState(KBDChannel ch, KBDModState *modState); 268 269 KBDUnicode KBDTranslateHidCode(KBDHIDCode hid, KBDModState modState, KBDCountryCode country); 270 271 KBDEc KBDSetRepeat(KBDChannel ch, u16 delay, u16 interval); 272 KBDEc KBDGetRepeat(KBDChannel ch, u16 *delay, u16 *interval); 273 274 KBDEc KBDSetAccessSticky(KBDChannel, BOOL enable); 275 KBDEc KBDGetAccessSticky(KBDChannel, BOOL *enable); 276 277 KBDEc KBDSetLeds(KBDChannel ch, KBDLedState leds); 278 KBDEc KBDSetLedsAsync(KBDChannel ch, KBDLedState leds, KBDLedCallbackF fn, void *cbArg); 279 KBDEc KBDSetLedsRetry(KBDChannel ch, KBDLedState leds); 280 281 #ifdef USE_PPC_HID 282 // Temporary test function 283 void KBDSetHidMem(u8 *ptr, u32 size); 284 #endif 285 286 #ifdef __cplusplus 287 } 288 #endif 289 290 #endif // __KBD_H__ 291