HiiFramework.h@ 23119

Last change on this file since 23119 was 23119, checked in by vboxsync, 15 years ago
re-export EFI
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 32.1 KB

Line
1	/** @file
2	This file defines the Human Interface Infrastructure protocol which will
3	be used by resources which want to publish IFR/Font/String data and have it
4	collected by the Configuration engine.
5
6	Copyright (c) 2007, Intel Corporation All rights reserved.
7
8	This program and the accompanying materials are licensed and made available
9	under the terms and conditions of the BSD License which accompanies this
10	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	File Name: HiiFramework.h
17
18	@par Revision Reference:
19	This protocol is defined in HII spec 0.92.
20
21	**/
22
23	#ifndef _FRAMEWORK_HII_H_
24	#define _FRAMEWORK_HII_H_
25
26	//#include <PiDxe.h>
27
28	//
29	// To get EFI_GRAPHICS_OUTPUT_BLT_PIXEL,
30	// is defined in MdePkg/Protocol/GraphicsOutput.h
31	//
32	#include <Protocol/GraphicsOutput.h>
33
34	#define EFI_HII_PROTOCOL_GUID \
35	{ \
36	0xd7ad636e, 0xb997, 0x459b, {0xbf, 0x3f, 0x88, 0x46, 0x89, 0x79, 0x80, 0xe1} \
37	}
38
39	// BugBug:
40	//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
41	// If UGA goes away we need to put this some place. I'm not sure where?
42	//
43	//typedef struct {
44	// UINT8 Blue;
45	// UINT8 Green;
46	// UINT8 Red;
47	// UINT8 Reserved;
48	//} EFI_UGA_PIXEL;
49
50	//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
51	//
52
53	typedef struct _EFI_HII_PROTOCOL EFI_HII_PROTOCOL;
54
55	//
56	// Global definition
57	//
58	#define NARROW_CHAR 0xFFF0
59	#define WIDE_CHAR 0xFFF1
60	#define NON_BREAKING_CHAR 0xFFF2
61	#define GLYPH_WIDTH 8
62	#define GLYPH_HEIGHT 19
63
64	#define EFI_HII_FONT 1
65	#define EFI_HII_STRING 2
66	#define EFI_HII_IFR 3
67	#define EFI_HII_KEYBOARD 4
68	#define EFI_HII_HANDLES 5
69	#define EFI_HII_VARIABLE 6
70	#define EFI_HII_DEVICE_PATH 7
71
72
73	// References to string tokens must use this macro to enable scanning for
74	// token usages.
75	//
76	#define STRING_TOKEN(t) t
77
78	//
79	// The following types are currently defined:
80	// EFI_FROM_ID has been defined in UEFI spec.
81	//
82	typedef UINT16 EFI_FORM_LABEL;
83
84	#pragma pack(1)
85
86	typedef struct {
87	UINT32 Length;
88	UINT16 Type;
89	} EFI_HII_PACK_HEADER;
90
91	//
92	// A form list consists of a large variety of structure
93	// possibilities so to represent the binary blob of data
94	// associated with a package of forms, we will assume a
95	// pointer to a self-describing data buffer.
96	//
97	typedef struct {
98	EFI_HII_PACK_HEADER Header;
99	} EFI_HII_IFR_PACK;
100
101	typedef struct {
102	EFI_HII_PACK_HEADER Header; // Must be filled in
103	EFI_HANDLE ImageHandle; // Must be filled in
104	EFI_HANDLE DeviceHandle; // Optional
105	EFI_HANDLE ControllerHandle; // Optional
106	EFI_HANDLE CallbackHandle; // Optional
107	EFI_HANDLE COBExportHandle; // Optional
108	} EFI_HII_HANDLE_PACK;
109
110	//
111	// ********************************************************
112	// EFI_VARIABLE_CONTENTS
113	// ********************************************************
114	//
115	typedef struct {
116	EFI_HII_PACK_HEADER Header;
117	EFI_GUID VariableGuid;
118	UINT32 VariableNameLength;
119	UINT16 VariableId;
120	//
121	// CHAR16 VariableName[]; //Null-terminated
122	//
123	} EFI_HII_VARIABLE_PACK;
124
125	//
126	// ********************************************************
127	// EFI_DEVICE_PATH_PACK
128	// ********************************************************
129	//
130	typedef struct {
131	EFI_HII_PACK_HEADER Header;
132	//
133	// EFI_DEVICE_PATH DevicePath[];
134	//
135	} EFI_HII_DEVICE_PATH_PACK;
136
137	//
138	// ********************************************************
139	// EFI_HII_DATA_TABLE
140	// ********************************************************
141	//
142	typedef struct {
143	EFI_HII_HANDLE HiiHandle;
144	EFI_GUID PackageGuid;
145	UINT32 DataTableSize;
146	UINT32 IfrDataOffset;
147	UINT32 StringDataOffset;
148	UINT32 VariableDataOffset;
149	UINT32 DevicePathOffset;
150	UINT32 NumberOfVariableData;
151	UINT32 NumberOfLanguages;
152	//
153	// EFI_HII_DEVICE_PATH_PACK DevicePath[];
154	// EFI_HII_VARIABLE_PACK VariableData[];
155	// EFI_HII_IFR_PACK IfrData;
156	// EFI_HII_STRING_PACK StringData[];
157	//
158	} EFI_HII_DATA_TABLE;
159
160	//
161	// ********************************************************
162	// EFI_HII_EXPORT_TABLE
163	// ********************************************************
164	//
165	typedef struct {
166	UINT32 NumberOfHiiDataTables;
167	EFI_GUID Revision;
168	//
169	// EFI_HII_DATA_TABLE HiiDataTable[];
170	//
171	} EFI_HII_EXPORT_TABLE;
172
173	typedef struct {
174	BOOLEAN FormSetUpdate; // If TRUE, next variable is significant
175	EFI_PHYSICAL_ADDRESS FormCallbackHandle; // If not 0, will update Formset with this info
176	BOOLEAN FormUpdate; // If TRUE, next variable is significant
177	UINT16 FormValue; // specify which form is to be updated if FormUpdate value is TRUE.
178	STRING_REF FormTitle; // If not 0, will update Form with this info
179	UINT16 DataCount; // The number of Data entries in this structure
180	UINT8 *Data; // An array of 1+ op-codes, specified by DataCount
181	} EFI_HII_UPDATE_DATA;
182
183	//
184	// String attributes
185	//
186	#define LANG_RIGHT_TO_LEFT 0x00000001
187
188	//
189	// A string package is used to localize strings to a particular
190	// language. The package is associated with a particular driver
191	// or set of drivers. Tools are used to associate tokens with
192	// string references in forms and in programs. These tokens are
193	// language agnostic. When paired with a language pack (directly
194	// or indirectly), the string token resolves into an actual
195	// UNICODE string. The NumStringPointers determines how many
196	// StringPointers (offset values) there are as well as the total
197	// number of Strings that are defined.
198	//
199	typedef struct {
200	EFI_HII_PACK_HEADER Header;
201	RELOFST LanguageNameString;
202	RELOFST PrintableLanguageName;
203	UINT32 NumStringPointers;
204	UINT32 Attributes;
205	//
206	// RELOFST StringPointers[];
207	// EFI_STRING Strings[];
208	//
209	} EFI_HII_STRING_PACK;
210
211	//
212	// Glyph Attributes
213	//
214	#define EFI_GLYPH_NON_SPACING 1
215	#define EFI_GLYPH_WIDE 2
216
217	typedef struct {
218	CHAR16 UnicodeWeight;
219	UINT8 Attributes;
220	UINT8 GlyphCol1[GLYPH_HEIGHT];
221	} EFI_NARROW_GLYPH;
222
223	typedef struct {
224	CHAR16 UnicodeWeight;
225	UINT8 Attributes;
226	UINT8 GlyphCol1[GLYPH_HEIGHT];
227	UINT8 GlyphCol2[GLYPH_HEIGHT];
228	UINT8 Pad[3];
229	} EFI_WIDE_GLYPH;
230
231	//
232	// A font list consists of a font header followed by a series
233	// of glyph structures. Note that fonts are not language specific.
234	//
235	typedef struct {
236	EFI_HII_PACK_HEADER Header;
237	UINT16 NumberOfNarrowGlyphs;
238	UINT16 NumberOfWideGlyphs;
239	} EFI_HII_FONT_PACK;
240
241	//
242	// The IfrData in the EFI_HII_IFR_PACK structure definition
243	// is variable length, and not really part of the header. To
244	// simplify from code the size of the header, define an
245	// identical structure that does not include the IfrData field.
246	// Then use sizeof() this new structure to determine the
247	// actual size of the header.
248	//
249	typedef struct {
250	EFI_HII_PACK_HEADER Header;
251	} EFI_HII_IFR_PACK_HEADER;
252
253	//
254	// pedef EFI_HII_PACK_HEADER EFI_HII_IFR_PACK_HEADER;
255	//
256	typedef enum {
257	EfiKeyLCtrl,
258	EfiKeyA0,
259	EfiKeyLAlt,
260	EfiKeySpaceBar,
261	EfiKeyA2,
262	EfiKeyA3,
263	EfiKeyA4,
264	EfiKeyRCtrl,
265	EfiKeyLeftArrow,
266	EfiKeyDownArrow,
267	EfiKeyRightArrow,
268	EfiKeyZero,
269	EfiKeyPeriod,
270	EfiKeyEnter,
271	EfiKeyLShift,
272	EfiKeyB0,
273	EfiKeyB1,
274	EfiKeyB2,
275	EfiKeyB3,
276	EfiKeyB4,
277	EfiKeyB5,
278	EfiKeyB6,
279	EfiKeyB7,
280	EfiKeyB8,
281	EfiKeyB9,
282	EfiKeyB10,
283	EfiKeyRshift,
284	EfiKeyUpArrow,
285	EfiKeyOne,
286	EfiKeyTwo,
287	EfiKeyThree,
288	EfiKeyCapsLock,
289	EfiKeyC1,
290	EfiKeyC2,
291	EfiKeyC3,
292	EfiKeyC4,
293	EfiKeyC5,
294	EfiKeyC6,
295	EfiKeyC7,
296	EfiKeyC8,
297	EfiKeyC9,
298	EfiKeyC10,
299	EfiKeyC11,
300	EfiKeyC12,
301	EfiKeyFour,
302	EfiKeyFive,
303	EfiKeySix,
304	EfiKeyPlus,
305	EfiKeyTab,
306	EfiKeyD1,
307	EfiKeyD2,
308	EfiKeyD3,
309	EfiKeyD4,
310	EfiKeyD5,
311	EfiKeyD6,
312	EfiKeyD7,
313	EfiKeyD8,
314	EfiKeyD9,
315	EfiKeyD10,
316	EfiKeyD11,
317	EfiKeyD12,
318	EfiKeyD13,
319	EfiKeyDel,
320	EfiKeyEnd,
321	EfiKeyPgDn,
322	EfiKeySeven,
323	EfiKeyEight,
324	EfiKeyNine,
325	EfiKeyE0,
326	EfiKeyE1,
327	EfiKeyE2,
328	EfiKeyE3,
329	EfiKeyE4,
330	EfiKeyE5,
331	EfiKeyE6,
332	EfiKeyE7,
333	EfiKeyE8,
334	EfiKeyE9,
335	EfiKeyE10,
336	EfiKeyE11,
337	EfiKeyE12,
338	EfiKeyBackSpace,
339	EfiKeyIns,
340	EfiKeyHome,
341	EfiKeyPgUp,
342	EfiKeyNLck,
343	EfiKeySlash,
344	EfiKeyAsterisk,
345	EfiKeyMinus,
346	EfiKeyEsc,
347	EfiKeyF1,
348	EfiKeyF2,
349	EfiKeyF3,
350	EfiKeyF4,
351	EfiKeyF5,
352	EfiKeyF6,
353	EfiKeyF7,
354	EfiKeyF8,
355	EfiKeyF9,
356	EfiKeyF10,
357	EfiKeyF11,
358	EfiKeyF12,
359	EfiKeyPrint,
360	EfiKeySLck,
361	EfiKeyPause
362	} EFI_KEY;
363
364	typedef struct {
365	EFI_KEY Key;
366	CHAR16 Unicode;
367	CHAR16 ShiftedUnicode;
368	CHAR16 AltGrUnicode;
369	CHAR16 ShiftedAltGrUnicode;
370	UINT16 Modifier;
371	} EFI_KEY_DESCRIPTOR;
372
373	//
374	// This structure allows a sparse set of keys to be redefined
375	// or a complete redefinition of the keyboard layout. Most
376	// keyboards have a lot of commonality in their layouts, therefore
377	// only defining those keys that need to change from the default
378	// minimizes the passed in information.
379	//
380	// Additionally, when an update occurs, the active keyboard layout
381	// will be switched to the newly updated keyboard layout. This
382	// allows for situations that when a keyboard layout driver is
383	// loaded as part of system initialization, the system will default
384	// the keyboard behavior to the new layout.
385	//
386	// Each call to update the keyboard mapping should contain the
387	// complete set of key descriptors to be updated, since every
388	// call to the HII which contains an EFI_HII_KEYBOARD_PACK will
389	// wipe the previous set of overrides. A call to
390	//
391	typedef struct {
392	EFI_HII_PACK_HEADER Header;
393	EFI_KEY_DESCRIPTOR *Descriptor;
394	UINT8 DescriptorCount;
395	} EFI_HII_KEYBOARD_PACK;
396
397	//
398	// The EFI_HII_PACKAGES can contain different types of packages just
399	// after the structure as inline data.
400	//
401	typedef struct {
402	UINTN NumberOfPackages;
403	EFI_GUID *GuidId;
404	//
405	// EFI_HII_HANDLE_PACK *HandlePack; // Only one pack.
406	// EFI_HII_IFR_PACK *IfrPack; // Only one pack.
407	// EFI_HII_FONT_PACK *FontPack[]; // Multiple packs ok
408	// EFI_HII_STRING_PACK *StringPack[]; // Multiple packs ok
409	// EFI_HII_KEYBOARD_PACK *KeyboardPack[]; // Multiple packs ok
410	//
411	} EFI_HII_PACKAGES;
412
413	typedef struct _EFI_HII_VARIABLE_PACK_LIST {
414	struct _EFI_HII_VARIABLE_PACK_LIST *NextVariablePack;
415	EFI_HII_VARIABLE_PACK *VariablePack;
416	} EFI_HII_VARIABLE_PACK_LIST;
417
418
419	#pragma pack()
420
421	/**
422	Registers the various packs that are passed in via the Packages parameter.
423
424	@param This A pointer to the EFI_HII_PROTOCOL instance.
425	@param Packages A pointer to an EFI_HII_PACKAGES package instance.
426	@param Handle A pointer to the EFI_HII_HANDLE instance.
427
428	@retval EFI_SUCCESS Data was extracted from Packages, the database
429	was updated with the data, and Handle returned successfully.
430	@retval EFI_INVALID_PARAMETER The content of Packages was invalid.
431
432	**/
433	typedef
434	EFI_STATUS
435	(EFIAPI *EFI_HII_NEW_PACK) (
436	IN EFI_HII_PROTOCOL *This,
437	IN EFI_HII_PACKAGES *Packages,
438	OUT EFI_HII_HANDLE *Handle
439	);
440
441	/**
442	Removes a package from the HII database.
443
444	@param This A pointer to the EFI_HII_PROTOCOL instance.
445	@param Handle The handle that was registered to the data that is requested
446	for removal.
447
448	@retval EFI_SUCCESS The data associated with the Handle was removed
449	from the HII database.
450	@retval EFI_INVALID_PARAMETER The Handle was not valid.
451
452	**/
453	typedef
454	EFI_STATUS
455	(EFIAPI *EFI_HII_REMOVE_PACK) (
456	IN EFI_HII_PROTOCOL *This,
457	IN EFI_HII_HANDLE Handle
458	);
459
460	/**
461	Determines the handles that are currently active in the database.
462
463	@param This A pointer to the EFI_HII_PROTOCOL instance.
464	@param HandleBufferLength On input, a pointer to the length of the handle
465	buffer. On output, the length of the handle buffer that is required
466	for the handles found.
467	@param Handle An array of EFI_HII_HANDLE instances returned.
468
469	@retval EFI_SUCCESS Handle was updated successfully.
470	@retval EFI_BUFFER_TOO_SMALL The HandleBufferLength parameter indicates
471	that Handle is too small to support the number of handles.
472
473	**/
474	typedef
475	EFI_STATUS
476	(EFIAPI *EFI_HII_FIND_HANDLES) (
477	IN EFI_HII_PROTOCOL *This,
478	IN OUT UINT16 *HandleBufferLength,
479	OUT EFI_HII_HANDLE *Handle
480	);
481
482	/**
483	Exports the contents of the database into a buffer.
484
485	@param This A pointer to the EFI_HII_PROTOCOL instance.
486	@param Handle An EFI_HII_HANDLE that corresponds to the desired
487	handle to export. If the value is 0, the entire database will be exported.
488	In either case, the data will be exported in a format described by the
489	structure definition of EFI_HII_EXPORT_TABLE.
490	@param BufferSize
491	On input, a pointer to the length of the buffer. On output, the length
492	of the buffer that is required for the export data.
493	@param Buffer A pointer to a buffer that will contain the results of the export function.
494
495	@retval EFI_SUCCESS The buffer was successfully filled with BufferSize amount of data.
496	@retval EFI_BUFFER_TOO_SMALL The value in BufferSize was too small to contain the export data.
497
498	**/
499	typedef
500	EFI_STATUS
501	(EFIAPI *EFI_HII_EXPORT) (
502	IN EFI_HII_PROTOCOL *This,
503	IN EFI_HII_HANDLE Handle,
504	IN OUT UINTN *BufferSize,
505	OUT VOID *Buffer
506	);
507
508	/**
509	Remove any new strings that were added after the initial string export
510	for this handle.
511
512	@param This A pointer to the EFI_HII_PROTOCOL instance.
513	@param Handle The handle on which the string resides.
514
515	@retval EFI_SUCCESS Remove strings from the handle successfully.
516	@retval EFI_INVALID_PARAMETER The Handle was unknown.
517
518	**/
519	typedef
520	EFI_STATUS
521	(EFIAPI *EFI_HII_RESET_STRINGS) (
522	IN EFI_HII_PROTOCOL *This,
523	IN EFI_HII_HANDLE Handle
524	);
525
526	/**
527	Tests if all of the characters in a string have corresponding font characters.
528
529	@param This A pointer to the EFI_HII_PROTOCOL instance.
530	@param StringToTest A pointer to a Unicode string.
531	@param FirstMissing A pointer to an index into the string. On input,
532	the index of the first character in the StringToTest to examine. On exit,
533	the index of the first character encountered for which a glyph is unavailable.
534	If all glyphs in the string are available, the index is the index of the
535	terminator of the string.
536	@param GlyphBufferSize A pointer to a value. On output, if the function
537	returns EFI_SUCCESS, it contains the amount of memory that is required to
538	store the string's glyph equivalent.
539
540	@retval EFI_SUCCESS All glyphs are available. Note that an empty string
541	always returns this value.
542	@retval EFI_NOT_FOUND A glyph was not found for a character.
543
544	**/
545	typedef
546	EFI_STATUS
547	(EFIAPI *EFI_HII_TEST_STRING) (
548	IN EFI_HII_PROTOCOL *This,
549	IN CHAR16 *StringToTest,
550	IN OUT UINT32 *FirstMissing,
551	OUT UINT32 *GlyphBufferSize
552	);
553
554	/**
555	Translates a Unicode character into the corresponding font glyph.
556
557	@param This A pointer to the EFI_HII_PROTOCOL instance.
558	@param Source A pointer to a Unicode string.
559	@param Index On input, the offset into the string from which to fetch
560	the character.On successful completion, the index is updated to the first
561	character past the character(s) making up the just extracted glyph.
562	@param GlyphBuffer Pointer to an array where the glyphs corresponding
563	to the characters in the source may be stored. GlyphBuffer is assumed
564	to be wide enough to accept a wide glyph character.
565	@param BitWidth If EFI_SUCCESS was returned, the UINT16 pointed to by
566	this value is filled with the length of the glyph in pixels. It is unchanged
567	if the call was unsuccessful.
568	@param InternalStatus The cell pointed to by this parameter must be
569	initialized to zero prior to invoking the call the first time for any string.
570
571	@retval EFI_SUCCESS It worked.
572	@retval EFI_NOT_FOUND A glyph for a character was not found.
573
574	**/
575	typedef
576	EFI_STATUS
577	(EFIAPI *EFI_HII_GET_GLYPH) (
578	IN EFI_HII_PROTOCOL *This,
579	IN CHAR16 *Source,
580	IN OUT UINT16 *Index,
581	OUT UINT8 **GlyphBuffer,
582	OUT UINT16 *BitWidth,
583	IN OUT UINT32 *InternalStatus
584	);
585
586	/**
587	Translates a glyph into the format required for input to the Universal
588	Graphics Adapter (UGA) Block Transfer (BLT) routines.
589
590	@param This A pointer to the EFI_HII_PROTOCOL instance.
591	@param GlyphBuffer A pointer to the buffer that contains glyph data.
592	@param Foreground The foreground setting requested to be used for the
593	generated BltBuffer data.
594	@param Background The background setting requested to be used for the
595	generated BltBuffer data.
596	@param Count The entry in the BltBuffer upon which to act.
597	@param Width The width in bits of the glyph being converted.
598	@param Height The height in bits of the glyph being converted
599	@param BltBuffer A pointer to the buffer that contains the data that is
600	ready to be used by the UGA BLT routines.
601
602	@retval EFI_SUCCESS It worked.
603	@retval EFI_NOT_FOUND A glyph for a character was not found.
604
605	**/
606	typedef
607	EFI_STATUS
608	(EFIAPI *EFI_HII_GLYPH_TO_BLT) (
609	IN EFI_HII_PROTOCOL *This,
610	IN UINT8 *GlyphBuffer,
611	IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL Foreground,
612	IN EFI_GRAPHICS_OUTPUT_BLT_PIXEL Background,
613	IN UINTN Count,
614	IN UINTN Width,
615	IN UINTN Height,
616	IN OUT EFI_GRAPHICS_OUTPUT_BLT_PIXEL *BltBuffer
617	);
618
619	/**
620	Allows a new string to be added to an already existing string package.
621
622	@param This A pointer to the EFI_HII_PROTOCOL instance.
623	@param Pointer to a NULL-terminated string containing a single ISO 639-2
624	language identifier, indicating the language in which the string is translated.
625	@param Handle The handle of the language pack to which the string is to be added.
626	@param Reference The identifier of the string to be added. If the reference
627	value is zero, then the string will be assigned a new identifier on that
628	handle for the language specified. Otherwise, the string will be updated
629	with the NewString Value.
630	@param NewString The string to be added.
631
632	@retval EFI_SUCCESS The string was effectively registered.
633	@retval EFI_INVALID_PARAMETER The Handle was unknown.
634
635	**/
636	typedef
637	EFI_STATUS
638	(EFIAPI *EFI_HII_NEW_STRING) (
639	IN EFI_HII_PROTOCOL *This,
640	IN CHAR16 *Language,
641	IN EFI_HII_HANDLE Handle,
642	IN OUT STRING_REF *Reference,
643	IN CHAR16 *NewString
644	);
645
646	/**
647	Allows a program to determine the primary languages that are supported
648	on a given handle.
649
650	@param This A pointer to the EFI_HII_PROTOCOL instance.
651	@param Handle The handle on which the strings reside.
652	@param LanguageString A string allocated by GetPrimaryLanguages() that
653	contains a list of all primary languages registered on the handle.
654
655	@retval EFI_SUCCESS LanguageString was correctly returned.
656	@retval EFI_INVALID_PARAMETER The Handle was unknown.
657
658	**/
659	typedef
660	EFI_STATUS
661	(EFIAPI *EFI_HII_GET_PRI_LANGUAGES) (
662	IN EFI_HII_PROTOCOL *This,
663	IN EFI_HII_HANDLE Handle,
664	OUT EFI_STRING *LanguageString
665	);
666
667	/**
668	Allows a program to determine which secondary languages are supported
669	on a given handle for a given primary language.
670
671	@param This A pointer to the EFI_HII_PROTOCOL instance.
672	@param Handle The handle on which the strings reside.
673	@param PrimaryLanguage Pointer to a NULL-terminated string containing a single
674	ISO 639-2 language identifier, indicating the primary language.
675	@param LanguageString A string allocated by GetSecondaryLanguages()
676	containing a list of all secondary languages registered on the handle.
677
678	@retval EFI_SUCCESS LanguageString was correctly returned.
679	@retval EFI_INVALID_PARAMETER The Handle was unknown.
680
681	**/
682	typedef
683	EFI_STATUS
684	(EFIAPI *EFI_HII_GET_SEC_LANGUAGES) (
685	IN EFI_HII_PROTOCOL *This,
686	IN EFI_HII_HANDLE Handle,
687	IN CHAR16 *PrimaryLanguage,
688	OUT EFI_STRING *LanguageString
689	);
690
691	/**
692	Extracts a string from a package already registered with the EFI HII database.
693
694	@param This A pointer to the EFI_HII_PROTOCOL instance.
695	@param Handle The handle on which the string resides.
696	@param Token The string token assigned to the string.
697	@param Raw If TRUE, the string is returned unedited in the internal
698	storage format described above. If false, the string returned is edited
699	by replacing <cr> with <space> and by removing special characters such
700	as the <wide> prefix.
701	@param LanguageString Pointer to a NULL-terminated string containing a
702	single ISO 639-2 language identifier, indicating the language to print.
703	If the LanguageString is empty (starts with a NULL), the default system
704	language will be used to determine the language.
705	@param BufferLength Length of the StringBuffer.
706	@param StringBuffer The buffer designed to receive the characters in the string.
707
708	@retval EFI_SUCCESS StringBuffer is filled with a NULL-terminated string.
709	@retval EFI_INVALID_PARAMETER The handle or string token is unknown.
710	@retval EFI_BUFFER_TOO_SMALL The buffer provided was not large enough to
711	allow the entire string to be stored.
712
713	**/
714	typedef
715	EFI_STATUS
716	(EFIAPI *EFI_HII_GET_STRING) (
717	IN EFI_HII_PROTOCOL *This,
718	IN EFI_HII_HANDLE Handle,
719	IN STRING_REF Token,
720	IN BOOLEAN Raw,
721	IN CHAR16 *LanguageString,
722	IN OUT UINTN *BufferLength,
723	OUT EFI_STRING StringBuffer
724	);
725
726	/**
727	Allows a program to extract a part of a string of not more than a given width.
728
729	@param This A pointer to the EFI_HII_PROTOCOL instance.
730	@param Handle The handle on which the string resides.
731	@param Token The string token assigned to the string.
732	@param Index On input, the offset into the string where the line is to start.
733	On output, the index is updated to point to beyond the last character returned
734	in the call.
735	@param LineWidth The maximum width of the line in units of narrow glyphs.
736	@param LanguageString Pointer to a NULL-terminated string containing a
737	single ISO 639-2 language identifier, indicating the language to print.
738	@param BufferLength Pointer to the length of the StringBuffer.
739	@param StringBuffer The buffer designed to receive the characters in the string.
740
741	@retval EFI_SUCCESS StringBuffer filled with characters that will fit on the line.
742	@retval EFI_NOT_FOUND The font glyph for at least one of the characters in
743	the string is not in the font database.
744	@retval EFI_BUFFER_TOO_SMALL The buffer provided was not large enough
745	to allow the entire string to be stored.
746
747	**/
748	typedef
749	EFI_STATUS
750	(EFIAPI *EFI_HII_GET_LINE) (
751	IN EFI_HII_PROTOCOL *This,
752	IN EFI_HII_HANDLE Handle,
753	IN STRING_REF Token,
754	IN OUT UINT16 *Index,
755	IN UINT16 LineWidth,
756	IN CHAR16 *LanguageString,
757	IN OUT UINT16 *BufferLength,
758	OUT EFI_STRING StringBuffer
759	);
760
761	/**
762	Allows a program to extract a form or form package that has previously
763	been registered with the HII database.
764
765	@param This A pointer to the EFI_HII_PROTOCOL instance.
766	@param Handle Handle on which the form resides.
767	@param FormId The ID of the form to return. If the ID is zero,
768	the entire form package is returned.
769	@param BufferLength On input, the length of the Buffer. On output,
770	the length of the returned buffer,
771	@param Buffer The buffer designed to receive the form(s).
772
773	@retval EFI_SUCCESS Buffer filled with the requested forms. BufferLength
774	was updated.
775	@retval EFI_INVALID_PARAMETER The handle is unknown.
776	@retval EFI_NOT_FOUND A form on the requested handle cannot be found with
777	the requested FormId.
778	@retval EFI_BUFFER_TOO_SMALL The buffer provided was not large enough
779	to allow the form to be stored.
780
781	**/
782	typedef
783	EFI_STATUS
784	(EFIAPI *EFI_HII_GET_FORMS) (
785	IN EFI_HII_PROTOCOL *This,
786	IN EFI_HII_HANDLE Handle,
787	IN EFI_FORM_ID FormId,
788	IN OUT UINTN *BufferLength,
789	OUT UINT8 *Buffer
790	);
791
792	/**
793	Extracts the defaults that are associated with a given handle in the HII database.
794
795	@param This A pointer to the EFI_HII_PROTOCOL instance.
796	@param Handle The HII handle from which will have default data retrieved.
797	@param DefaultMask The mask used to specify some type of default override when extracting
798	the default image data.
799	@param VariablePackList A indirect pointer to the first entry of a link list with
800	type EFI_HII_VARIABLE_PACK_LIST.
801
802	@retval EFI_SUCCESS The VariablePackList was populated with the appropriate
803	default setting data.
804	@retval EFI_NOT_FOUND The IFR does not have any explicit or default map(s).
805	@retval EFI_INVALID_PARAMETER The HII database entry associated with Handle
806	contain invalid data.
807
808	**/
809	typedef
810	EFI_STATUS
811	(EFIAPI *EFI_HII_GET_DEFAULT_IMAGE) (
812	IN EFI_HII_PROTOCOL *This,
813	IN EFI_HII_HANDLE Handle,
814	IN UINTN DefaultMask,
815	OUT EFI_HII_VARIABLE_PACK_LIST **VariablePackList
816	);
817
818	/**
819	Allows the caller to update a form or form package that has previously been
820	registered with the EFI HII database.
821
822	@param This A pointer to the EFI_HII_PROTOCOL instance.
823	@param Handle Handle of the package where the form to be updated resides.
824	@param Label The label inside the form package where the update is to take place.
825	@param AddData If TRUE, adding data at a given Label; otherwise,
826	if FALSE, removing data at a given Label.
827	@param Data The buffer containing the new tags to insert after the Label
828
829	@retval EFI_SUCCESS The form was updated with the new tags.
830	@retval EFI_INVALID_PARAMETER The buffer for the buffer length does not
831	contain an integral number of tags.
832	@retval EFI_NOT_FOUND The Handle, Label, or FormId was not found.
833
834	**/
835	typedef
836	EFI_STATUS
837	(EFIAPI *EFI_HII_UPDATE_FORM) (
838	IN EFI_HII_PROTOCOL *This,
839	IN EFI_HII_HANDLE Handle,
840	IN EFI_FORM_LABEL Label,
841	IN BOOLEAN AddData,
842	IN EFI_HII_UPDATE_DATA *Data
843	);
844
845	/**
846	Retrieves the current keyboard layout.
847
848	@param This A pointer to the EFI_HII_PROTOCOL instance.
849	@param DescriptorCount A pointer to the number of Descriptor entries being
850	described in the keyboard layout being retrieved.
851	@param Descriptor A pointer to a buffer containing an array of EFI_KEY_DESCRIPTOR
852	entries. Each entry will reflect the definition of a specific physical key.
853
854	@retval EFI_SUCCESS The keyboard layout was retrieved successfully.
855
856	**/
857	typedef
858	EFI_STATUS
859	(EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) (
860	IN EFI_HII_PROTOCOL *This,
861	OUT UINT16 *DescriptorCount,
862	OUT EFI_KEY_DESCRIPTOR *Descriptor
863	);
864
865	/**
866	@par Protocol Description:
867	The HII Protocol manages the HII database, which is a repository for data
868	having to do with fonts, strings, forms, keyboards, and other future human
869	interface items.
870
871	@param NewPack
872	Extracts the various packs from a package list.
873
874	@param RemovePack
875	Removes a package from the HII database.
876
877	@param FindHandles
878	Determines the handles that are currently active in the database.
879
880	@param ExportDatabase
881	Export the entire contents of the database to a buffer.
882
883	@param TestString
884	Tests if all of the characters in a string have corresponding font characters.
885
886	@param GetGlyph
887	Translates a Unicode character into the corresponding font glyph.
888
889	@param GlyphToBlt
890	Converts a glyph value into a format that is ready for a UGA BLT command.
891
892	@param NewString
893	Allows a new string to be added to an already existing string package.
894
895	@param GetPrimaryLanguages
896	Allows a program to determine the primary languages that are supported
897	on a given handle.
898
899	@param GetSecondaryLanguages
900	Allows a program to determine which secondary languages are supported
901	on a given handle for a given primary language.
902
903	@param GetString
904	Extracts a string from a package that is already registered with the
905	EFI HII database.
906
907	@param ResetString
908	Remove any new strings that were added after the initial string export
909	for this handle.
910
911	@param GetLine
912	Allows a program to extract a part of a string of not more than a given width.
913
914	@param GetForms
915	Allows a program to extract a form or form package that has been previously registered.
916
917	@param GetDefaultImage
918	Allows a program to extract the nonvolatile image that represents the default storage image.
919
920	@param UpdateForm
921	Allows a program to update a previously registered form.
922
923	@param GetKeyboardLayout
924	Allows a program to extract the current keyboard layout.
925
926	**/
927	struct _EFI_HII_PROTOCOL {
928	EFI_HII_NEW_PACK NewPack;
929	EFI_HII_REMOVE_PACK RemovePack;
930	EFI_HII_FIND_HANDLES FindHandles;
931	EFI_HII_EXPORT ExportDatabase;
932
933	EFI_HII_TEST_STRING TestString;
934	EFI_HII_GET_GLYPH GetGlyph;
935	EFI_HII_GLYPH_TO_BLT GlyphToBlt;
936
937	EFI_HII_NEW_STRING NewString;
938	EFI_HII_GET_PRI_LANGUAGES GetPrimaryLanguages;
939	EFI_HII_GET_SEC_LANGUAGES GetSecondaryLanguages;
940	EFI_HII_GET_STRING GetString;
941	EFI_HII_RESET_STRINGS ResetStrings;
942	EFI_HII_GET_LINE GetLine;
943	EFI_HII_GET_FORMS GetForms;
944	EFI_HII_GET_DEFAULT_IMAGE GetDefaultImage;
945	EFI_HII_UPDATE_FORM UpdateForm;
946
947	EFI_HII_GET_KEYBOARD_LAYOUT GetKeyboardLayout;
948	};
949
950	extern EFI_GUID gEfiHiiProtocolGuid;
951
952	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/tools/include/Protocol/HiiFramework.h@ 23119

Download in other formats: