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