HiiLib.h@ 77662

Last change on this file since 77662 was 77662, checked in by vboxsync, 6 years ago
EFI: First step in UDK2018 merge. Does not build yet.
Property svn:eol-style set to `native`
File size: 43.1 KB

Line
1	/** @file
2	Public include file for the HII Library
3
4	Copyright (c) 2007 - 2013, Intel Corporation. All rights reserved.<BR>
5	This program and the accompanying materials are licensed and made available under
6	the terms and conditions of the BSD License that accompanies this distribution.
7	The full text of the license may be found at
8	http://opensource.org/licenses/bsd-license.php.
9
10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13	**/
14
15	#ifndef __HII_LIB_H__
16	#define __HII_LIB_H__
17
18	////////////////////////////////////////////////////////
19	////////////////////////////////////////////////////////
20	// HiiLib Functions
21	////////////////////////////////////////////////////////
22	////////////////////////////////////////////////////////
23
24	/**
25	Registers a list of packages in the HII Database and returns the HII Handle
26	associated with that registration. If an HII Handle has already been registered
27	with the same PackageListGuid and DeviceHandle, then NULL is returned. If there
28	are not enough resources to perform the registration, then NULL is returned.
29	If an empty list of packages is passed in, then NULL is returned. If the size of
30	the list of package is 0, then NULL is returned.
31
32	The variable arguments are pointers that point to package headers defined
33	by UEFI VFR compiler and StringGather tool.
34
35	#pragma pack (push, 1)
36	typedef struct {
37	UINT32 BinaryLength;
38	EFI_HII_PACKAGE_HEADER PackageHeader;
39	} EDKII_AUTOGEN_PACKAGES_HEADER;
40	#pragma pack (pop)
41
42	@param[in] PackageListGuid The GUID of the package list.
43	@param[in] DeviceHandle If not NULL, the Device Handle on which
44	an instance of DEVICE_PATH_PROTOCOL is installed.
45	This Device Handle uniquely defines the device that
46	the added packages are associated with.
47	@param[in] ... The variable argument list that contains pointers
48	to packages terminated by a NULL.
49
50	@retval NULL An HII Handle has already been registered in the HII Database with
51	the same PackageListGuid and DeviceHandle.
52	@retval NULL The HII Handle could not be created.
53	@retval NULL An empty list of packages was passed in.
54	@retval NULL All packages are empty.
55	@retval Other The HII Handle associated with the newly registered package list.
56
57	**/
58	EFI_HII_HANDLE
59	EFIAPI
60	HiiAddPackages (
61	IN CONST EFI_GUID *PackageListGuid,
62	IN EFI_HANDLE DeviceHandle OPTIONAL,
63	...
64	)
65	;
66
67	/**
68	Removes a package list from the HII database.
69
70	If HiiHandle is NULL, then ASSERT().
71	If HiiHandle is not a valid EFI_HII_HANDLE in the HII database, then ASSERT().
72
73	@param[in] HiiHandle The handle that was previously registered in the HII database
74
75	**/
76	VOID
77	EFIAPI
78	HiiRemovePackages (
79	IN EFI_HII_HANDLE HiiHandle
80	)
81	;
82
83	/**
84	This function creates a new string in String Package or updates an existing
85	string in a String Package. If StringId is 0, then a new string is added to
86	a String Package. If StringId is not zero, then a string in String Package is
87	updated. If SupportedLanguages is NULL, then the string is added or updated
88	for all the languages that the String Package supports. If SupportedLanguages
89	is not NULL, then the string is added or updated for the set of languages
90	specified by SupportedLanguages.
91
92	If HiiHandle is NULL, then ASSERT().
93	If String is NULL, then ASSERT().
94
95	@param[in] HiiHandle A handle that was previously registered in the
96	HII Database.
97	@param[in] StringId If zero, then a new string is created in the
98	String Package associated with HiiHandle. If
99	non-zero, then the string specified by StringId
100	is updated in the String Package associated
101	with HiiHandle.
102	@param[in] String A pointer to the Null-terminated Unicode string
103	to add or update in the String Package associated
104	with HiiHandle.
105	@param[in] SupportedLanguages A pointer to a Null-terminated ASCII string of
106	language codes. If this parameter is NULL, then
107	String is added or updated in the String Package
108	associated with HiiHandle for all the languages
109	that the String Package supports. If this
110	parameter is not NULL, then String is added
111	or updated in the String Package associated with
112	HiiHandle for the set of languages specified by
113	SupportedLanguages. The format of
114	SupportedLanguages must follow the language
115	format assumed in the HII Database.
116
117	@retval 0 The string could not be added or updated in the String Package.
118	@retval Other The EFI_STRING_ID of the newly added or updated string.
119
120	**/
121	EFI_STRING_ID
122	EFIAPI
123	HiiSetString (
124	IN EFI_HII_HANDLE HiiHandle,
125	IN EFI_STRING_ID StringId, OPTIONAL
126	IN CONST EFI_STRING String,
127	IN CONST CHAR8 *SupportedLanguages OPTIONAL
128	)
129	;
130
131	/**
132	Retrieves a string from a string package in a specific language. If the language
133	is not specified, then a string from a string package in the current platform
134	language is retrieved. If the string cannot be retrieved using the specified
135	language or the current platform language, then the string is retrieved from
136	the string package in the first language the string package supports. The
137	returned string is allocated using AllocatePool(). The caller is responsible
138	for freeing the allocated buffer using FreePool().
139
140	If HiiHandle is NULL, then ASSERT().
141	If StringId is 0, then ASSERT().
142
143	@param[in] HiiHandle A handle that was previously registered in the HII Database.
144	@param[in] StringId The identifier of the string to retrieved from the string
145	package associated with HiiHandle.
146	@param[in] Language The language of the string to retrieve. If this parameter
147	is NULL, then the current platform language is used. The
148	format of Language must follow the language format assumed in
149	the HII Database.
150
151	@retval NULL The string specified by StringId is not present in the string package.
152	@retval Other The string was returned.
153
154	**/
155	EFI_STRING
156	EFIAPI
157	HiiGetString (
158	IN EFI_HII_HANDLE HiiHandle,
159	IN EFI_STRING_ID StringId,
160	IN CONST CHAR8 *Language OPTIONAL
161	)
162	;
163
164	/**
165	Retrieves a string from a string package named by GUID, in the specified language.
166	If the language is not specified, then a string from a string package in the
167	current platform language is retrieved. If the string cannot be retrieved
168	using the specified language or the current platform language, then the string
169	is retrieved from the string package in the first language the string package
170	supports. The returned string is allocated using AllocatePool(). The caller
171	is responsible for freeing the allocated buffer using FreePool().
172
173	If PackageListGuid is NULL, then ASSERT().
174	If StringId is 0, then ASSERT().
175
176	@param[in] PackageListGuid The GUID of a package list that was previously
177	registered in the HII Database.
178	@param[in] StringId The identifier of the string to retrieved from the
179	string package associated with PackageListGuid.
180	@param[in] Language The language of the string to retrieve. If this
181	parameter is NULL, then the current platform
182	language is used. The format of Language must
183	follow the language format assumed in the HII Database.
184
185	@retval NULL The package list specified by PackageListGuid is not present in the
186	HII Database.
187	@retval NULL The string specified by StringId is not present in the string package.
188	@retval Other The string was returned.
189
190	**/
191	EFI_STRING
192	EFIAPI
193	HiiGetPackageString (
194	IN CONST EFI_GUID *PackageListGuid,
195	IN EFI_STRING_ID StringId,
196	IN CONST CHAR8 *Language OPTIONAL
197	)
198	;
199
200	/**
201	Retrieves the array of all the HII Handles or the HII handles of a specific
202	package list GUID in the HII Database.
203	This array is terminated with a NULL HII Handle.
204	This function allocates the returned array using AllocatePool().
205	The caller is responsible for freeing the array with FreePool().
206
207	@param[in] PackageListGuid An optional parameter that is used to request
208	HII Handles associated with a specific
209	Package List GUID. If this parameter is NULL,
210	then all the HII Handles in the HII Database
211	are returned. If this parameter is not NULL,
212	then zero or more HII Handles associated with
213	PackageListGuid are returned.
214
215	@retval NULL No HII handles were found in the HII database
216	@retval NULL The array of HII Handles could not be retrieved
217	@retval Other A pointer to the NULL terminated array of HII Handles
218
219	**/
220	EFI_HII_HANDLE *
221	EFIAPI
222	HiiGetHiiHandles (
223	IN CONST EFI_GUID *PackageListGuid OPTIONAL
224	)
225	;
226
227	/**
228	This function allows a caller to extract the form set opcode form the Hii Handle.
229	The returned buffer is allocated using AllocatePool().The caller is responsible
230	for freeing the allocated buffer using FreePool().
231
232	@param Handle The HII handle.
233	@param Buffer On return, points to a pointer which point to the buffer that contain the formset opcode.
234	@param BufferSize On return, points to the length of the buffer.
235
236	@retval EFI_OUT_OF_RESOURCES No enough memory resource is allocated.
237	@retval EFI_NOT_FOUND Can't find the package data for the input Handle.
238	@retval EFI_INVALID_PARAMETER The input parameters are not correct.
239	@retval EFI_SUCCESS Get the formset opcode from the hii handle successfully.
240
241	**/
242	EFI_STATUS
243	EFIAPI
244	HiiGetFormSetFromHiiHandle(
245	IN EFI_HII_HANDLE Handle,
246	OUT EFI_IFR_FORM_SET **Buffer,
247	OUT UINTN *BufferSize
248	);
249
250	/**
251	Retrieves a pointer to a Null-terminated ASCII string containing the list
252	of languages that an HII handle in the HII Database supports. The returned
253	string is allocated using AllocatePool(). The caller is responsible for freeing
254	the returned string using FreePool(). The format of the returned string follows
255	the language format assumed in the HII Database.
256
257	If HiiHandle is NULL, then ASSERT().
258
259	@param[in] HiiHandle A handle that was previously registered in the HII Database.
260
261	@retval NULL HiiHandle is not registered in the HII database
262	@retval NULL There are not enough resources available to retrieve the supported
263	languages.
264	@retval NULL The list of supported languages could not be retrieved.
265	@retval Other A pointer to the Null-terminated ASCII string of supported languages.
266
267	**/
268	CHAR8 *
269	EFIAPI
270	HiiGetSupportedLanguages (
271	IN EFI_HII_HANDLE HiiHandle
272	)
273	;
274
275	/**
276	Allocates and returns a Null-terminated Unicode <ConfigHdr> string using routing
277	information that includes a GUID, an optional Unicode string name, and a device
278	path. The string returned is allocated with AllocatePool(). The caller is
279	responsible for freeing the allocated string with FreePool().
280
281	The format of a <ConfigHdr> is as follows:
282
283	GUID=<HexCh>32&NAME=<Char>NameLength&PATH=<HexChar>DevicePathSize<Null>
284
285	@param[in] Guid The pointer to an EFI_GUID that is the routing information
286	GUID. Each of the 16 bytes in Guid is converted to
287	a 2 Unicode character hexadecimal string. This is
288	an optional parameter that may be NULL.
289	@param[in] Name The pointer to a Null-terminated Unicode string that is
290	the routing information NAME. This is an optional
291	parameter that may be NULL. Each 16-bit Unicode
292	character in Name is converted to a 4 character Unicode
293	hexadecimal string.
294	@param[in] DriverHandle The driver handle that supports a Device Path Protocol
295	that is the routing information PATH. Each byte of
296	the Device Path associated with DriverHandle is converted
297	to a two (Unicode) character hexadecimal string.
298
299	@retval NULL DriverHandle does not support the Device Path Protocol.
300	@retval NULL DriverHandle does not support the Device Path Protocol.
301	@retval Other A pointer to the Null-terminate Unicode <ConfigHdr> string
302
303	**/
304	EFI_STRING
305	EFIAPI
306	HiiConstructConfigHdr (
307	IN CONST EFI_GUID *Guid, OPTIONAL
308	IN CONST CHAR16 *Name, OPTIONAL
309	IN EFI_HANDLE DriverHandle
310	);
311
312	/**
313	Reset the default value specified by DefaultId to the driver
314	configuration specified by the Request string.
315
316	NULL request string support depends on the ExportConfig interface of
317	HiiConfigRouting protocol in UEFI specification.
318
319	@param Request A null-terminated Unicode string in
320	<MultiConfigRequest> format. It can be NULL.
321	If it is NULL, all configurations for the
322	entirety of the current HII database will be reset.
323	@param DefaultId Specifies the type of defaults to retrieve.
324
325	@retval TRUE The default value was set successfully.
326	@retval FALSE The default value was not found.
327	**/
328	BOOLEAN
329	EFIAPI
330	HiiSetToDefaults (
331	IN CONST EFI_STRING Request, OPTIONAL
332	IN UINT16 DefaultId
333	);
334
335	/**
336	Validate the current configuration by parsing the IFR opcode in HII form.
337
338	NULL request string support depends on the ExportConfig interface of
339	HiiConfigRouting protocol in the UEFI specification.
340
341	@param Request A null-terminated Unicode string in
342	<MultiConfigRequest> format. It can be NULL.
343	If it is NULL, all current configurations for the
344	entirety of the current HII database will be validated.
345
346	@retval TRUE The current configuration is valid.
347	@retval FALSE The current configuration is invalid.
348	**/
349	BOOLEAN
350	EFIAPI
351	HiiValidateSettings (
352	IN CONST EFI_STRING Request OPTIONAL
353	);
354
355	/**
356	Determines if the routing data specified by GUID and NAME match a <ConfigHdr>.
357
358	If ConfigHdr is NULL, then ASSERT().
359
360	@param[in] ConfigHdr Either <ConfigRequest> or <ConfigResp>.
361	@param[in] Guid The GUID of the storage.
362	@param[in] Name The NAME of the storage.
363
364	@retval TRUE Routing information matches <ConfigHdr>.
365	@retval FALSE Routing information does not match <ConfigHdr>.
366
367	**/
368	BOOLEAN
369	EFIAPI
370	HiiIsConfigHdrMatch (
371	IN CONST EFI_STRING ConfigHdr,
372	IN CONST EFI_GUID *Guid, OPTIONAL
373	IN CONST CHAR16 *Name OPTIONAL
374	);
375
376	/**
377	Retrieves uncommitted data from the Form Browser and converts it to a binary
378	buffer.
379
380	@param[in] VariableGuid The pointer to an EFI_GUID structure. This is an optional
381	parameter that may be NULL.
382	@param[in] VariableName The pointer to a Null-terminated Unicode string. This
383	is an optional parameter that may be NULL.
384	@param[in] BufferSize The length in bytes of buffer to hold retrieved data.
385	@param[out] Buffer The buffer of data to be updated.
386
387	@retval FALSE The uncommitted data could not be retrieved.
388	@retval TRUE The uncommitted data was retrieved.
389
390	**/
391	BOOLEAN
392	EFIAPI
393	HiiGetBrowserData (
394	IN CONST EFI_GUID *VariableGuid, OPTIONAL
395	IN CONST CHAR16 *VariableName, OPTIONAL
396	IN UINTN BufferSize,
397	OUT UINT8 *Buffer
398	);
399
400	/**
401	Updates uncommitted data in the Form Browser.
402
403	If Buffer is NULL, then ASSERT().
404
405	@param[in] VariableGuid The pointer to an EFI_GUID structure. This is an optional
406	parameter that may be NULL.
407	@param[in] VariableName The pointer to a Null-terminated Unicode string. This
408	is an optional parameter that may be NULL.
409	@param[in] BufferSize The length, in bytes, of Buffer.
410	@param[in] Buffer The buffer of data to commit.
411	@param[in] RequestElement An optional field to specify which part of the
412	buffer data will be send back to Browser. If NULL,
413	the whole buffer of data will be committed to
414	Browser.
415	<RequestElement> ::= &OFFSET=<Number>&WIDTH=<Number>*
416
417	@retval FALSE The uncommitted data could not be updated.
418	@retval TRUE The uncommitted data was updated.
419
420	**/
421	BOOLEAN
422	EFIAPI
423	HiiSetBrowserData (
424	IN CONST EFI_GUID *VariableGuid, OPTIONAL
425	IN CONST CHAR16 *VariableName, OPTIONAL
426	IN UINTN BufferSize,
427	IN CONST UINT8 *Buffer,
428	IN CONST CHAR16 *RequestElement OPTIONAL
429	);
430
431	/////////////////////////////////////////
432	/////////////////////////////////////////
433	/// IFR Functions
434	/////////////////////////////////////////
435	/////////////////////////////////////////
436
437	/**
438	Returns a UINT64 value that contains bitfields for Hour, Minute, and Second.
439	The lower 8-bits of Hour are placed in bits 0..7. The lower 8-bits of Minute
440	are placed in bits 8..15, and the lower 8-bits of Second are placed in bits
441	16..23. This format was selected because it can be easily translated to
442	an EFI_HII_TIME structure in an EFI_IFR_TYPE_VALUE union.
443
444	@param Hour The hour value to be encoded.
445	@param Minute The minute value to be encoded.
446	@param Second The second value to be encoded.
447
448	@return A 64-bit containing Hour, Minute, and Second.
449	**/
450	#define EFI_HII_TIME_UINT64(Hour, Minute, Second) \
451	(UINT64)((Hour & 0xff) \| ((Minute & 0xff) << 8) \| ((Second & 0xff) << 16))
452
453	/**
454	Returns a UINT64 value that contains bit fields for Year, Month, and Day.
455	The lower 16-bits of Year are placed in bits 0..15. The lower 8-bits of Month
456	are placed in bits 16..23, and the lower 8-bits of Day are placed in bits
457	24..31. This format was selected because it can be easily translated to
458	an EFI_HII_DATE structure in an EFI_IFR_TYPE_VALUE union.
459
460	@param Year The year value to be encoded.
461	@param Month The month value to be encoded.
462	@param Day The day value to be encoded.
463
464	@return A 64-bit containing Year, Month, and Day.
465	**/
466	#define EFI_HII_DATE_UINT64(Year, Month, Day) \
467	(UINT64)((Year & 0xffff) \| ((Month & 0xff) << 16) \| ((Day & 0xff) << 24))
468
469	/**
470	Allocates and returns a new OpCode Handle. OpCode Handles must be freed with
471	HiiFreeOpCodeHandle().
472
473	@retval NULL There are not enough resources to allocate a new OpCode Handle.
474	@retval Other A new OpCode handle.
475
476	**/
477	VOID *
478	EFIAPI
479	HiiAllocateOpCodeHandle (
480	VOID
481	);
482
483	/**
484	Frees an OpCode Handle that was previously allocated with HiiAllocateOpCodeHandle().
485	When an OpCode Handle is freed, all of the opcodes associated with the OpCode
486	Handle are also freed.
487
488	If OpCodeHandle is NULL, then ASSERT().
489
490	@param[in] OpCodeHandle The handle to the buffer of opcodes.
491
492	**/
493	VOID
494	EFIAPI
495	HiiFreeOpCodeHandle (
496	VOID *OpCodeHandle
497	);
498
499	/**
500	Append raw opcodes to an OpCodeHandle.
501
502	If OpCodeHandle is NULL, then ASSERT().
503	If RawBuffer is NULL, then ASSERT();
504
505	@param[in] OpCodeHandle The handle to the buffer of opcodes.
506	@param[in] RawBuffer The buffer of opcodes to append.
507	@param[in] RawBufferSize The size, in bytes, of Buffer.
508
509	@retval NULL There is not enough space left in Buffer to add the opcode.
510	@retval Other A pointer to the appended opcodes.
511
512	**/
513	UINT8 *
514	EFIAPI
515	HiiCreateRawOpCodes (
516	IN VOID *OpCodeHandle,
517	IN UINT8 *RawBuffer,
518	IN UINTN RawBufferSize
519	);
520
521	/**
522	Create EFI_IFR_END_OP opcode.
523
524	If OpCodeHandle is NULL, then ASSERT().
525
526	@param[in] OpCodeHandle Handle to the buffer of opcodes.
527
528	@retval NULL There is not enough space left in Buffer to add the opcode.
529	@retval Other A pointer to the created opcode.
530
531	**/
532	UINT8 *
533	EFIAPI
534	HiiCreateEndOpCode (
535	IN VOID *OpCodeHandle
536	);
537
538	/**
539	Create EFI_IFR_ONE_OF_OPTION_OP opcode.
540
541	If OpCodeHandle is NULL, then ASSERT().
542	If Type is invalid, then ASSERT().
543	If Flags is invalid, then ASSERT().
544
545	@param[in] OpCodeHandle The handle to the buffer of opcodes.
546	@param[in] StringId StringId for the option.
547	@param[in] Flags The flags for the option.
548	@param[in] Type The type for the option.
549	@param[in] Value The value for the option.
550
551	@retval NULL There is not enough space left in Buffer to add the opcode.
552	@retval Other A pointer to the created opcode.
553
554	**/
555	UINT8 *
556	EFIAPI
557	HiiCreateOneOfOptionOpCode (
558	IN VOID *OpCodeHandle,
559	IN UINT16 StringId,
560	IN UINT8 Flags,
561	IN UINT8 Type,
562	IN UINT64 Value
563	);
564
565	/**
566	Create EFI_IFR_DEFAULT_OP opcode.
567
568	If OpCodeHandle is NULL, then ASSERT().
569	If Type is invalid, then ASSERT().
570
571	@param[in] OpCodeHandle The handle to the buffer of opcodes.
572	@param[in] DefaultId The DefaultId for the default.
573	@param[in] Type The type for the default.
574	@param[in] Value The value for the default.
575
576	@retval NULL There is not enough space left in Buffer to add the opcode.
577	@retval Other A pointer to the created opcode.
578
579	**/
580	UINT8 *
581	EFIAPI
582	HiiCreateDefaultOpCode (
583	IN VOID *OpCodeHandle,
584	IN UINT16 DefaultId,
585	IN UINT8 Type,
586	IN UINT64 Value
587	);
588
589	/**
590	Create EFI_IFR_GUID opcode.
591
592	If OpCodeHandle is NULL, then ASSERT().
593	If Guid is NULL, then ASSERT().
594	If OpCodeSize < sizeof (EFI_IFR_GUID), then ASSERT().
595
596	@param[in] OpCodeHandle The handle to the buffer of opcodes.
597	@param[in] Guid The pointer to EFI_GUID of this guided opcode.
598	@param[in] GuidOpCode The pointer to an EFI_IFR_GUID opcode. This is an
599	optional parameter that may be NULL. If this
600	parameter is NULL, then the GUID extension
601	region of the created opcode is filled with zeros.
602	If this parameter is not NULL, then the GUID
603	extension region of GuidData will be copied to
604	the GUID extension region of the created opcode.
605	@param[in] OpCodeSize The size, in bytes, of created opcode. This value
606	must be >= sizeof(EFI_IFR_GUID).
607
608	@retval NULL There is not enough space left in Buffer to add the opcode.
609	@retval Other A pointer to the created opcode.
610
611	**/
612	UINT8 *
613	EFIAPI
614	HiiCreateGuidOpCode (
615	IN VOID *OpCodeHandle,
616	IN CONST EFI_GUID *Guid,
617	IN CONST VOID *GuidOpCode, OPTIONAL
618	IN UINTN OpCodeSize
619	);
620
621	/**
622	Create EFI_IFR_ACTION_OP opcode.
623
624	If OpCodeHandle is NULL, then ASSERT().
625	If any reserved bits are set in QuestionFlags, then ASSERT().
626
627	@param[in] OpCodeHandle The handle to the buffer of opcodes.
628	@param[in] QuestionId The Question ID.
629	@param[in] Prompt The String ID for Prompt.
630	@param[in] Help The String ID for Help.
631	@param[in] QuestionFlags The flags in the Question Header.
632	@param[in] QuestionConfig The String ID for the configuration.
633
634	@retval NULL There is not enough space left in Buffer to add the opcode.
635	@retval Other A pointer to the created opcode.
636
637	**/
638	UINT8 *
639	EFIAPI
640	HiiCreateActionOpCode (
641	IN VOID *OpCodeHandle,
642	IN EFI_QUESTION_ID QuestionId,
643	IN EFI_STRING_ID Prompt,
644	IN EFI_STRING_ID Help,
645	IN UINT8 QuestionFlags,
646	IN EFI_STRING_ID QuestionConfig
647	);
648
649	/**
650	Create EFI_IFR_SUBTITLE_OP opcode.
651
652	If OpCodeHandle is NULL, then ASSERT().
653	If any reserved bits are set in Flags, then ASSERT().
654	If Scope > 1, then ASSERT().
655
656	@param[in] OpCodeHandle The handle to the buffer of opcodes.
657	@param[in] Prompt The string ID for Prompt.
658	@param[in] Help The string ID for Help.
659	@param[in] Flags The subtitle opcode flags.
660	@param[in] Scope 1 if this opcode is the beginning of a new scope.
661	0 if this opcode is within the current scope.
662
663	@retval NULL There is not enough space left in Buffer to add the opcode.
664	@retval Other A pointer to the created opcode.
665
666	**/
667	UINT8 *
668	EFIAPI
669	HiiCreateSubTitleOpCode (
670	IN VOID *OpCodeHandle,
671	IN EFI_STRING_ID Prompt,
672	IN EFI_STRING_ID Help,
673	IN UINT8 Flags,
674	IN UINT8 Scope
675	);
676
677	/**
678	Create EFI_IFR_REF_OP opcode.
679
680	If OpCodeHandle is NULL, then ASSERT().
681	If any reserved bits are set in QuestionFlags, then ASSERT().
682
683	@param[in] OpCodeHandle The handle to the buffer of opcodes.
684	@param[in] FormId The Destination Form ID.
685	@param[in] Prompt The string ID for Prompt.
686	@param[in] Help The string ID for Help.
687	@param[in] QuestionFlags The flags in Question Header
688	@param[in] QuestionId Question ID.
689
690	@retval NULL There is not enough space left in Buffer to add the opcode.
691	@retval Other A pointer to the created opcode.
692
693	**/
694	UINT8 *
695	EFIAPI
696	HiiCreateGotoOpCode (
697	IN VOID *OpCodeHandle,
698	IN EFI_FORM_ID FormId,
699	IN EFI_STRING_ID Prompt,
700	IN EFI_STRING_ID Help,
701	IN UINT8 QuestionFlags,
702	IN EFI_QUESTION_ID QuestionId
703	);
704
705	/**
706	Create EFI_IFR_REF_OP, EFI_IFR_REF2_OP, EFI_IFR_REF3_OP and EFI_IFR_REF4_OP opcode.
707
708	When RefDevicePath is not zero, EFI_IFR_REF4 opcode will be created.
709	When RefDevicePath is zero and RefFormSetId is not NULL, EFI_IFR_REF3 opcode will be created.
710	When RefDevicePath is zero, RefFormSetId is NULL and RefQuestionId is not zero, EFI_IFR_REF2 opcode will be created.
711	When RefDevicePath is zero, RefFormSetId is NULL and RefQuestionId is zero, EFI_IFR_REF opcode will be created.
712
713	If OpCodeHandle is NULL, then ASSERT().
714	If any reserved bits are set in QuestionFlags, then ASSERT().
715
716	@param[in] OpCodeHandle The handle to the buffer of opcodes.
717	@param[in] RefFormId The Destination Form ID.
718	@param[in] Prompt The string ID for Prompt.
719	@param[in] Help The string ID for Help.
720	@param[in] QuestionFlags The flags in Question Header
721	@param[in] QuestionId Question ID.
722	@param[in] RefQuestionId The question on the form to which this link is referring.
723	If its value is zero, then the link refers to the top of the form.
724	@param[in] RefFormSetId The form set to which this link is referring. If its value is NULL, and RefDevicePath is
725	zero, then the link is to the current form set.
726	@param[in] RefDevicePath The string identifier that specifies the string containing the text representation of
727	the device path to which the form set containing the form specified by FormId.
728	If its value is zero, then the link refers to the current page.
729
730	@retval NULL There is not enough space left in Buffer to add the opcode.
731	@retval Other A pointer to the created opcode.
732
733	**/
734	UINT8 *
735	EFIAPI
736	HiiCreateGotoExOpCode (
737	IN VOID *OpCodeHandle,
738	IN EFI_FORM_ID RefFormId,
739	IN EFI_STRING_ID Prompt,
740	IN EFI_STRING_ID Help,
741	IN UINT8 QuestionFlags,
742	IN EFI_QUESTION_ID QuestionId,
743	IN EFI_QUESTION_ID RefQuestionId,
744	IN EFI_GUID *RefFormSetId, OPTIONAL
745	IN EFI_STRING_ID RefDevicePath
746	);
747
748	/**
749	Create EFI_IFR_CHECKBOX_OP opcode.
750
751	If OpCodeHandle is NULL, then ASSERT().
752	If any reserved bits are set in QuestionFlags, then ASSERT().
753	If any reserved bits are set in CheckBoxFlags, then ASSERT().
754
755	@param[in] OpCodeHandle The handle to the buffer of opcodes.
756	@param[in] QuestionId The question ID.
757	@param[in] VarStoreId The storage ID.
758	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
759	for this name/value pair.
760	@param[in] Prompt The string ID for Prompt.
761	@param[in] Help The string ID for Help.
762	@param[in] QuestionFlags The flags in Question Header.
763	@param[in] CheckBoxFlags The flags for checkbox opcode.
764	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
765	is an optional parameter that may be NULL.
766
767	@retval NULL There is not enough space left in Buffer to add the opcode.
768	@retval Other A pointer to the created opcode.
769
770	**/
771	UINT8 *
772	EFIAPI
773	HiiCreateCheckBoxOpCode (
774	IN VOID *OpCodeHandle,
775	IN EFI_QUESTION_ID QuestionId,
776	IN EFI_VARSTORE_ID VarStoreId,
777	IN UINT16 VarOffset,
778	IN EFI_STRING_ID Prompt,
779	IN EFI_STRING_ID Help,
780	IN UINT8 QuestionFlags,
781	IN UINT8 CheckBoxFlags,
782	IN VOID *DefaultsOpCodeHandle OPTIONAL
783	);
784
785	/**
786	Create EFI_IFR_NUMERIC_OP opcode.
787
788	If OpCodeHandle is NULL, then ASSERT().
789	If any reserved bits are set in QuestionFlags, then ASSERT().
790	If any reserved bits are set in NumericFlags, then ASSERT().
791
792	@param[in] OpCodeHandle The handle to the buffer of opcodes.
793	@param[in] QuestionId The question ID.
794	@param[in] VarStoreId The storage ID.
795	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
796	for this name/value pair.
797	@param[in] Prompt The string ID for Prompt.
798	@param[in] Help The string ID for Help.
799	@param[in] QuestionFlags The flags in Question Header.
800	@param[in] NumericFlags The flags for a numeric opcode.
801	@param[in] Minimum The numeric minimum value.
802	@param[in] Maximum The numeric maximum value.
803	@param[in] Step The numeric step for edit.
804	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
805	is an optional parameter that may be NULL.
806
807	@retval NULL There is not enough space left in Buffer to add the opcode.
808	@retval Other A pointer to the created opcode.
809
810	**/
811	UINT8 *
812	EFIAPI
813	HiiCreateNumericOpCode (
814	IN VOID *OpCodeHandle,
815	IN EFI_QUESTION_ID QuestionId,
816	IN EFI_VARSTORE_ID VarStoreId,
817	IN UINT16 VarOffset,
818	IN EFI_STRING_ID Prompt,
819	IN EFI_STRING_ID Help,
820	IN UINT8 QuestionFlags,
821	IN UINT8 NumericFlags,
822	IN UINT64 Minimum,
823	IN UINT64 Maximum,
824	IN UINT64 Step,
825	IN VOID *DefaultsOpCodeHandle OPTIONAL
826	);
827
828	/**
829	Create EFI_IFR_STRING_OP opcode.
830
831	If OpCodeHandle is NULL, then ASSERT().
832	If any reserved bits are set in QuestionFlags, then ASSERT().
833	If any reserved bits are set in StringFlags, then ASSERT().
834
835	@param[in] OpCodeHandle The handle to the buffer of opcodes.
836	@param[in] QuestionId The question ID.
837	@param[in] VarStoreId The storage ID.
838	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
839	for this name/value pair.
840	@param[in] Prompt The string ID for Prompt.
841	@param[in] Help The string ID for Help.
842	@param[in] QuestionFlags The flags in Question Header.
843	@param[in] StringFlags The flags for a string opcode.
844	@param[in] MinSize The string minimum length.
845	@param[in] MaxSize The string maximum length.
846	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
847	is an optional parameter that may be NULL.
848
849	@retval NULL There is not enough space left in Buffer to add the opcode.
850	@retval Other A pointer to the created opcode.
851
852	**/
853	UINT8 *
854	EFIAPI
855	HiiCreateStringOpCode (
856	IN VOID *OpCodeHandle,
857	IN EFI_QUESTION_ID QuestionId,
858	IN EFI_VARSTORE_ID VarStoreId,
859	IN UINT16 VarOffset,
860	IN EFI_STRING_ID Prompt,
861	IN EFI_STRING_ID Help,
862	IN UINT8 QuestionFlags,
863	IN UINT8 StringFlags,
864	IN UINT8 MinSize,
865	IN UINT8 MaxSize,
866	IN VOID *DefaultsOpCodeHandle OPTIONAL
867	);
868
869	/**
870	Create EFI_IFR_ONE_OF_OP opcode.
871
872	If OpCodeHandle is NULL, then ASSERT().
873	If any reserved bits are set in QuestionFlags, then ASSERT().
874	If any reserved bits are set in OneOfFlags, then ASSERT().
875
876	@param[in] OpCodeHandle The handle to the buffer of opcodes.
877	@param[in] QuestionId The question ID.
878	@param[in] VarStoreId The storage ID.
879	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
880	for this name/value pair.
881	@param[in] Prompt The string ID for Prompt.
882	@param[in] Help The string ID for Help.
883	@param[in] QuestionFlags The flags in Question Header.
884	@param[in] OneOfFlags The flags for a oneof opcode.
885	@param[in] OptionsOpCodeHandle The handle for a buffer of ONE_OF_OPTION opcodes.
886	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
887	is an optional parameter that may be NULL.
888
889	@retval NULL There is not enough space left in Buffer to add the opcode.
890	@retval Other A pointer to the created opcode.
891
892	**/
893	UINT8 *
894	EFIAPI
895	HiiCreateOneOfOpCode (
896	IN VOID *OpCodeHandle,
897	IN EFI_QUESTION_ID QuestionId,
898	IN EFI_VARSTORE_ID VarStoreId,
899	IN UINT16 VarOffset,
900	IN EFI_STRING_ID Prompt,
901	IN EFI_STRING_ID Help,
902	IN UINT8 QuestionFlags,
903	IN UINT8 OneOfFlags,
904	IN VOID *OptionsOpCodeHandle,
905	IN VOID *DefaultsOpCodeHandle OPTIONAL
906	);
907
908	/**
909	Create EFI_IFR_ORDERED_LIST_OP opcode.
910
911	If OpCodeHandle is NULL, then ASSERT().
912	If any reserved bits are set in QuestionFlags, then ASSERT().
913	If any reserved bits are set in OrderedListFlags, then ASSERT().
914
915	@param[in] OpCodeHandle The handle to the buffer of opcodes.
916	@param[in] QuestionId The question ID.
917	@param[in] VarStoreId The storage ID.
918	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
919	for this name/value pair.
920	@param[in] Prompt The string ID for Prompt.
921	@param[in] Help The string ID for Help.
922	@param[in] QuestionFlags The flags in Question Header.
923	@param[in] OrderedListFlags The flags for an ordered list opcode.
924	@param[in] DataType The type for option value.
925	@param[in] MaxContainers Maximum count for options in this ordered list
926	@param[in] OptionsOpCodeHandle The handle for a buffer of ONE_OF_OPTION opcodes.
927	@param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This
928	is an optional parameter that may be NULL.
929
930	@retval NULL There is not enough space left in Buffer to add the opcode.
931	@retval Other A pointer to the created opcode.
932
933	**/
934	UINT8 *
935	EFIAPI
936	HiiCreateOrderedListOpCode (
937	IN VOID *OpCodeHandle,
938	IN EFI_QUESTION_ID QuestionId,
939	IN EFI_VARSTORE_ID VarStoreId,
940	IN UINT16 VarOffset,
941	IN EFI_STRING_ID Prompt,
942	IN EFI_STRING_ID Help,
943	IN UINT8 QuestionFlags,
944	IN UINT8 OrderedListFlags,
945	IN UINT8 DataType,
946	IN UINT8 MaxContainers,
947	IN VOID *OptionsOpCodeHandle,
948	IN VOID *DefaultsOpCodeHandle OPTIONAL
949	);
950
951	/**
952	Create EFI_IFR_TEXT_OP opcode.
953
954	If OpCodeHandle is NULL, then ASSERT().
955
956	@param[in] OpCodeHandle Handle to the buffer of opcodes.
957	@param[in] Prompt String ID for Prompt.
958	@param[in] Help String ID for Help.
959	@param[in] TextTwo String ID for TextTwo.
960
961	@retval NULL There is not enough space left in Buffer to add the opcode.
962	@retval Other A pointer to the created opcode.
963
964	**/
965	UINT8 *
966	EFIAPI
967	HiiCreateTextOpCode (
968	IN VOID *OpCodeHandle,
969	IN EFI_STRING_ID Prompt,
970	IN EFI_STRING_ID Help,
971	IN EFI_STRING_ID TextTwo
972	);
973
974	/**
975	Create EFI_IFR_DATE_OP opcode.
976
977	If OpCodeHandle is NULL, then ASSERT().
978	If any reserved bits are set in QuestionFlags, then ASSERT().
979	If any reserved bits are set in DateFlags, then ASSERT().
980
981	@param[in] OpCodeHandle Handle to the buffer of opcodes.
982	@param[in] QuestionId Question ID
983	@param[in] VarStoreId Storage ID, optional. If DateFlags is not
984	QF_DATE_STORAGE_NORMAL, this parameter is ignored.
985	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
986	for this name/value pair, optional. If DateFlags is not
987	QF_DATE_STORAGE_NORMAL, this parameter is ignored.
988	@param[in] Prompt String ID for Prompt
989	@param[in] Help String ID for Help
990	@param[in] QuestionFlags Flags in Question Header
991	@param[in] DateFlags Flags for date opcode
992	@param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This
993	is an optional parameter that may be NULL.
994
995	@retval NULL There is not enough space left in Buffer to add the opcode.
996	@retval Other A pointer to the created opcode.
997
998	**/
999	UINT8 *
1000	EFIAPI
1001	HiiCreateDateOpCode (
1002	IN VOID *OpCodeHandle,
1003	IN EFI_QUESTION_ID QuestionId,
1004	IN EFI_VARSTORE_ID VarStoreId, OPTIONAL
1005	IN UINT16 VarOffset, OPTIONAL
1006	IN EFI_STRING_ID Prompt,
1007	IN EFI_STRING_ID Help,
1008	IN UINT8 QuestionFlags,
1009	IN UINT8 DateFlags,
1010	IN VOID *DefaultsOpCodeHandle OPTIONAL
1011	);
1012
1013	/**
1014	Create EFI_IFR_TIME_OP opcode.
1015
1016	If OpCodeHandle is NULL, then ASSERT().
1017	If any reserved bits are set in QuestionFlags, then ASSERT().
1018	If any reserved bits are set in TimeFlags, then ASSERT().
1019
1020	@param[in] OpCodeHandle Handle to the buffer of opcodes.
1021	@param[in] QuestionId Question ID
1022	@param[in] VarStoreId Storage ID, optional. If TimeFlags is not
1023	QF_TIME_STORAGE_NORMAL, this parameter is ignored.
1024	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
1025	for this name/value pair, optional. If TimeFlags is not
1026	QF_TIME_STORAGE_NORMAL, this parameter is ignored.
1027	@param[in] Prompt String ID for Prompt
1028	@param[in] Help String ID for Help
1029	@param[in] QuestionFlags Flags in Question Header
1030	@param[in] TimeFlags Flags for time opcode
1031	@param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This
1032	is an optional parameter that may be NULL.
1033
1034	@retval NULL There is not enough space left in Buffer to add the opcode.
1035	@retval Other A pointer to the created opcode.
1036
1037	**/
1038	UINT8 *
1039	EFIAPI
1040	HiiCreateTimeOpCode (
1041	IN VOID *OpCodeHandle,
1042	IN EFI_QUESTION_ID QuestionId,
1043	IN EFI_VARSTORE_ID VarStoreId, OPTIONAL
1044	IN UINT16 VarOffset, OPTIONAL
1045	IN EFI_STRING_ID Prompt,
1046	IN EFI_STRING_ID Help,
1047	IN UINT8 QuestionFlags,
1048	IN UINT8 TimeFlags,
1049	IN VOID *DefaultsOpCodeHandle OPTIONAL
1050	);
1051
1052	/**
1053	This function updates a form that has previously been registered with the HII
1054	Database. This function will perform at most one update operation.
1055
1056	The form to update is specified by Handle, FormSetGuid, and FormId. Binary
1057	comparisons of IFR opcodes are performed from the beginning of the form being
1058	updated until an IFR opcode is found that exactly matches the first IFR opcode
1059	specified by StartOpCodeHandle. The following rules are used to determine if
1060	an insert, replace, or delete operation is performed:
1061
1062	1) If no matches are found, then NULL is returned.
1063	2) If a match is found, and EndOpCodeHandle is NULL, then all of the IFR opcodes
1064	from StartOpCodeHandle except the first opcode are inserted immediately after
1065	the matching IFR opcode in the form to be updated.
1066	3) If a match is found, and EndOpCodeHandle is not NULL, then a search is made
1067	from the matching IFR opcode until an IFR opcode exactly matches the first
1068	IFR opcode specified by EndOpCodeHandle. If no match is found for the first
1069	IFR opcode specified by EndOpCodeHandle, then NULL is returned. If a match
1070	is found, then all of the IFR opcodes between the start match and the end
1071	match are deleted from the form being updated and all of the IFR opcodes
1072	from StartOpCodeHandle except the first opcode are inserted immediately after
1073	the matching start IFR opcode. If StartOpCcodeHandle only contains one
1074	IFR instruction, then the result of this operation will delete all of the IFR
1075	opcodes between the start end matches.
1076
1077	If HiiHandle is NULL, then ASSERT().
1078	If StartOpCodeHandle is NULL, then ASSERT().
1079
1080	@param[in] HiiHandle The HII Handle of the form to update.
1081	@param[in] FormSetGuid The Formset GUID of the form to update. This
1082	is an optional parameter that may be NULL.
1083	If it is NULL, all FormSet will be updated.
1084	@param[in] FormId The ID of the form to update.
1085	@param[in] StartOpCodeHandle An OpCode Handle that contains the set of IFR
1086	opcodes to be inserted or replaced in the form.
1087	The first IFR instruction in StartOpCodeHandle
1088	is used to find matching IFR opcode in the
1089	form.
1090	@param[in] EndOpCodeHandle An OpCcode Handle that contains the IFR opcode
1091	that marks the end of a replace operation in
1092	the form. This is an optional parameter that
1093	may be NULL. If it is NULL, then the IFR
1094	opcodes specified by StartOpCodeHandle are
1095	inserted into the form.
1096
1097	@retval EFI_OUT_OF_RESOURCES Not enough memory resources are allocated.
1098	@retval EFI_NOT_FOUND The following cases will return EFI_NOT_FOUND:
1099	1) The form specified by HiiHandle, FormSetGuid,
1100	and FormId could not be found in the HII Database.
1101	2) No IFR opcodes in the target form match the first
1102	IFR opcode in StartOpCodeHandle.
1103	3) EndOpCOde is not NULL, and no IFR opcodes in the
1104	target form following a matching start opcode match
1105	the first IFR opcode in EndOpCodeHandle.
1106	@retval EFI_SUCCESS The matched form is updated by StartOpcode.
1107
1108	**/
1109	EFI_STATUS
1110	EFIAPI
1111	HiiUpdateForm (
1112	IN EFI_HII_HANDLE HiiHandle,
1113	IN EFI_GUID *FormSetGuid, OPTIONAL
1114	IN EFI_FORM_ID FormId,
1115	IN VOID *StartOpCodeHandle,
1116	IN VOID *EndOpCodeHandle OPTIONAL
1117	);
1118
1119	#endif

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

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/MdeModulePkg/Include/Library/HiiLib.h@ 77662

Download in other formats: