input.c File Reference

This application showcases ways to read input from the keyboard. More...

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <UEFIStarter/core.h>

Macros
#define	ARG_HANDLE   _args[0].value.uint64
	helper macro to access the "handle offset" command-line argument's value
#define	ARG_OTHER_WAIT_EVENT   _args[1].value.uint64
	helper macro to access the alternative wait command-line argument's value

Functions
void	test_simple_input ()
	Reads keyboard input the easiest way: SIMPLE_TEXT_INPUT_PROTOCOL.
void *	find_device (EFI_GUID *guid, unsigned int offset)
	Locates an UEFI protocol handler, opens and returns it. More...
EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *	find_input_ex ()
	Finds the protocol handler for SIMPLE_TEXT_INPUT_EX_PROTOCOL. More...
void	test_ex_input ()
	Reads keyboard input with the extended protocol: SIMPLE_TEXT_INPUT_EX_PROTOCOL.
EFI_STATUS EFIAPI	ex_notify (EFI_KEY_DATA *data)
	Callback function for keyboard handler, prints the pressed key(s). More...
void	test_ex_notify ()
	Registers a listener for a specific key combination and waits for that combination to be pressed. More...
INTN EFIAPI	ShellAppMain (UINTN argc, CHAR16 **argv)
	Main function, gets invoked by UEFI shell. More...

Variables
static cmdline_argument_t	_args []
	command-line arguments More...
static cmdline_argument_group_t	_arguments ={ L"Application-specific options" ,sizeof( _args )/sizeof(cmdline_argument_t), _args }
	command-line argument group

Detailed Description

This application showcases ways to read input from the keyboard.

Keep in mind that terminals (and terminal multiplexers) in virtualized environments often don't send the pressed keys' raw scancodes but escape sequences instead. For example you may have to hit the Escape key 2-3 times in succession until it's registered once.

Author

Richard Nusser

Copyright

2017-2018 Richard Nusser

License

GPLv3 (see http://www.gnu.org/licenses/)

See also

https://github.com/rinusser/UEFIStarter

Function Documentation

find_device()

void* find_device	(	EFI_GUID *	guid,
		unsigned int	offset
	)

Locates an UEFI protocol handler, opens and returns it.

UEFI protocols can have multiple handlers attached, use the (0-based) "offset" parameter to determine which handler you want. Usually the handler at offset 0 works fine.

Parameters

guid	the protocol GUID to locate
offset	makes this function return the (0-based) nth handler for the requested protocol

Returns

the protoco handler's address, or NULL on error

Todo:

extract to lib and rename to open_protocol()

find_input_ex()

EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL* find_input_ex

(

)

Finds the protocol handler for SIMPLE_TEXT_INPUT_EX_PROTOCOL.

Returns

the handler's address, or NULL on error

ex_notify()

EFI_STATUS EFIAPI ex_notify

(

EFI_KEY_DATA *

data

)

Callback function for keyboard handler, prints the pressed key(s).

This function gets called on individually registered keystrrokes only.

Parameters

data	the pressed keys' data

Returns

the EFI status code, currently always indicating success

test_ex_notify()

void test_ex_notify

(

)

Registers a listener for a specific key combination and waits for that combination to be pressed.

There are no wildcards allowing to register multiple keys at once and left/right modifier states (e.g. "left shift" vs. "right shift") have to be registered separately. An application needs to register, remember and then unregister handlers for each combination of keys, so this way of reading the keyboard is probably too cumbersome for large amounts of key combinations.

ShellAppMain()

INTN EFIAPI ShellAppMain	(	UINTN	argc,
		CHAR16 **	argv
	)

Main function, gets invoked by UEFI shell.

Parameters

argc	the number of command-line arguments passed
argv	the command-line arguments passed

Returns

an EFI status code for the shell

Variable Documentation

_args

cmdline_argument_t _args[]

static

Initial value:

= {
  {{uint64:0},ARG_INT, NULL,L"-handle",          L"Use (zero-based) nth handle"},
  {{uint64:0},ARG_BOOL,NULL,L"-other-wait-event",L"Use alternate wait event"},
}

command-line arguments