2 Library class name: FrameworkIfrSupportLib
4 FrameworkIfrSupportLib is designed for produce IFR operation interface .
5 The IFR format follows framework specification.
7 Copyright (c) 2006, Intel Corporation
8 All rights reserved. This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 #ifndef _IFRSUPPORTLIBRARY_H_
19 #define _IFRSUPPORTLIBRARY_H_
21 #define DEFAULT_FORM_BUFFER_SIZE 0xFFFF
22 #define DEFAULT_STRING_BUFFER_SIZE 0xFFFF
26 CHAR16
*OptionString
; // Passed in string to generate a token for in a truly dynamic form creation
27 STRING_REF StringToken
; // This is used when creating a single op-code without generating a StringToken (have one already)
35 Determine what is the current language setting.
37 The setting is stored in language variable in flash. This routine
38 will get setting by accesssing that variable. If failed to access
39 language variable, then use default setting that 'eng' as current
42 @param Lang Pointer of system language
44 @return whether success to get setting from variable
53 Add a string to the incoming buffer and return the token and offset data.
55 @param StringBuffer The incoming buffer
56 @param Language Currrent language
57 @param String The string to be added
58 @param StringToken The index where the string placed
60 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
61 @retval EFI_SUCCESS String successfully added to the incoming buffer
66 IN VOID
*StringBuffer
,
69 IN OUT STRING_REF
*StringToken
73 Add op-code data to the FormBuffer.
75 @param FormBuffer Form buffer to be inserted to
76 @param OpCodeData Op-code data to be inserted
78 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
79 @retval EFI_SUCCESS Op-code data successfully inserted
85 IN OUT VOID
*OpCodeData
91 The form package is a collection of forms that are intended to describe the pages that will be
92 displayed to the user.
94 @param FormSetTitle Title of formset
95 @param Guid Guid of formset
96 @param Class Class of formset
97 @param SubClass Sub class of formset
98 @param FormBuffer Pointer of the formset created
99 @param StringBuffer Pointer of FormSetTitile string created
101 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
102 @retval EFI_SUCCESS Formset successfully created
107 IN CHAR16
*FormSetTitle
,
111 IN OUT VOID
**FormBuffer
,
112 IN OUT VOID
**StringBuffer
117 A form is the encapsulation of what amounts to a browser page. The header defines a FormId,
118 which is referenced by the form package, among others. It also defines a FormTitle, which is a
119 string to be used as the title for the form
121 @param FormTitle Title of the form
122 @param FormId Id of the form
123 @param FormBuffer Pointer of the form created
124 @param StringBuffer Pointer of FormTitil string created
126 @retval EFI_SUCCESS Form successfully created
131 IN CHAR16
*FormTitle
,
133 IN OUT VOID
*FormBuffer
,
134 IN OUT VOID
*StringBuffer
140 Subtitle strings are intended to be used by authors to separate sections of questions into semantic
143 @param SubTitle Sub title to be created
144 @param FormBuffer Where this subtitle to add to
145 @param StringBuffer String buffer created for subtitle
147 @retval EFI_SUCCESS Subtitle successfully created
153 IN OUT VOID
*FormBuffer
,
154 IN OUT VOID
*StringBuffer
158 Create a line of text
159 Unlike HTML, text is simply another tag.
160 This tag type enables IFR to be more easily localized.
162 @param String First string of the text
163 @param String2 Second string of the text
164 @param String3 Help string of the text
165 @param Flags Flag of the text
166 @param Key Key of the text
167 @param FormBuffer The form where this text adds to
168 @param StringBuffer String buffer created for String, String2 and String3
170 @retval EFI_SUCCESS Text successfully created
180 IN OUT VOID
*FormBuffer
,
181 IN OUT VOID
*StringBuffer
187 @param FormId Form ID of the hyperlink
188 @param Prompt Prompt of the hyperlink
189 @param FormBuffer The form where this hyperlink adds to
190 @param StringBuffer String buffer created for Prompt
192 @retval EFI_SUCCESS Hyperlink successfully created
199 IN OUT VOID
*FormBuffer
,
200 IN OUT VOID
*StringBuffer
204 Create a one-of question with a set of options to choose from. The
205 OptionsList is a pointer to a null-terminated list of option descriptions.
207 @param QuestionId Question ID of the one-of box
208 @param DataWidth DataWidth of the one-of box
209 @param Prompt Prompt of the one-of box
210 @param Help Help of the one-of box
211 @param OptionsList Each string in it is an option of the one-of box
212 @param OptionCount Option string count
213 @param FormBuffer The form where this one-of box adds to
214 @param StringBuffer String buffer created for Prompt, Help and Option strings
216 @retval EFI_DEVICE_ERROR DataWidth > 2
217 @retval EFI_SUCCESS One-Of box successfully created.
222 IN UINT16 QuestionId
,
226 IN IFR_OPTION
*OptionsList
,
227 IN UINTN OptionCount
,
228 IN OUT VOID
*FormBuffer
,
229 IN OUT VOID
*StringBuffer
233 Create a one-of question with a set of options to choose from. The
234 OptionsList is a pointer to a null-terminated list of option descriptions.
236 @param QuestionId Question ID of the ordered list
237 @param MaxEntries MaxEntries of the ordered list
238 @param Prompt Prompt of the ordered list
239 @param Help Help of the ordered list
240 @param OptionsList Each string in it is an option of the ordered list
241 @param OptionCount Option string count
242 @param FormBuffer The form where this ordered list adds to
243 @param StringBuffer String buffer created for Prompt, Help and Option strings
245 @retval EFI_SUCCESS Ordered list successfully created.
250 IN UINT16 QuestionId
,
254 IN IFR_OPTION
*OptionsList
,
255 IN UINTN OptionCount
,
256 IN OUT VOID
*FormBuffer
,
257 IN OUT VOID
*StringBuffer
263 @param QuestionId Question ID of the check box
264 @param DataWidth DataWidth of the check box
265 @param Prompt Prompt of the check box
266 @param Help Help of the check box
267 @param Flags Flags of the check box
268 @param FormBuffer The form where this check box adds to
269 @param StringBuffer String buffer created for Prompt and Help.
271 @retval EFI_DEVICE_ERROR DataWidth > 1
272 @retval EFI_SUCCESS Check box successfully created
277 IN UINT16 QuestionId
,
282 IN OUT VOID
*FormBuffer
,
283 IN OUT VOID
*StringBuffer
289 @param QuestionId Question ID of the numeric
290 @param DataWidth DataWidth of the numeric
291 @param Prompt Prompt of the numeric
292 @param Help Help of the numeric
293 @param Minimum Minumun boundary of the numeric
294 @param Maximum Maximum boundary of the numeric
295 @param Step Step of the numeric
296 @param Default Default value
297 @param Flags Flags of the numeric
298 @param Key Key of the numeric
299 @param FormBuffer The form where this numeric adds to
300 @param StringBuffer String buffer created for Prompt and Help.
302 @retval EFI_DEVICE_ERROR DataWidth > 2
303 @retval EFI_SUCCESS Numeric is successfully created
308 IN UINT16 QuestionId
,
318 IN OUT VOID
*FormBuffer
,
319 IN OUT VOID
*StringBuffer
325 @param QuestionId Question ID of the string
326 @param DataWidth DataWidth of the string
327 @param Prompt Prompt of the string
328 @param Help Help of the string
329 @param MinSize Min size boundary of the string
330 @param MaxSize Max size boundary of the string
331 @param Flags Flags of the string
332 @param Key Key of the string
333 @param FormBuffer The form where this string adds to
334 @param StringBuffer String buffer created for Prompt and Help.
335 @retval EFI_SUCCESS String successfully created.
340 IN UINT16 QuestionId
,
348 IN OUT VOID
*FormBuffer
,
349 IN OUT VOID
*StringBuffer
353 Extract information pertaining to the HiiHandle.
355 @param HiiHandle Hii handle
356 @param ImageLength For input, length of DefaultImage;
357 For output, length of actually required
358 @param DefaultImage Image buffer prepared by caller
359 @param Guid Guid information about the form
361 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
362 @retval EFI_BUFFER_TOO_SMALL DefualtImage has no enough ImageLength
363 @retval EFI_SUCCESS Successfully extract data from Hii database.
367 ExtractDataFromHiiHandle (
368 IN FRAMEWORK_EFI_HII_HANDLE HiiHandle
,
369 IN OUT UINT16
*ImageLength
,
370 OUT UINT8
*DefaultImage
,
375 Finds HII handle for given pack GUID previously registered with the HII.
377 @param HiiProtocol pointer to pointer to HII protocol interface.
378 If NULL, the interface will be found but not returned.
379 If it points to NULL, the interface will be found and
380 written back to the pointer that is pointed to.
381 @param Guid The GUID of the pack that registered with the HII.
383 @return Handle to the HII pack previously registered by the memory driver.
385 FRAMEWORK_EFI_HII_HANDLE
388 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
393 Create a SubTitle opcode independent of string creation
394 This is used primarily by users who need to create just one particular valid op-code and the string
395 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
396 location to pre-defined forms in HII)
398 @param StringToken StringToken of the subtitle
399 @param FormBuffer Output of subtitle as a form
401 @retval EFI_SUCCESS Subtitle created to be a form
405 CreateSubTitleOpCode (
406 IN STRING_REF StringToken
,
407 IN OUT VOID
*FormBuffer
411 Create a Text opcode independent of string creation.
413 This is used primarily by users who need to create just one particular valid op-code and the string
414 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
415 location to pre-defined forms in HII)
417 @param StringToken First string token of the text
418 @param StringTokenTwo Second string token of the text
419 @param StringTokenThree Help string token of the text
420 @param Flags Flag of the text
421 @param Key Key of the text
422 @param FormBuffer Output of text as a form
424 @retval EFI_SUCCESS Text created to be a form
429 IN STRING_REF StringToken
,
430 IN STRING_REF StringTokenTwo
,
431 IN STRING_REF StringTokenThree
,
434 IN OUT VOID
*FormBuffer
438 Create a hyperlink opcode independent of string creation.
440 This is used primarily by users who need to create just one particular valid op-code and the string
441 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
442 location to pre-defined forms in HII)
445 @param FormId Form ID of the hyperlink
446 @param StringToken Prompt string token of the hyperlink
447 @param StringTokenTwo Help string token of the hyperlink
448 @param Flags Flags of the hyperlink
449 @param Key Key of the hyperlink
450 @param FormBuffer Output of hyperlink as a form
451 @retval EFI_SUCCESS Hyperlink created to be a form
457 IN STRING_REF StringToken
,
458 IN STRING_REF StringTokenTwo
,
461 IN OUT VOID
*FormBuffer
465 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
466 This is used primarily by users who need to create just one particular valid op-code and the string
467 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
468 location to pre-defined forms in HII)
470 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
471 has been filled in since this routine will not generate StringToken values.
473 @param QuestionId Question ID of the one-of box
474 @param DataWidth DataWidth of the one-of box
475 @param PromptToken Prompt string token of the one-of box
476 @param HelpToken Help string token of the one-of box
477 @param OptionsList Each string in it is an option of the one-of box
478 @param OptionCount Option string count
479 @param FormBuffer Output of One-Of box as a form
482 @retval EFI_SUCCESS One-Of box created to be a form
483 @retval EFI_DEVICE_ERROR DataWidth > 2
488 IN UINT16 QuestionId
,
490 IN STRING_REF PromptToken
,
491 IN STRING_REF HelpToken
,
492 IN IFR_OPTION
*OptionsList
,
493 IN UINTN OptionCount
,
494 IN OUT VOID
*FormBuffer
498 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
499 This is used primarily by users who need to create just one particular valid op-code and the string
500 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
501 location to pre-defined forms in HII)
503 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
504 has been filled in since this routine will not generate StringToken values.
506 @param QuestionId Question ID of the ordered list
507 @param MaxEntries MaxEntries of the ordered list
508 @param PromptToken Prompt string token of the ordered list
509 @param HelpToken Help string token of the ordered list
510 @param OptionsList Each string in it is an option of the ordered list
511 @param OptionCount Option string count
512 @param FormBuffer Output of ordered list as a form
514 @retval EFI_SUCCESS Ordered list created to be a form
518 CreateOrderedListOpCode (
519 IN UINT16 QuestionId
,
521 IN STRING_REF PromptToken
,
522 IN STRING_REF HelpToken
,
523 IN IFR_OPTION
*OptionsList
,
524 IN UINTN OptionCount
,
525 IN OUT VOID
*FormBuffer
529 Create a checkbox opcode independent of string creation
530 This is used primarily by users who need to create just one particular valid op-code and the string
531 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
532 location to pre-defined forms in HII)
534 @param QuestionId Question ID of the check box
535 @param DataWidth DataWidth of the check box
536 @param PromptToken Prompt string token of the check box
537 @param HelpToken Help string token of the check box
538 @param Flags Flags of the check box
539 @param Key Key of the check box
540 @param FormBuffer Output of the check box as a form
542 @retval EFI_SUCCESS Checkbox created to be a form
543 @retval EFI_DEVICE_ERROR DataWidth > 1
547 CreateCheckBoxOpCode (
548 IN UINT16 QuestionId
,
550 IN STRING_REF PromptToken
,
551 IN STRING_REF HelpToken
,
554 IN OUT VOID
*FormBuffer
558 Create a numeric opcode independent of string creation.
559 This is used primarily by users who need to create just one particular valid op-code and the string
560 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
561 location to pre-defined forms in HII)
563 @param QuestionId Question ID of the numeric
564 @param DataWidth DataWidth of the numeric
565 @param PromptToken Prompt string token of the numeric
566 @param HelpToken Help string token of the numeric
567 @param Minimum Minumun boundary of the numeric
568 @param Maximum Maximum boundary of the numeric
569 @param Step Step of the numeric
570 @param Default Default value of the numeric
571 @param Flags Flags of the numeric
572 @param Key Key of the numeric
573 @param FormBuffer Output of the numeric as a form
576 @retval EFI_SUCCESS The numeric created to be a form.
577 @retval EFI_DEVICE_ERROR DataWidth > 2
581 CreateNumericOpCode (
582 IN UINT16 QuestionId
,
584 IN STRING_REF PromptToken
,
585 IN STRING_REF HelpToken
,
592 IN OUT VOID
*FormBuffer
596 Create a numeric opcode independent of string creation
597 This is used primarily by users who need to create just one particular valid op-code and the string
598 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
599 location to pre-defined forms in HII)
601 @param QuestionId Question ID of the string
602 @param DataWidth DataWidth of the string
603 @param PromptToken Prompt token of the string
604 @param HelpToken Help token of the string
605 @param MinSize Min size boundary of the string
606 @param MaxSize Max size boundary of the string
607 @param Flags Flags of the string
608 @param Key Key of the string
609 @param FormBuffer Output of the string as a form
611 @retval EFI_SUCCESS String created to be a form.
616 IN UINT16 QuestionId
,
618 IN STRING_REF PromptToken
,
619 IN STRING_REF HelpToken
,
624 IN OUT VOID
*FormBuffer
628 Validate that the data associated with the HiiHandle in NVRAM is within
629 the reasonable parameters for that FormSet. Values for strings and passwords
630 are not verified due to their not having the equivalent of valid range settings.
632 @param HiiHandle Handle of the HII database entry to query
634 @param Results If return Status is EFI_SUCCESS, Results provides valid data
635 TRUE = NVRAM Data is within parameters
636 FALSE = NVRAM Data is NOT within parameters
637 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
638 @retval EFI_SUCCESS Data successfully validated
642 ValidateDataFromHiiHandle (
643 IN FRAMEWORK_EFI_HII_HANDLE HiiHandle
,
648 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
650 @param Title Title of the banner
651 @param LineNumber LineNumber of the banner
652 @param Alignment Alignment of the banner
653 @param FormBuffer Output of banner as a form
655 @retval EFI_SUCCESS Banner created to be a form.
661 IN UINT16 LineNumber
,
663 IN OUT VOID
*FormBuffer
667 Extracts a variable form a Pack.
669 @param Pack List of variables
670 @param Name Name of the variable/map
671 @param Guid GUID of the variable/map
672 @param Id The index of the variable/map to retrieve
673 @param Var Pointer to the variable/map
674 @param Size Size of the variable/map in bytes
678 EfiLibHiiVariablePackGetMap (
679 IN EFI_HII_VARIABLE_PACK
*Pack
,
680 OUT CHAR16
**Name
, OPTIONAL
681 OUT EFI_GUID
**Guid
, OPTIONAL
682 OUT UINT16
*Id
, OPTIONAL
683 OUT VOID
**Var
, OPTIONAL
684 OUT UINTN
*Size OPTIONAL
688 Finds a count of the variables/maps in the List.
690 @param List List of variables
692 @return The number of map count.
696 EfiLibHiiVariablePackListGetMapCnt (
697 IN EFI_HII_VARIABLE_PACK_LIST
*List
701 type definition for the callback to be
702 used with EfiLibHiiVariablePackListForEachVar().
704 @param Id Variable/Map ID
705 @param Name Name of the variable/map
706 @param Guid GUID of the variable/map
707 @param Var Pointer to the variable/map
708 @param Size Size of the variable/map in bytes
710 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
719 Will iterate all variable/maps as appearing
720 in List and for each, it will call the Callback.
722 @param List List of variables
723 @param Callback Routine to be called for each iterated variable.
727 EfiLibHiiVariablePackListForEachVar (
728 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
729 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
733 Finds a variable form List given
734 the order number as appears in the List.
736 @param Idx The index of the variable/map to retrieve
737 @param List List of variables
738 @param Name Name of the variable/map
739 @param Guid GUID of the variable/map
740 @param Id Id of the variable/map
741 @param Var Pointer to the variable/map
742 @param Size Size of the variable/map in bytes
744 @return EFI_SUCCESS Variable is found, OUT parameters are valid
745 @return EFI_NOT_FOUND Variable is not found, OUT parameters are not valid
749 EfiLibHiiVariablePackListGetMapByIdx (
751 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
752 OUT CHAR16
**Name
, OPTIONAL
753 OUT EFI_GUID
**Guid
, OPTIONAL
754 OUT UINT16
*Id
, OPTIONAL
760 Finds a variable form List given the
761 order number as appears in the List.
763 @param Id The ID of the variable/map to retrieve
764 @param List List of variables
765 @param Name Name of the variable/map
766 @param Guid GUID of the variable/map
767 @param Var Pointer to the variable/map
768 @param Size Size of the variable/map in bytes
770 @retval EFI_SUCCESS Variable is found, OUT parameters are valid
771 @retval EFI_NOT_FOUND Variable is not found, OUT parameters are not valid
775 EfiLibHiiVariablePackListGetMapById (
777 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
778 OUT CHAR16
**Name
, OPTIONAL
779 OUT EFI_GUID
**Guid
, OPTIONAL
785 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
787 @param List List of variables
788 @param Name Name of the variable/map to be found
789 @param Guid GUID of the variable/map to be found
790 @param Id Id of the variable/map to be found
791 @param Var Pointer to the variable/map found
792 @param Size Size of the variable/map in bytes found
794 @retval EFI_SUCCESS variable is found, OUT parameters are valid
795 @retval EFI_NOT_FOUND variable is not found, OUT parameters are not valid
799 EfiLibHiiVariablePackListGetMap (
800 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
809 Finds out if a variable of specific Name/Guid/Size exists in NV.
810 If it does, it will retrieve it into the Var.
812 @param Name Parameters of the variable to retrieve. Must match exactly.
813 @param Guid Parameters of the variable to retrieve. Must match exactly.
814 @param Size Parameters of the variable to retrieve. Must match exactly.
815 @param Var Variable will be retrieved into buffer pointed by this pointer.
816 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
818 @retval EFI_SUCCESS The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
819 @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV.
820 @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error.
824 EfiLibHiiVariableRetrieveFromNv (
832 Overrrides the variable with NV data if found.
833 But it only does it if the Name ends with specified Suffix.
834 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
835 the Suffix matches the end of Name, so the variable will be loaded from NV
836 provided the variable exists and the GUID and Size matches.
838 @param Suffix Suffix the Name should end with.
839 @param Name Name of the variable to retrieve.
840 @param Guid Guid of the variable to retrieve.
841 @param Size Parameters of the variable to retrieve.
842 @param Var Variable will be retrieved into this buffer.
843 Caller is responsible for providing storage of exactly Size size in bytes.
845 @retval EFI_SUCCESS The variable was overriden with NV variable of same Name/Guid/Size.
846 @retval EFI_INVALID_PARAMETER The name of the variable does not end with <Suffix>.
847 @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV.
848 @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error.
852 EfiLibHiiVariableOverrideIfSuffix (
861 Overrrides the variable with NV data if found.
862 But it only does it if the NV contains the same variable with Name is appended with Suffix.
863 For example, if Suffix="MyOverride" and the Name="XyzSetup",
864 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
865 will be loaded from NV provided the variable exists and the GUID and Size matches.
867 @param Suffix Suffix the variable will be appended with.
868 @param Name Parameters of the Name variable to retrieve.
869 @param Guid Parameters of the Guid variable to retrieve.
870 @param Size Parameters of the Size variable to retrieve.
871 @param Var Variable will be retrieved into this buffer.
872 Caller is responsible for providing storage of exactly Size size in bytes.
874 @retval EFI_SUCCESS The variable was overriden with NV variable of same Name/Guid/Size.
875 @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV.
876 @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error.
880 EfiLibHiiVariableOverrideBySuffix (