4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Simple Text Input Ex protocol from the UEFI 2.0 specification.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This protocol defines an extension to the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which exposes much more state and modifier information from the input device,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync also allows one to register a notification for a particular keystroke.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This program and the accompanying materials
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync are licensed and made available under the terms and conditions of the BSD License
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which accompanies this distribution. The full text of the license may be found at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync {0xdd9e7534, 0x7762, 0x4698, { 0x8c, 0x14, 0xf5, 0x85, 0x17, 0xa6, 0x25, 0xaa } }
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL;
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The Reset() function resets the input device hardware. As part
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of initialization process, the firmware/device will make a quick
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync but reasonable attempt to verify that the device is functioning.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync If the ExtendedVerification flag is TRUE the firmware may take
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync an extended amount of time to verify the device is operating on
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync reset. Otherwise the reset operation is to occur as quickly as
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync possible. The hardware verification process is not defined by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync this specification and is left up to the platform firmware or
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync driver to implement.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param ExtendedVerification Indicates that the driver may
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync perform a more exhaustive
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync verification operation of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync device during reset.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The device was reset.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_DEVICE_ERROR The device is not functioning
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync correctly and could not be reset.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// EFI_KEY_TOGGLE_STATE. The toggle states are defined.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// They are: EFI_TOGGLE_STATE_VALID, EFI_SCROLL_LOCK_ACTIVE
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// EFI_NUM_LOCK_ACTIVE, EFI_CAPS_LOCK_ACTIVE
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Reflects the currently pressed shift
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// modifiers for the input device. The
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// returned value is valid only if the high
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// order bit has been set.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Reflects the current internal state of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// various toggled attributes. The returned
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// value is valid only if the high order
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// bit has been set.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The EFI scan code and Unicode value returned from the input device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The current state of various toggled attributes as well as input modifier values.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync// Any Shift or Toggle State that is valid should have
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync// high order bit set.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync// Shift state
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync// Toggle state
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync// EFI Scan codes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The function reads the next keystroke from the input device. If
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync there is no pending keystroke the function returns
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_NOT_READY. If there is a pending keystroke, then
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync KeyData.Key.ScanCode is the EFI scan code defined in Error!
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Reference source not found. The KeyData.Key.UnicodeChar is the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync actual printable character or is zero if the key does not
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync represent a printable character (control key, function key,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync etc.). The KeyData.KeyState is shift state for the character
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync reflected in KeyData.Key.UnicodeChar or KeyData.Key.ScanCode .
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync When interpreting the data from this function, it should be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync noted that if a class of printable characters that are
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync normally adjusted by shift modifiers (e.g. Shift Key + "f"
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync key) would be presented solely as a KeyData.Key.UnicodeChar
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync without the associated shift state. So in the previous example
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of a Shift Key + "f" key being pressed, the only pertinent
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync data returned would be KeyData.Key.UnicodeChar with the value
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of "F". This of course would not typically be the case for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync non-printable characters such as the pressing of the Right
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Shift Key + F10 key since the corresponding returned data
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync would be reflected both in the KeyData.KeyState.KeyShiftState
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync and KeyData.Key.ScanCode values. UEFI drivers which implement
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the EFI_SIMPLE_TEXT_INPUT_EX protocol are required to return
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync KeyData.Key and KeyData.KeyState values. These drivers must
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync always return the most current state of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync KeyData.KeyState.KeyShiftState and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync KeyData.KeyState.KeyToggleState. It should also be noted that
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync certain input devices may not be able to produce shift or toggle
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync state information, and in those cases the high order bit in the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync respective Toggle and Shift state fields should not be active.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param KeyData A pointer to a buffer that is filled in with
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the keystroke state data for the key that was
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The keystroke information was
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_NOT_READY There was no keystroke data available.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_DEVICE_ERROR The keystroke
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync information was not returned due to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync hardware errors.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The SetState() function allows the input device hardware to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync have state settings adjusted.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param KeyToggleState Pointer to the EFI_KEY_TOGGLE_STATE to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync set the state for the input device.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The device state was set appropriately.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_DEVICE_ERROR The device is not functioning
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync correctly and could not have the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync setting adjusted.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_UNSUPPORTED The device does not support the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ability to have its state set.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// The function will be called when the key sequence is typed specified by KeyData.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The RegisterKeystrokeNotify() function registers a function
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which will be called when a specified keystroke will occur.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param KeyData A pointer to a buffer that is filled in with
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the keystroke information for the key that was
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param KeyNotificationFunction Points to the function to be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync called when the key sequence
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is typed specified by KeyData.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param NotifyHandle Points to the unique handle assigned to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the registered notification.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The device state was set
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync appropriately.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync data structures.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN EFI_KEY_NOTIFY_FUNCTION KeyNotificationFunction,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The UnregisterKeystrokeNotify() function removes the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync notification which was previously registered.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param NotificationHandle The handle of the notification
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync function being unregistered.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The device state was set appropriately.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER The NotificationHandle is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// device. It is an extension to the Simple Text Input protocol
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// which allows a variety of extended shift state information to be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// returned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Event to use with WaitForEvent() to wait for a key to be available.