MdePkg/Include/Protocol/SimpleTextInEx.h

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