EFI SIMPLE TEXT INPUT EX PROTOCOL

From PhoenixWiki

Jump to: navigation, search

This protocol is used to obtain input from the ConsoleIn device. The EFI specification requires that the EFI_SIMPLE_TEXT_INPUT_PROTOCOL supports the same languages as the corresponding EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.

Contents

GUID

#define EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL_GUID \
  {0xdd9e7534, 0x7762, 0x4698, 0x8c, 0x14, 0xf5, 0x85, \
  0x17, 0xa6, 0x25, 0xaa}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(SimpleTextInEx)
 
extern EFI_GUID gEfiSimpleTextInProtocolGuid;
typedef struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL{
  EFI_INPUT_RESET_EX              Reset;
  EFI_INPUT_READ_KEY_EX           ReadKeyStrokeEx;
  EFI_EVENT                       WaitForKeyEx;
  EFI_SET_STATE                   SetState;
  EFI_REGISTER_KEYSTROKE_NOTIFY   RegisterKeyNotify;
  EFI_UNREGISTER_KEYSTROKE_NOTIFY UnregisterKeyNotify;
} EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL;

Members

Member Description
Reset Reset the ConsoleIn device.
ReadKeyStrokeEx Returns the next input character.
WaitForKeyEx Event to use with WaitForEvent() to wait for a key to be available.
SetState Set the EFI_KEY_TOGGLE_STATE state settings for the input device.
RegisterKeyNotify Register a notification function to be called when a given key sequence is hit.
UnregisterKeyNotify Removes a specific notification function.

Description

The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn device. It is an extension to the Simple Text Input protocol which allows a variety of extended shift state information to be returned.

Reset()

Resets the input device hardware.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_INPUT_RESET_EX) (
  IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
  IN BOOLEAN                           ExtendedVerification
  );

Parameters

Parameter Description
This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
ExtendedVerification Indicates that the driver may perform a more exhaustive verification operation of the device during reset.

Description
The Reset() function resets the input device hardware.

The implementation of Reset is required to clear the contents of any input queues resident in memory used for buffering keystroke data and put the input stream in a known empty state.

As part of initialization process, the firmware/device will make a quick but reasonable attempt to verify that the device is functioning. If the ExtendedVerification flag is TRUE the firmware may take an extended amount of time to verify the device is operating on reset. Otherwise the reset operation is to occur as quickly as possible.

The hardware verification process is not defined by this specification and is left up to the platform firmware or driver to implement.

Status Codes Returned

Status Code Description
EFI_SUCCESS The device was reset.
EFI_DEVICE_ERROR The device is not functioning correctly and could not be reset.

ReadKeyStrokeEx()

Reads the next keystroke from the input device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_INPUT_READ_KEY_EX) (
  IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
  OUT EFI_KEY_DATA                      *KeyData
  );

Parameters

Parameter Description
This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
KeyData A pointer to a buffer that is filled in with the keystroke state data for the key that was pressed.

Description
The ReadKeyStrokeEx() function reads the next keystroke from the input device. If there is no pending keystroke the function returns EFI_NOT_READY. If there is a pending keystroke, then KeyData.Key.ScanCode is the EFI scan code. The KeyData.Key.UnicodeChar is the actual printable character or is zero if the key does not represent a printable character (control key, function key, etc.). The KeyData.KeyState is the modifier shift state for the character reflected in KeyData.Key.UnicodeChar or KeyData.Key.ScanCode. This function mirrors the behavior of ReadKeyStroke() in the EFI_SIMPLE_TEXT_INPUT_PROTOCOLin that a keystroke will only be returned when KeyData.Key has data within it.

When interpreting the data from this function, it should be noted that if a class of printable characters that are normally adjusted by shift modifiers (e.g. Shift Key + "f" key) would be presented solely as a KeyData.Key.UnicodeChar without the associated shift state. So in the previous example of a Shift Key + "f" key being pressed, the only pertinent data returned would be KeyData.Key.UnicodeChar with the value of "F". This of course would not typically be the case for non-printable characters such as the pressing of the Right Shift Key + F10 key since the corresponding returned data would be reflected both in the KeyData.KeyState.KeyShiftState and KeyData.Key.ScanCode values.

UEFI drivers which implement the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL are required to return KeyData.Key and KeyData.KeyState values. These drivers must always return the most current state of KeyData.KeyState.KeyShiftState and KeyData.KeyState.KeyToggleState. It should also be noted that certain input devices may not be able to produce shift or toggle state information, and in those cases the high order bit in the respective Toggle and Shift state fields should not be active.

Status Codes Returned

Status Code Description
EFI_SUCCESS The keystroke information was returned.
EFI_NOT_READY There was no keystroke data available.
EFI_DEVICE_ERROR The keystroke information was not returned due to hardware errors.

SetState()

Set certain state for the input device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SET_STATE) (
  IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
  IN EFI_KEY_TOGGLE_STATE              *KeyToggleState
  );

Parameters

Parameter Description
This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
KeyToggleState Pointer to the EFI_KEY_TOGGLE_STATE to set the state for the input device.

Description
The SetState() function allows the input device hardware to have state settings adjusted.

Status Codes Returned

Status Code Description
EFI_SUCCESS The device state was set appropriately.
EFI_DEVICE_ERROR The device is not functioning correctly and could not have the setting adjusted.
EFI_UNSUPPORTED The device does not support the ability to have its state set.

RegisterKeyNotify()

Register a notification function for a particular keystroke for the input device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_REGISTER_KEYSTROKE_NOTIFY) (
  IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
  IN  EFI_KEY_DATA                      *KeyData,
  IN  EFI_KEY_NOTIFY_FUNCTION           KeyNotificationFunction,
  OUT EFI_HANDLE                        *NotifyHandle
  );

Parameters

Parameter Description
This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
KeyData A pointer to a buffer that is filled in with the keystroke information for the key that was pressed.
KeyNotificationFunction Points to the function to be called when the key sequence is typed specified by KeyData.
NotifyHandle Points to the unique handle assigned to the registered notification..

Description
The RegisterKeystrokeNotify() function registers a function which will be called when a specified keystroke will occur. The keystroke being specified can be for any combination of KeyData.Key and KeyData.KeyState information.

Status Codes Returned

Status Code Description
EFI_SUCCESS The device state was set appropriately.
EFI_OUT_OF_RESOURCES Unable to allocate necessary data structures.

UnregisterKeyNotify()

Removes key notification function.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_UNREGISTER_KEYSTROKE_NOTIFY) (
  IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
  IN EFI_HANDLE                        NotificationHandle
  );

Parameters

Parameter Description
This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
NotificationHandle The handle of the notification function being unregistered.

Description
The UnregisterKeystrokeNotify() function removes the notification which was previously registered.

Status Codes Returned

Status Code Description
EFI_SUCCESS The device state was set appropriately.
EFI_INVALID_PARAMETER The NotificationHandle is invalid.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools