MdePkg/Include/Protocol/SimpleTextInEx.h

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