HiiLib.h@ 61103

Last change on this file since 61103 was 58466, checked in by vboxsync, 9 years ago
EFI/Firmware: Merged in the svn:eol-style, svn:mime-type and trailing whitespace cleanup that was done after the initial UDK2014.SP1 import: svn merge ^{/vendor/edk2/UDK2014.SP1}/vendor/edk2/current .
Property svn:eol-style set to `native`
File size: 42.2 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	Retrieves a pointer to a Null-terminated ASCII string containing the list
229	of languages that an HII handle in the HII Database supports. The returned
230	string is allocated using AllocatePool(). The caller is responsible for freeing
231	the returned string using FreePool(). The format of the returned string follows
232	the language format assumed in the HII Database.
233
234	If HiiHandle is NULL, then ASSERT().
235
236	@param[in] HiiHandle A handle that was previously registered in the HII Database.
237
238	@retval NULL HiiHandle is not registered in the HII database
239	@retval NULL There are not enough resources available to retrieve the suported
240	languages.
241	@retval NULL The list of suported languages could not be retrieved.
242	@retval Other A pointer to the Null-terminated ASCII string of supported languages.
243
244	**/
245	CHAR8 *
246	EFIAPI
247	HiiGetSupportedLanguages (
248	IN EFI_HII_HANDLE HiiHandle
249	)
250	;
251
252	/**
253	Allocates and returns a Null-terminated Unicode <ConfigHdr> string using routing
254	information that includes a GUID, an optional Unicode string name, and a device
255	path. The string returned is allocated with AllocatePool(). The caller is
256	responsible for freeing the allocated string with FreePool().
257
258	The format of a <ConfigHdr> is as follows:
259
260	GUID=<HexCh>32&NAME=<Char>NameLength&PATH=<HexChar>DevicePathSize<Null>
261
262	@param[in] Guid The pointer to an EFI_GUID that is the routing information
263	GUID. Each of the 16 bytes in Guid is converted to
264	a 2 Unicode character hexidecimal string. This is
265	an optional parameter that may be NULL.
266	@param[in] Name The pointer to a Null-terminated Unicode string that is
267	the routing information NAME. This is an optional
268	parameter that may be NULL. Each 16-bit Unicode
269	character in Name is converted to a 4 character Unicode
270	hexidecimal string.
271	@param[in] DriverHandle The driver handle that supports a Device Path Protocol
272	that is the routing information PATH. Each byte of
273	the Device Path associated with DriverHandle is converted
274	to a two (Unicode) character hexidecimal string.
275
276	@retval NULL DriverHandle does not support the Device Path Protocol.
277	@retval NULL DriverHandle does not support the Device Path Protocol.
278	@retval Other A pointer to the Null-terminate Unicode <ConfigHdr> string
279
280	**/
281	EFI_STRING
282	EFIAPI
283	HiiConstructConfigHdr (
284	IN CONST EFI_GUID *Guid, OPTIONAL
285	IN CONST CHAR16 *Name, OPTIONAL
286	IN EFI_HANDLE DriverHandle
287	);
288
289	/**
290	Reset the default value specified by DefaultId to the driver
291	configuration specified by the Request string.
292
293	NULL request string support depends on the ExportConfig interface of
294	HiiConfigRouting protocol in UEFI specification.
295
296	@param Request A null-terminated Unicode string in
297	<MultiConfigRequest> format. It can be NULL.
298	If it is NULL, all configurations for the
299	entirety of the current HII database will be reset.
300	@param DefaultId Specifies the type of defaults to retrieve.
301
302	@retval TURE The default value was set successfully.
303	@retval FALSE The default value was not found.
304	**/
305	BOOLEAN
306	EFIAPI
307	HiiSetToDefaults (
308	IN CONST EFI_STRING Request, OPTIONAL
309	IN UINT16 DefaultId
310	);
311
312	/**
313	Validate the current configuration by parsing the IFR opcode in HII form.
314
315	NULL request string support depends on the ExportConfig interface of
316	HiiConfigRouting protocol in the UEFI specification.
317
318	@param Request A null-terminated Unicode string in
319	<MultiConfigRequest> format. It can be NULL.
320	If it is NULL, all current configurations for the
321	entirety of the current HII database will be validated.
322
323	@retval TRUE The current configuration is valid.
324	@retval FALSE The current configuration is invalid.
325	**/
326	BOOLEAN
327	EFIAPI
328	HiiValidateSettings (
329	IN CONST EFI_STRING Request OPTIONAL
330	);
331
332	/**
333	Determines if the routing data specified by GUID and NAME match a <ConfigHdr>.
334
335	If ConfigHdr is NULL, then ASSERT().
336
337	@param[in] ConfigHdr Either <ConfigRequest> or <ConfigResp>.
338	@param[in] Guid The GUID of the storage.
339	@param[in] Name The NAME of the storage.
340
341	@retval TRUE Routing information matches <ConfigHdr>.
342	@retval FALSE Routing information does not match <ConfigHdr>.
343
344	**/
345	BOOLEAN
346	EFIAPI
347	HiiIsConfigHdrMatch (
348	IN CONST EFI_STRING ConfigHdr,
349	IN CONST EFI_GUID *Guid, OPTIONAL
350	IN CONST CHAR16 *Name OPTIONAL
351	);
352
353	/**
354	Retrieves uncommitted data from the Form Browser and converts it to a binary
355	buffer.
356
357	@param[in] VariableGuid The pointer to an EFI_GUID structure. This is an optional
358	parameter that may be NULL.
359	@param[in] VariableName The pointer to a Null-terminated Unicode string. This
360	is an optional parameter that may be NULL.
361	@param[in] BufferSize The length in bytes of buffer to hold retrieved data.
362	@param[out] Buffer The buffer of data to be updated.
363
364	@retval FALSE The uncommitted data could not be retrieved.
365	@retval TRUE The uncommitted data was retrieved.
366
367	**/
368	BOOLEAN
369	EFIAPI
370	HiiGetBrowserData (
371	IN CONST EFI_GUID *VariableGuid, OPTIONAL
372	IN CONST CHAR16 *VariableName, OPTIONAL
373	IN UINTN BufferSize,
374	OUT UINT8 *Buffer
375	);
376
377	/**
378	Updates uncommitted data in the Form Browser.
379
380	If Buffer is NULL, then ASSERT().
381
382	@param[in] VariableGuid The pointer to an EFI_GUID structure. This is an optional
383	parameter that may be NULL.
384	@param[in] VariableName The pointer to a Null-terminated Unicode string. This
385	is an optional parameter that may be NULL.
386	@param[in] BufferSize The length, in bytes, of Buffer.
387	@param[in] Buffer The buffer of data to commit.
388	@param[in] RequestElement An optional field to specify which part of the
389	buffer data will be send back to Browser. If NULL,
390	the whole buffer of data will be committed to
391	Browser.
392	<RequestElement> ::= &OFFSET=<Number>&WIDTH=<Number>*
393
394	@retval FALSE The uncommitted data could not be updated.
395	@retval TRUE The uncommitted data was updated.
396
397	**/
398	BOOLEAN
399	EFIAPI
400	HiiSetBrowserData (
401	IN CONST EFI_GUID *VariableGuid, OPTIONAL
402	IN CONST CHAR16 *VariableName, OPTIONAL
403	IN UINTN BufferSize,
404	IN CONST UINT8 *Buffer,
405	IN CONST CHAR16 *RequestElement OPTIONAL
406	);
407
408	/////////////////////////////////////////
409	/////////////////////////////////////////
410	/// IFR Functions
411	/////////////////////////////////////////
412	/////////////////////////////////////////
413
414	/**
415	Returns a UINT64 value that contains bitfields for Hour, Minute, and Second.
416	The lower 8-bits of Hour are placed in bits 0..7. The lower 8-bits of Minute
417	are placed in bits 8..15, and the lower 8-bits of Second are placed in bits
418	16..23. This format was selected because it can be easily translated to
419	an EFI_HII_TIME structure in an EFI_IFR_TYPE_VALUE union.
420
421	@param Hour The hour value to be encoded.
422	@param Minute The minute value to be encoded.
423	@param Second The second value to be encoded.
424
425	@return A 64-bit containing Hour, Minute, and Second.
426	**/
427	#define EFI_HII_TIME_UINT64(Hour, Minute, Second) \
428	(UINT64)((Hour & 0xff) \| ((Minute & 0xff) << 8) \| ((Second & 0xff) << 16))
429
430	/**
431	Returns a UINT64 value that contains bit fields for Year, Month, and Day.
432	The lower 16-bits of Year are placed in bits 0..15. The lower 8-bits of Month
433	are placed in bits 16..23, and the lower 8-bits of Day are placed in bits
434	24..31. This format was selected because it can be easily translated to
435	an EFI_HII_DATE structure in an EFI_IFR_TYPE_VALUE union.
436
437	@param Year The year value to be encoded.
438	@param Month The month value to be encoded.
439	@param Day The day value to be encoded.
440
441	@return A 64-bit containing Year, Month, and Day.
442	**/
443	#define EFI_HII_DATE_UINT64(Year, Month, Day) \
444	(UINT64)((Year & 0xffff) \| ((Month & 0xff) << 16) \| ((Day & 0xff) << 24))
445
446	/**
447	Allocates and returns a new OpCode Handle. OpCode Handles must be freed with
448	HiiFreeOpCodeHandle().
449
450	@retval NULL There are not enough resources to allocate a new OpCode Handle.
451	@retval Other A new OpCode handle.
452
453	**/
454	VOID *
455	EFIAPI
456	HiiAllocateOpCodeHandle (
457	VOID
458	);
459
460	/**
461	Frees an OpCode Handle that was previously allocated with HiiAllocateOpCodeHandle().
462	When an OpCode Handle is freed, all of the opcodes associated with the OpCode
463	Handle are also freed.
464
465	If OpCodeHandle is NULL, then ASSERT().
466
467	@param[in] OpCodeHandle The handle to the buffer of opcodes.
468
469	**/
470	VOID
471	EFIAPI
472	HiiFreeOpCodeHandle (
473	VOID *OpCodeHandle
474	);
475
476	/**
477	Append raw opcodes to an OpCodeHandle.
478
479	If OpCodeHandle is NULL, then ASSERT().
480	If RawBuffer is NULL, then ASSERT();
481
482	@param[in] OpCodeHandle The handle to the buffer of opcodes.
483	@param[in] RawBuffer The buffer of opcodes to append.
484	@param[in] RawBufferSize The size, in bytes, of Buffer.
485
486	@retval NULL There is not enough space left in Buffer to add the opcode.
487	@retval Other A pointer to the appended opcodes.
488
489	**/
490	UINT8 *
491	EFIAPI
492	HiiCreateRawOpCodes (
493	IN VOID *OpCodeHandle,
494	IN UINT8 *RawBuffer,
495	IN UINTN RawBufferSize
496	);
497
498	/**
499	Create EFI_IFR_END_OP opcode.
500
501	If OpCodeHandle is NULL, then ASSERT().
502
503	@param[in] OpCodeHandle Handle to the buffer of opcodes.
504
505	@retval NULL There is not enough space left in Buffer to add the opcode.
506	@retval Other A pointer to the created opcode.
507
508	**/
509	UINT8 *
510	EFIAPI
511	HiiCreateEndOpCode (
512	IN VOID *OpCodeHandle
513	);
514
515	/**
516	Create EFI_IFR_ONE_OF_OPTION_OP opcode.
517
518	If OpCodeHandle is NULL, then ASSERT().
519	If Type is invalid, then ASSERT().
520	If Flags is invalid, then ASSERT().
521
522	@param[in] OpCodeHandle The handle to the buffer of opcodes.
523	@param[in] StringId StringId for the option.
524	@param[in] Flags The flags for the option.
525	@param[in] Type The type for the option.
526	@param[in] Value The value for the option.
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	HiiCreateOneOfOptionOpCode (
535	IN VOID *OpCodeHandle,
536	IN UINT16 StringId,
537	IN UINT8 Flags,
538	IN UINT8 Type,
539	IN UINT64 Value
540	);
541
542	/**
543	Create EFI_IFR_DEFAULT_OP opcode.
544
545	If OpCodeHandle is NULL, then ASSERT().
546	If Type is invalid, then ASSERT().
547
548	@param[in] OpCodeHandle The handle to the buffer of opcodes.
549	@param[in] DefaultId The DefaultId for the default.
550	@param[in] Type The type for the default.
551	@param[in] Value The value for the default.
552
553	@retval NULL There is not enough space left in Buffer to add the opcode.
554	@retval Other A pointer to the created opcode.
555
556	**/
557	UINT8 *
558	EFIAPI
559	HiiCreateDefaultOpCode (
560	IN VOID *OpCodeHandle,
561	IN UINT16 DefaultId,
562	IN UINT8 Type,
563	IN UINT64 Value
564	);
565
566	/**
567	Create EFI_IFR_GUID opcode.
568
569	If OpCodeHandle is NULL, then ASSERT().
570	If Guid is NULL, then ASSERT().
571	If OpCodeSize < sizeof (EFI_IFR_GUID), then ASSERT().
572
573	@param[in] OpCodeHandle The handle to the buffer of opcodes.
574	@param[in] Guid The pointer to EFI_GUID of this guided opcode.
575	@param[in] GuidOpCode The pointer to an EFI_IFR_GUID opcode. This is an
576	optional parameter that may be NULL. If this
577	parameter is NULL, then the GUID extension
578	region of the created opcode is filled with zeros.
579	If this parameter is not NULL, then the GUID
580	extension region of GuidData will be copied to
581	the GUID extension region of the created opcode.
582	@param[in] OpCodeSize The size, in bytes, of created opcode. This value
583	must be >= sizeof(EFI_IFR_GUID).
584
585	@retval NULL There is not enough space left in Buffer to add the opcode.
586	@retval Other A pointer to the created opcode.
587
588	**/
589	UINT8 *
590	EFIAPI
591	HiiCreateGuidOpCode (
592	IN VOID *OpCodeHandle,
593	IN CONST EFI_GUID *Guid,
594	IN CONST VOID *GuidOpCode, OPTIONAL
595	IN UINTN OpCodeSize
596	);
597
598	/**
599	Create EFI_IFR_ACTION_OP opcode.
600
601	If OpCodeHandle is NULL, then ASSERT().
602	If any reserved bits are set in QuestionFlags, then ASSERT().
603
604	@param[in] OpCodeHandle The handle to the buffer of opcodes.
605	@param[in] QuestionId The Question ID.
606	@param[in] Prompt The String ID for Prompt.
607	@param[in] Help The String ID for Help.
608	@param[in] QuestionFlags The flags in the Question Header.
609	@param[in] QuestionConfig The String ID for the configuration.
610
611	@retval NULL There is not enough space left in Buffer to add the opcode.
612	@retval Other A pointer to the created opcode.
613
614	**/
615	UINT8 *
616	EFIAPI
617	HiiCreateActionOpCode (
618	IN VOID *OpCodeHandle,
619	IN EFI_QUESTION_ID QuestionId,
620	IN EFI_STRING_ID Prompt,
621	IN EFI_STRING_ID Help,
622	IN UINT8 QuestionFlags,
623	IN EFI_STRING_ID QuestionConfig
624	);
625
626	/**
627	Create EFI_IFR_SUBTITLE_OP opcode.
628
629	If OpCodeHandle is NULL, then ASSERT().
630	If any reserved bits are set in Flags, then ASSERT().
631	If Scope > 1, then ASSERT().
632
633	@param[in] OpCodeHandle The handle to the buffer of opcodes.
634	@param[in] Prompt The string ID for Prompt.
635	@param[in] Help The string ID for Help.
636	@param[in] Flags The subtitle opcode flags.
637	@param[in] Scope 1 if this opcode is the beginning of a new scope.
638	0 if this opcode is within the current scope.
639
640	@retval NULL There is not enough space left in Buffer to add the opcode.
641	@retval Other A pointer to the created opcode.
642
643	**/
644	UINT8 *
645	EFIAPI
646	HiiCreateSubTitleOpCode (
647	IN VOID *OpCodeHandle,
648	IN EFI_STRING_ID Prompt,
649	IN EFI_STRING_ID Help,
650	IN UINT8 Flags,
651	IN UINT8 Scope
652	);
653
654	/**
655	Create EFI_IFR_REF_OP opcode.
656
657	If OpCodeHandle is NULL, then ASSERT().
658	If any reserved bits are set in QuestionFlags, then ASSERT().
659
660	@param[in] OpCodeHandle The handle to the buffer of opcodes.
661	@param[in] FormId The Destination Form ID.
662	@param[in] Prompt The string ID for Prompt.
663	@param[in] Help The string ID for Help.
664	@param[in] QuestionFlags The flags in Question Header
665	@param[in] QuestionId Question ID.
666
667	@retval NULL There is not enough space left in Buffer to add the opcode.
668	@retval Other A pointer to the created opcode.
669
670	**/
671	UINT8 *
672	EFIAPI
673	HiiCreateGotoOpCode (
674	IN VOID *OpCodeHandle,
675	IN EFI_FORM_ID FormId,
676	IN EFI_STRING_ID Prompt,
677	IN EFI_STRING_ID Help,
678	IN UINT8 QuestionFlags,
679	IN EFI_QUESTION_ID QuestionId
680	);
681
682	/**
683	Create EFI_IFR_REF_OP, EFI_IFR_REF2_OP, EFI_IFR_REF3_OP and EFI_IFR_REF4_OP opcode.
684
685	When RefDevicePath is not zero, EFI_IFR_REF4 opcode will be created.
686	When RefDevicePath is zero and RefFormSetId is not NULL, EFI_IFR_REF3 opcode will be created.
687	When RefDevicePath is zero, RefFormSetId is NULL and RefQuestionId is not zero, EFI_IFR_REF2 opcode will be created.
688	When RefDevicePath is zero, RefFormSetId is NULL and RefQuestionId is zero, EFI_IFR_REF opcode will be created.
689
690	If OpCodeHandle is NULL, then ASSERT().
691	If any reserved bits are set in QuestionFlags, then ASSERT().
692
693	@param[in] OpCodeHandle The handle to the buffer of opcodes.
694	@param[in] RefFormId The Destination Form ID.
695	@param[in] Prompt The string ID for Prompt.
696	@param[in] Help The string ID for Help.
697	@param[in] QuestionFlags The flags in Question Header
698	@param[in] QuestionId Question ID.
699	@param[in] RefQuestionId The question on the form to which this link is referring.
700	If its value is zero, then the link refers to the top of the form.
701	@param[in] RefFormSetId The form set to which this link is referring. If its value is NULL, and RefDevicePath is
702	zero, then the link is to the current form set.
703	@param[in] RefDevicePath The string identifier that specifies the string containing the text representation of
704	the device path to which the form set containing the form specified by FormId.
705	If its value is zero, then the link refers to the current page.
706
707	@retval NULL There is not enough space left in Buffer to add the opcode.
708	@retval Other A pointer to the created opcode.
709
710	**/
711	UINT8 *
712	EFIAPI
713	HiiCreateGotoExOpCode (
714	IN VOID *OpCodeHandle,
715	IN EFI_FORM_ID RefFormId,
716	IN EFI_STRING_ID Prompt,
717	IN EFI_STRING_ID Help,
718	IN UINT8 QuestionFlags,
719	IN EFI_QUESTION_ID QuestionId,
720	IN EFI_QUESTION_ID RefQuestionId,
721	IN EFI_GUID *RefFormSetId, OPTIONAL
722	IN EFI_STRING_ID RefDevicePath
723	);
724
725	/**
726	Create EFI_IFR_CHECKBOX_OP opcode.
727
728	If OpCodeHandle is NULL, then ASSERT().
729	If any reserved bits are set in QuestionFlags, then ASSERT().
730	If any reserved bits are set in CheckBoxFlags, then ASSERT().
731
732	@param[in] OpCodeHandle The handle to the buffer of opcodes.
733	@param[in] QuestionId The question ID.
734	@param[in] VarStoreId The storage ID.
735	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
736	for this name/value pair.
737	@param[in] Prompt The string ID for Prompt.
738	@param[in] Help The string ID for Help.
739	@param[in] QuestionFlags The flags in Question Header.
740	@param[in] CheckBoxFlags The flags for checkbox opcode.
741	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
742	is an optional parameter that may be NULL.
743
744	@retval NULL There is not enough space left in Buffer to add the opcode.
745	@retval Other A pointer to the created opcode.
746
747	**/
748	UINT8 *
749	EFIAPI
750	HiiCreateCheckBoxOpCode (
751	IN VOID *OpCodeHandle,
752	IN EFI_QUESTION_ID QuestionId,
753	IN EFI_VARSTORE_ID VarStoreId,
754	IN UINT16 VarOffset,
755	IN EFI_STRING_ID Prompt,
756	IN EFI_STRING_ID Help,
757	IN UINT8 QuestionFlags,
758	IN UINT8 CheckBoxFlags,
759	IN VOID *DefaultsOpCodeHandle OPTIONAL
760	);
761
762	/**
763	Create EFI_IFR_NUMERIC_OP opcode.
764
765	If OpCodeHandle is NULL, then ASSERT().
766	If any reserved bits are set in QuestionFlags, then ASSERT().
767	If any reserved bits are set in NumericFlags, then ASSERT().
768
769	@param[in] OpCodeHandle The handle to the buffer of opcodes.
770	@param[in] QuestionId The question ID.
771	@param[in] VarStoreId The storage ID.
772	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
773	for this name/value pair.
774	@param[in] Prompt The string ID for Prompt.
775	@param[in] Help The string ID for Help.
776	@param[in] QuestionFlags The flags in Question Header.
777	@param[in] NumericFlags The flags for a numeric opcode.
778	@param[in] Minimum The numeric minimum value.
779	@param[in] Maximum The numeric maximum value.
780	@param[in] Step The numeric step for edit.
781	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
782	is an optional parameter that may be NULL.
783
784	@retval NULL There is not enough space left in Buffer to add the opcode.
785	@retval Other A pointer to the created opcode.
786
787	**/
788	UINT8 *
789	EFIAPI
790	HiiCreateNumericOpCode (
791	IN VOID *OpCodeHandle,
792	IN EFI_QUESTION_ID QuestionId,
793	IN EFI_VARSTORE_ID VarStoreId,
794	IN UINT16 VarOffset,
795	IN EFI_STRING_ID Prompt,
796	IN EFI_STRING_ID Help,
797	IN UINT8 QuestionFlags,
798	IN UINT8 NumericFlags,
799	IN UINT64 Minimum,
800	IN UINT64 Maximum,
801	IN UINT64 Step,
802	IN VOID *DefaultsOpCodeHandle OPTIONAL
803	);
804
805	/**
806	Create EFI_IFR_STRING_OP opcode.
807
808	If OpCodeHandle is NULL, then ASSERT().
809	If any reserved bits are set in QuestionFlags, then ASSERT().
810	If any reserved bits are set in StringFlags, then ASSERT().
811
812	@param[in] OpCodeHandle The handle to the buffer of opcodes.
813	@param[in] QuestionId The question ID.
814	@param[in] VarStoreId The storage ID.
815	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
816	for this name/value pair.
817	@param[in] Prompt The string ID for Prompt.
818	@param[in] Help The string ID for Help.
819	@param[in] QuestionFlags The flags in Question Header.
820	@param[in] StringFlags The flags for a string opcode.
821	@param[in] MinSize The string minimum length.
822	@param[in] MaxSize The string maximum length.
823	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
824	is an optional parameter that may be NULL.
825
826	@retval NULL There is not enough space left in Buffer to add the opcode.
827	@retval Other A pointer to the created opcode.
828
829	**/
830	UINT8 *
831	EFIAPI
832	HiiCreateStringOpCode (
833	IN VOID *OpCodeHandle,
834	IN EFI_QUESTION_ID QuestionId,
835	IN EFI_VARSTORE_ID VarStoreId,
836	IN UINT16 VarOffset,
837	IN EFI_STRING_ID Prompt,
838	IN EFI_STRING_ID Help,
839	IN UINT8 QuestionFlags,
840	IN UINT8 StringFlags,
841	IN UINT8 MinSize,
842	IN UINT8 MaxSize,
843	IN VOID *DefaultsOpCodeHandle OPTIONAL
844	);
845
846	/**
847	Create EFI_IFR_ONE_OF_OP opcode.
848
849	If OpCodeHandle is NULL, then ASSERT().
850	If any reserved bits are set in QuestionFlags, then ASSERT().
851	If any reserved bits are set in OneOfFlags, then ASSERT().
852
853	@param[in] OpCodeHandle The handle to the buffer of opcodes.
854	@param[in] QuestionId The question ID.
855	@param[in] VarStoreId The storage ID.
856	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
857	for this name/value pair.
858	@param[in] Prompt The string ID for Prompt.
859	@param[in] Help The string ID for Help.
860	@param[in] QuestionFlags The flags in Question Header.
861	@param[in] OneOfFlags The flags for a oneof opcode.
862	@param[in] OptionsOpCodeHandle The handle for a buffer of ONE_OF_OPTION opcodes.
863	@param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This
864	is an optional parameter that may be NULL.
865
866	@retval NULL There is not enough space left in Buffer to add the opcode.
867	@retval Other A pointer to the created opcode.
868
869	**/
870	UINT8 *
871	EFIAPI
872	HiiCreateOneOfOpCode (
873	IN VOID *OpCodeHandle,
874	IN EFI_QUESTION_ID QuestionId,
875	IN EFI_VARSTORE_ID VarStoreId,
876	IN UINT16 VarOffset,
877	IN EFI_STRING_ID Prompt,
878	IN EFI_STRING_ID Help,
879	IN UINT8 QuestionFlags,
880	IN UINT8 OneOfFlags,
881	IN VOID *OptionsOpCodeHandle,
882	IN VOID *DefaultsOpCodeHandle OPTIONAL
883	);
884
885	/**
886	Create EFI_IFR_ORDERED_LIST_OP opcode.
887
888	If OpCodeHandle is NULL, then ASSERT().
889	If any reserved bits are set in QuestionFlags, then ASSERT().
890	If any reserved bits are set in OrderedListFlags, then ASSERT().
891
892	@param[in] OpCodeHandle The handle to the buffer of opcodes.
893	@param[in] QuestionId The question ID.
894	@param[in] VarStoreId The storage ID.
895	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
896	for this name/value pair.
897	@param[in] Prompt The string ID for Prompt.
898	@param[in] Help The string ID for Help.
899	@param[in] QuestionFlags The flags in Question Header.
900	@param[in] OrderedListFlags The flags for an ordered list opcode.
901	@param[in] DataType The type for option value.
902	@param[in] MaxContainers Maximum count for options in this ordered list
903	@param[in] OptionsOpCodeHandle The handle for a buffer of ONE_OF_OPTION opcodes.
904	@param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This
905	is an optional parameter that may be NULL.
906
907	@retval NULL There is not enough space left in Buffer to add the opcode.
908	@retval Other A pointer to the created opcode.
909
910	**/
911	UINT8 *
912	EFIAPI
913	HiiCreateOrderedListOpCode (
914	IN VOID *OpCodeHandle,
915	IN EFI_QUESTION_ID QuestionId,
916	IN EFI_VARSTORE_ID VarStoreId,
917	IN UINT16 VarOffset,
918	IN EFI_STRING_ID Prompt,
919	IN EFI_STRING_ID Help,
920	IN UINT8 QuestionFlags,
921	IN UINT8 OrderedListFlags,
922	IN UINT8 DataType,
923	IN UINT8 MaxContainers,
924	IN VOID *OptionsOpCodeHandle,
925	IN VOID *DefaultsOpCodeHandle OPTIONAL
926	);
927
928	/**
929	Create EFI_IFR_TEXT_OP opcode.
930
931	If OpCodeHandle is NULL, then ASSERT().
932
933	@param[in] OpCodeHandle Handle to the buffer of opcodes.
934	@param[in] Prompt String ID for Prompt.
935	@param[in] Help String ID for Help.
936	@param[in] TextTwo String ID for TextTwo.
937
938	@retval NULL There is not enough space left in Buffer to add the opcode.
939	@retval Other A pointer to the created opcode.
940
941	**/
942	UINT8 *
943	EFIAPI
944	HiiCreateTextOpCode (
945	IN VOID *OpCodeHandle,
946	IN EFI_STRING_ID Prompt,
947	IN EFI_STRING_ID Help,
948	IN EFI_STRING_ID TextTwo
949	);
950
951	/**
952	Create EFI_IFR_DATE_OP opcode.
953
954	If OpCodeHandle is NULL, then ASSERT().
955	If any reserved bits are set in QuestionFlags, then ASSERT().
956	If any reserved bits are set in DateFlags, then ASSERT().
957
958	@param[in] OpCodeHandle Handle to the buffer of opcodes.
959	@param[in] QuestionId Question ID
960	@param[in] VarStoreId Storage ID, optional. If DateFlags is not
961	QF_DATE_STORAGE_NORMAL, this parameter is ignored.
962	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
963	for this name/value pair, optional. If DateFlags is not
964	QF_DATE_STORAGE_NORMAL, this parameter is ignored.
965	@param[in] Prompt String ID for Prompt
966	@param[in] Help String ID for Help
967	@param[in] QuestionFlags Flags in Question Header
968	@param[in] DateFlags Flags for date opcode
969	@param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This
970	is an optional parameter that may be NULL.
971
972	@retval NULL There is not enough space left in Buffer to add the opcode.
973	@retval Other A pointer to the created opcode.
974
975	**/
976	UINT8 *
977	EFIAPI
978	HiiCreateDateOpCode (
979	IN VOID *OpCodeHandle,
980	IN EFI_QUESTION_ID QuestionId,
981	IN EFI_VARSTORE_ID VarStoreId, OPTIONAL
982	IN UINT16 VarOffset, OPTIONAL
983	IN EFI_STRING_ID Prompt,
984	IN EFI_STRING_ID Help,
985	IN UINT8 QuestionFlags,
986	IN UINT8 DateFlags,
987	IN VOID *DefaultsOpCodeHandle OPTIONAL
988	);
989
990	/**
991	Create EFI_IFR_TIME_OP opcode.
992
993	If OpCodeHandle is NULL, then ASSERT().
994	If any reserved bits are set in QuestionFlags, then ASSERT().
995	If any reserved bits are set in TimeFlags, then ASSERT().
996
997	@param[in] OpCodeHandle Handle to the buffer of opcodes.
998	@param[in] QuestionId Question ID
999	@param[in] VarStoreId Storage ID, optional. If TimeFlags is not
1000	QF_TIME_STORAGE_NORMAL, this parameter is ignored.
1001	@param[in] VarOffset Offset in Storage or String ID of the name (VarName)
1002	for this name/value pair, optional. If TimeFlags is not
1003	QF_TIME_STORAGE_NORMAL, this parameter is ignored.
1004	@param[in] Prompt String ID for Prompt
1005	@param[in] Help String ID for Help
1006	@param[in] QuestionFlags Flags in Question Header
1007	@param[in] TimeFlags Flags for time opcode
1008	@param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This
1009	is an optional parameter that may be NULL.
1010
1011	@retval NULL There is not enough space left in Buffer to add the opcode.
1012	@retval Other A pointer to the created opcode.
1013
1014	**/
1015	UINT8 *
1016	EFIAPI
1017	HiiCreateTimeOpCode (
1018	IN VOID *OpCodeHandle,
1019	IN EFI_QUESTION_ID QuestionId,
1020	IN EFI_VARSTORE_ID VarStoreId, OPTIONAL
1021	IN UINT16 VarOffset, OPTIONAL
1022	IN EFI_STRING_ID Prompt,
1023	IN EFI_STRING_ID Help,
1024	IN UINT8 QuestionFlags,
1025	IN UINT8 TimeFlags,
1026	IN VOID *DefaultsOpCodeHandle OPTIONAL
1027	);
1028
1029	/**
1030	This function updates a form that has previously been registered with the HII
1031	Database. This function will perform at most one update operation.
1032
1033	The form to update is specified by Handle, FormSetGuid, and FormId. Binary
1034	comparisons of IFR opcodes are performed from the beginning of the form being
1035	updated until an IFR opcode is found that exactly matches the first IFR opcode
1036	specified by StartOpCodeHandle. The following rules are used to determine if
1037	an insert, replace, or delete operation is performed:
1038
1039	1) If no matches are found, then NULL is returned.
1040	2) If a match is found, and EndOpCodeHandle is NULL, then all of the IFR opcodes
1041	from StartOpCodeHandle except the first opcode are inserted immediately after
1042	the matching IFR opcode in the form to be updated.
1043	3) If a match is found, and EndOpCodeHandle is not NULL, then a search is made
1044	from the matching IFR opcode until an IFR opcode exactly matches the first
1045	IFR opcode specified by EndOpCodeHandle. If no match is found for the first
1046	IFR opcode specified by EndOpCodeHandle, then NULL is returned. If a match
1047	is found, then all of the IFR opcodes between the start match and the end
1048	match are deleted from the form being updated and all of the IFR opcodes
1049	from StartOpCodeHandle except the first opcode are inserted immediately after
1050	the matching start IFR opcode. If StartOpCcodeHandle only contains one
1051	IFR instruction, then the result of this operation will delete all of the IFR
1052	opcodes between the start end matches.
1053
1054	If HiiHandle is NULL, then ASSERT().
1055	If StartOpCodeHandle is NULL, then ASSERT().
1056
1057	@param[in] HiiHandle The HII Handle of the form to update.
1058	@param[in] FormSetGuid The Formset GUID of the form to update. This
1059	is an optional parameter that may be NULL.
1060	If it is NULL, all FormSet will be updated.
1061	@param[in] FormId The ID of the form to update.
1062	@param[in] StartOpCodeHandle An OpCode Handle that contains the set of IFR
1063	opcodes to be inserted or replaced in the form.
1064	The first IFR instruction in StartOpCodeHandle
1065	is used to find matching IFR opcode in the
1066	form.
1067	@param[in] EndOpCodeHandle An OpCcode Handle that contains the IFR opcode
1068	that marks the end of a replace operation in
1069	the form. This is an optional parameter that
1070	may be NULL. If it is NULL, then the IFR
1071	opcodes specified by StartOpCodeHandle are
1072	inserted into the form.
1073
1074	@retval EFI_OUT_OF_RESOURCES Not enough memory resources are allocated.
1075	@retval EFI_NOT_FOUND The following cases will return EFI_NOT_FOUND:
1076	1) The form specified by HiiHandle, FormSetGuid,
1077	and FormId could not be found in the HII Database.
1078	2) No IFR opcodes in the target form match the first
1079	IFR opcode in StartOpCodeHandle.
1080	3) EndOpCOde is not NULL, and no IFR opcodes in the
1081	target form following a matching start opcode match
1082	the first IFR opcode in EndOpCodeHandle.
1083	@retval EFI_SUCCESS The matched form is updated by StartOpcode.
1084
1085	**/
1086	EFI_STATUS
1087	EFIAPI
1088	HiiUpdateForm (
1089	IN EFI_HII_HANDLE HiiHandle,
1090	IN EFI_GUID *FormSetGuid, OPTIONAL
1091	IN EFI_FORM_ID FormId,
1092	IN VOID *StartOpCodeHandle,
1093	IN VOID *EndOpCodeHandle OPTIONAL
1094	);
1095
1096	#endif

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

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

Download in other formats: