]> git.proxmox.com Git - mirror_edk2.git/blob - MdeModulePkg/Include/Library/HiiLib.h
projects / mirror_edk2.git / blob
? search:


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