MdePkg/SimpleTextInEx.h: Fix comments alignment
[mirror_edk2.git] / MdePkg / Include / Protocol / SimpleTextInEx.h
CommitLineData
d1f95000 1/** @file\r
c8c44377 2 Simple Text Input Ex protocol from the UEFI 2.0 specification.\r
e791cf44 3\r
c8c44377 4 This protocol defines an extension to the EFI_SIMPLE_TEXT_INPUT_PROTOCOL\r
5 which exposes much more state and modifier information from the input device,\r
6 also allows one to register a notification for a particular keystroke.\r
d1f95000 7\r
2de87e46 8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
e791cf44 9 This program and the accompanying materials\r
10 are licensed and made available under the terms and conditions of the BSD License\r
11 which accompanies this distribution. The full text of the license may be found at\r
12 http://opensource.org/licenses/bsd-license.php\r
d1f95000 13\r
e791cf44 14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
d1f95000 16\r
d1f95000 17**/\r
18\r
19#ifndef __SIMPLE_TEXT_IN_EX_H__\r
20#define __SIMPLE_TEXT_IN_EX_H__\r
21\r
2be21afb 22#include <Protocol/SimpleTextIn.h>\r
23\r
d1f95000 24#define EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL_GUID \\r
25 {0xdd9e7534, 0x7762, 0x4698, { 0x8c, 0x14, 0xf5, 0x85, 0x17, 0xa6, 0x25, 0xaa } }\r
26\r
27\r
28typedef struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL;\r
29\r
30/**\r
31 The Reset() function resets the input device hardware. As part\r
32 of initialization process, the firmware/device will make a quick\r
33 but reasonable attempt to verify that the device is functioning.\r
34 If the ExtendedVerification flag is TRUE the firmware may take\r
35 an extended amount of time to verify the device is operating on\r
36 reset. Otherwise the reset operation is to occur as quickly as\r
37 possible. The hardware verification process is not defined by\r
38 this specification and is left up to the platform firmware or\r
39 driver to implement.\r
40\r
4ca9b6c4 41 @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.\r
d1f95000 42\r
43 @param ExtendedVerification Indicates that the driver may\r
44 perform a more exhaustive\r
45 verification operation of the\r
46 device during reset.\r
47\r
48\r
4ca9b6c4 49 @retval EFI_SUCCESS The device was reset.\r
e791cf44 50\r
d1f95000 51 @retval EFI_DEVICE_ERROR The device is not functioning\r
52 correctly and could not be reset.\r
53\r
54**/\r
55typedef\r
56EFI_STATUS\r
8b13229b 57(EFIAPI *EFI_INPUT_RESET_EX)(\r
85f74a01 58 IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,\r
59 IN BOOLEAN ExtendedVerification\r
d1f95000 60);\r
61\r
62\r
992f22b9 63///\r
630b4187 64/// EFI_KEY_TOGGLE_STATE. The toggle states are defined.\r
65/// They are: EFI_TOGGLE_STATE_VALID, EFI_SCROLL_LOCK_ACTIVE\r
992f22b9
LG
66/// EFI_NUM_LOCK_ACTIVE, EFI_CAPS_LOCK_ACTIVE\r
67///\r
85f74a01 68typedef UINT8 EFI_KEY_TOGGLE_STATE;\r
d1f95000 69\r
d1f95000 70typedef struct _EFI_KEY_STATE {\r
992f22b9
LG
71 ///\r
72 /// Reflects the currently pressed shift\r
73 /// modifiers for the input device. The\r
74 /// returned value is valid only if the high\r
75 /// order bit has been set.\r
76 ///\r
d1f95000 77 UINT32 KeyShiftState;\r
992f22b9
LG
78 ///\r
79 /// Reflects the current internal state of\r
80 /// various toggled attributes. The returned\r
81 /// value is valid only if the high order\r
82 /// bit has been set.\r
83 ///\r
d1f95000 84 EFI_KEY_TOGGLE_STATE KeyToggleState;\r
85} EFI_KEY_STATE;\r
86\r
d1f95000 87typedef struct {\r
992f22b9
LG
88 ///\r
89 /// The EFI scan code and Unicode value returned from the input device.\r
90 ///\r
d1f95000 91 EFI_INPUT_KEY Key;\r
992f22b9
LG
92 ///\r
93 /// The current state of various toggled attributes as well as input modifier values.\r
94 ///\r
d1f95000 95 EFI_KEY_STATE KeyState;\r
96} EFI_KEY_DATA;\r
97\r
d1f95000 98//\r
99// Any Shift or Toggle State that is valid should have\r
100// high order bit set.\r
101//\r
85f74a01 102// Shift state\r
103//\r
104#define EFI_SHIFT_STATE_VALID 0x80000000\r
105#define EFI_RIGHT_SHIFT_PRESSED 0x00000001\r
106#define EFI_LEFT_SHIFT_PRESSED 0x00000002\r
107#define EFI_RIGHT_CONTROL_PRESSED 0x00000004\r
108#define EFI_LEFT_CONTROL_PRESSED 0x00000008\r
109#define EFI_RIGHT_ALT_PRESSED 0x00000010\r
110#define EFI_LEFT_ALT_PRESSED 0x00000020\r
111#define EFI_RIGHT_LOGO_PRESSED 0x00000040\r
112#define EFI_LEFT_LOGO_PRESSED 0x00000080\r
113#define EFI_MENU_KEY_PRESSED 0x00000100\r
114#define EFI_SYS_REQ_PRESSED 0x00000200\r
115\r
e791cf44 116//\r
117// Toggle state\r
118//\r
85f74a01 119#define EFI_TOGGLE_STATE_VALID 0x80\r
e791cf44 120#define EFI_KEY_STATE_EXPOSED 0x40\r
85f74a01 121#define EFI_SCROLL_LOCK_ACTIVE 0x01\r
122#define EFI_NUM_LOCK_ACTIVE 0x02\r
123#define EFI_CAPS_LOCK_ACTIVE 0x04\r
e791cf44 124\r
125//\r
126// EFI Scan codes\r
2be21afb 127//\r
128#define SCAN_F11 0x0015\r
129#define SCAN_F12 0x0016\r
66b96f92 130#define SCAN_PAUSE 0x0048\r
85f74a01 131#define SCAN_F13 0x0068\r
132#define SCAN_F14 0x0069\r
133#define SCAN_F15 0x006A\r
134#define SCAN_F16 0x006B\r
135#define SCAN_F17 0x006C\r
136#define SCAN_F18 0x006D\r
137#define SCAN_F19 0x006E\r
138#define SCAN_F20 0x006F\r
139#define SCAN_F21 0x0070\r
140#define SCAN_F22 0x0071\r
141#define SCAN_F23 0x0072\r
142#define SCAN_F24 0x0073\r
143#define SCAN_MUTE 0x007F\r
144#define SCAN_VOLUME_UP 0x0080\r
145#define SCAN_VOLUME_DOWN 0x0081\r
146#define SCAN_BRIGHTNESS_UP 0x0100\r
147#define SCAN_BRIGHTNESS_DOWN 0x0101\r
148#define SCAN_SUSPEND 0x0102\r
149#define SCAN_HIBERNATE 0x0103\r
150#define SCAN_TOGGLE_DISPLAY 0x0104\r
151#define SCAN_RECOVERY 0x0105\r
152#define SCAN_EJECT 0x0106\r
d1f95000 153\r
154/**\r
155 The function reads the next keystroke from the input device. If\r
156 there is no pending keystroke the function returns\r
157 EFI_NOT_READY. If there is a pending keystroke, then\r
158 KeyData.Key.ScanCode is the EFI scan code defined in Error!\r
630b4187 159 Reference source not found. The KeyData.Key.UnicodeChar is the\r
f754f721 160 actual printable character or is zero if the key does not\r
d1f95000 161 represent a printable character (control key, function key,\r
162 etc.). The KeyData.KeyState is shift state for the character\r
163 reflected in KeyData.Key.UnicodeChar or KeyData.Key.ScanCode .\r
f754f721 164 When interpreting the data from this function, it should be\r
165 noted that if a class of printable characters that are\r
d1f95000 166 normally adjusted by shift modifiers (e.g. Shift Key + "f"\r
f754f721 167 key) would be presented solely as a KeyData.Key.UnicodeChar\r
168 without the associated shift state. So in the previous example\r
169 of a Shift Key + "f" key being pressed, the only pertinent\r
d1f95000 170 data returned would be KeyData.Key.UnicodeChar with the value\r
f754f721 171 of "F". This of course would not typically be the case for\r
172 non-printable characters such as the pressing of the Right\r
173 Shift Key + F10 key since the corresponding returned data\r
d1f95000 174 would be reflected both in the KeyData.KeyState.KeyShiftState\r
175 and KeyData.Key.ScanCode values. UEFI drivers which implement\r
176 the EFI_SIMPLE_TEXT_INPUT_EX protocol are required to return\r
177 KeyData.Key and KeyData.KeyState values. These drivers must\r
178 always return the most current state of\r
179 KeyData.KeyState.KeyShiftState and\r
f754f721 180 KeyData.KeyState.KeyToggleState. It should also be noted that\r
181 certain input devices may not be able to produce shift or toggle\r
d1f95000 182 state information, and in those cases the high order bit in the\r
183 respective Toggle and Shift state fields should not be active.\r
184\r
e791cf44 185\r
4ca9b6c4 186 @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.\r
d1f95000 187\r
188 @param KeyData A pointer to a buffer that is filled in with\r
189 the keystroke state data for the key that was\r
190 pressed.\r
191\r
e791cf44 192\r
2de87e46
RN
193 @retval EFI_SUCCESS The keystroke information was returned.\r
194 @retval EFI_NOT_READY There was no keystroke data available.\r
195 @retval EFI_DEVICE_ERROR The keystroke information was not returned due to\r
196 hardware errors.\r
d1f95000 197\r
198\r
199**/\r
200typedef\r
201EFI_STATUS\r
8b13229b 202(EFIAPI *EFI_INPUT_READ_KEY_EX)(\r
85f74a01 203 IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,\r
204 OUT EFI_KEY_DATA *KeyData\r
d1f95000 205);\r
206\r
207/**\r
208 The SetState() function allows the input device hardware to\r
209 have state settings adjusted.\r
e791cf44 210\r
4ca9b6c4 211 @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.\r
e791cf44 212\r
d1f95000 213 @param KeyToggleState Pointer to the EFI_KEY_TOGGLE_STATE to\r
214 set the state for the input device.\r
e791cf44 215\r
216\r
4ca9b6c4 217 @retval EFI_SUCCESS The device state was set appropriately.\r
d1f95000 218\r
219 @retval EFI_DEVICE_ERROR The device is not functioning\r
220 correctly and could not have the\r
221 setting adjusted.\r
222\r
223 @retval EFI_UNSUPPORTED The device does not support the\r
224 ability to have its state set.\r
225\r
226**/\r
227typedef\r
228EFI_STATUS\r
8b13229b 229(EFIAPI *EFI_SET_STATE)(\r
85f74a01 230 IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,\r
231 IN EFI_KEY_TOGGLE_STATE *KeyToggleState\r
d1f95000 232);\r
233\r
992f22b9
LG
234///\r
235/// The function will be called when the key sequence is typed specified by KeyData.\r
236///\r
d1f95000 237typedef\r
238EFI_STATUS\r
8b13229b 239(EFIAPI *EFI_KEY_NOTIFY_FUNCTION)(\r
85f74a01 240 IN EFI_KEY_DATA *KeyData\r
d1f95000 241);\r
242\r
243/**\r
244 The RegisterKeystrokeNotify() function registers a function\r
f754f721 245 which will be called when a specified keystroke will occur.\r
e791cf44 246\r
4ca9b6c4 247 @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.\r
e791cf44 248\r
4ca9b6c4
LG
249 @param KeyData A pointer to a buffer that is filled in with\r
250 the keystroke information for the key that was\r
d4225da1
DB
251 pressed. If KeyData.Key, KeyData.KeyState.KeyToggleState\r
252 and KeyData.KeyState.KeyShiftState are 0, then any incomplete\r
253 keystroke will trigger a notification of the KeyNotificationFunction.\r
e791cf44 254\r
d4225da1
DB
255 @param KeyNotificationFunction Points to the function to be called when the key sequence\r
256 is typed specified by KeyData. This notification function\r
257 should be called at <=TPL_CALLBACK.\r
e791cf44 258\r
259\r
4ca9b6c4
LG
260 @param NotifyHandle Points to the unique handle assigned to\r
261 the registered notification.\r
e791cf44 262\r
d4225da1 263 @retval EFI_SUCCESS Key notify was registered successfully.\r
d1f95000 264\r
265 @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary\r
266 data structures.\r
267\r
268**/\r
269typedef\r
270EFI_STATUS\r
8b13229b 271(EFIAPI *EFI_REGISTER_KEYSTROKE_NOTIFY)(\r
85f74a01 272 IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,\r
273 IN EFI_KEY_DATA *KeyData,\r
274 IN EFI_KEY_NOTIFY_FUNCTION KeyNotificationFunction,\r
402e4a9d 275 OUT VOID **NotifyHandle\r
d1f95000 276);\r
277\r
278/**\r
f754f721 279 The UnregisterKeystrokeNotify() function removes the\r
280 notification which was previously registered.\r
e791cf44 281\r
4ca9b6c4 282 @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.\r
e791cf44 283\r
d1f95000 284 @param NotificationHandle The handle of the notification\r
285 function being unregistered.\r
e791cf44 286\r
d4225da1 287 @retval EFI_SUCCESS Key notify was unregistered successfully.\r
e791cf44 288\r
d1f95000 289 @retval EFI_INVALID_PARAMETER The NotificationHandle is\r
290 invalid.\r
291\r
292**/\r
293typedef\r
294EFI_STATUS\r
8b13229b 295(EFIAPI *EFI_UNREGISTER_KEYSTROKE_NOTIFY)(\r
85f74a01 296 IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,\r
402e4a9d 297 IN VOID *NotificationHandle\r
d1f95000 298);\r
299\r
300\r
44717a39 301///\r
302/// The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn\r
303/// device. It is an extension to the Simple Text Input protocol\r
304/// which allows a variety of extended shift state information to be\r
305/// returned.\r
306///\r
d1f95000 307struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL{\r
308 EFI_INPUT_RESET_EX Reset;\r
309 EFI_INPUT_READ_KEY_EX ReadKeyStrokeEx;\r
1f08a159 310 ///\r
311 /// Event to use with WaitForEvent() to wait for a key to be available.\r
312 ///\r
d1f95000 313 EFI_EVENT WaitForKeyEx;\r
314 EFI_SET_STATE SetState;\r
315 EFI_REGISTER_KEYSTROKE_NOTIFY RegisterKeyNotify;\r
316 EFI_UNREGISTER_KEYSTROKE_NOTIFY UnregisterKeyNotify;\r
317};\r
318\r
319\r
320extern EFI_GUID gEfiSimpleTextInputExProtocolGuid;\r
321\r
322#endif\r
323\r