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)
42 Determine what is the current language setting
46 Lang - Pointer of system language
57 IN VOID
*StringBuffer
,
60 IN OUT STRING_REF
*StringToken
66 Add a string to the incoming buffer and return the token and offset data
70 StringBuffer - The incoming buffer
72 Language - Currrent language
74 String - The string to be added
76 StringToken - The index where the string placed
80 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
82 EFI_SUCCESS - String successfully added to the incoming buffer
90 IN OUT VOID
*OpCodeData
96 Add op-code data to the FormBuffer
100 FormBuffer - Form buffer to be inserted to
102 OpCodeData - Op-code data to be inserted
106 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
108 EFI_SUCCESS - Op-code data successfully inserted
115 IN CHAR16
*FormSetTitle
,
119 IN OUT VOID
**FormBuffer
,
120 IN OUT VOID
**StringBuffer
130 FormSetTitle - Title of formset
132 Guid - Guid of formset
134 Class - Class of formset
136 SubClass - Sub class of formset
138 FormBuffer - Pointer of the formset created
140 StringBuffer - Pointer of FormSetTitile string created
144 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
146 EFI_SUCCESS - Formset successfully created
153 IN CHAR16
*FormTitle
,
155 IN OUT VOID
*FormBuffer
,
156 IN OUT VOID
*StringBuffer
166 FormTitle - Title of the form
168 FormId - Id of the form
170 FormBuffer - Pointer of the form created
172 StringBuffer - Pointer of FormTitil string created
176 EFI_SUCCESS - Form successfully created
184 IN OUT VOID
*FormBuffer
,
185 IN OUT VOID
*StringBuffer
195 SubTitle - Sub title to be created
197 FormBuffer - Where this subtitle to add to
199 StringBuffer - String buffer created for subtitle
203 EFI_SUCCESS - Subtitle successfully created
215 IN OUT VOID
*FormBuffer
,
216 IN OUT VOID
*StringBuffer
222 Create a line of text
226 String - First string of the text
228 String2 - Second string of the text
230 String3 - Help string of the text
232 Flags - Flag of the text
234 Key - Key of the text
236 FormBuffer - The form where this text adds to
238 StringBuffer - String buffer created for String, String2 and String3
242 EFI_SUCCESS - Text successfully created
251 IN OUT VOID
*FormBuffer
,
252 IN OUT VOID
*StringBuffer
262 FormId - Form ID of the hyperlink
264 Prompt - Prompt of the hyperlink
266 FormBuffer - The form where this hyperlink adds to
268 StringBuffer - String buffer created for Prompt
272 EFI_SUCCESS - Hyperlink successfully created
279 IN UINT16 QuestionId
,
283 IN IFR_OPTION
*OptionsList
,
284 IN UINTN OptionCount
,
285 IN OUT VOID
*FormBuffer
,
286 IN OUT VOID
*StringBuffer
292 Create a one-of question with a set of options to choose from. The
293 OptionsList is a pointer to a null-terminated list of option descriptions.
297 QuestionId - Question ID of the one-of box
299 DataWidth - DataWidth of the one-of box
301 Prompt - Prompt of the one-of box
303 Help - Help of the one-of box
305 OptionsList - Each string in it is an option of the one-of box
307 OptionCount - Option string count
309 FormBuffer - The form where this one-of box adds to
311 StringBuffer - String buffer created for Prompt, Help and Option strings
315 EFI_DEVICE_ERROR - DataWidth > 2
317 EFI_SUCCESS - One-Of box successfully created.
324 IN UINT16 QuestionId
,
328 IN IFR_OPTION
*OptionsList
,
329 IN UINTN OptionCount
,
330 IN OUT VOID
*FormBuffer
,
331 IN OUT VOID
*StringBuffer
337 Create a one-of question with a set of options to choose from. The
338 OptionsList is a pointer to a null-terminated list of option descriptions.
342 QuestionId - Question ID of the ordered list
344 MaxEntries - MaxEntries of the ordered list
346 Prompt - Prompt of the ordered list
348 Help - Help of the ordered list
350 OptionsList - Each string in it is an option of the ordered list
352 OptionCount - Option string count
354 FormBuffer - The form where this ordered list adds to
356 StringBuffer - String buffer created for Prompt, Help and Option strings
360 EFI_SUCCESS - Ordered list successfully created.
367 IN UINT16 QuestionId
,
372 IN OUT VOID
*FormBuffer
,
373 IN OUT VOID
*StringBuffer
383 QuestionId - Question ID of the check box
385 DataWidth - DataWidth of the check box
387 Prompt - Prompt of the check box
389 Help - Help of the check box
391 Flags - Flags of the check box
393 FormBuffer - The form where this check box adds to
395 StringBuffer - String buffer created for Prompt and Help.
399 EFI_DEVICE_ERROR - DataWidth > 1
401 EFI_SUCCESS - Check box successfully created
408 IN UINT16 QuestionId
,
418 IN OUT VOID
*FormBuffer
,
419 IN OUT VOID
*StringBuffer
429 QuestionId - Question ID of the numeric
431 DataWidth - DataWidth of the numeric
433 Prompt - Prompt of the numeric
435 Help - Help of the numeric
437 Minimum - Minumun boundary of the numeric
439 Maximum - Maximum boundary of the numeric
441 Step - Step of the numeric
443 Default - Default value
445 Flags - Flags of the numeric
447 Key - Key of the numeric
449 FormBuffer - The form where this numeric adds to
451 StringBuffer - String buffer created for Prompt and Help.
455 EFI_DEVICE_ERROR - DataWidth > 2
457 EFI_SUCCESS - Numeric is successfully created
464 IN UINT16 QuestionId
,
472 IN OUT VOID
*FormBuffer
,
473 IN OUT VOID
*StringBuffer
483 QuestionId - Question ID of the string
485 DataWidth - DataWidth of the string
487 Prompt - Prompt of the string
489 Help - Help of the string
491 MinSize - Min size boundary of the string
493 MaxSize - Max size boundary of the string
495 Flags - Flags of the string
497 Key - Key of the string
499 FormBuffer - The form where this string adds to
501 StringBuffer - String buffer created for Prompt and Help.
505 EFI_SUCCESS - String successfully created.
511 ExtractDataFromHiiHandle (
512 IN FRAMEWORK_EFI_HII_HANDLE HiiHandle
,
513 IN OUT UINT16
*ImageLength
,
514 OUT UINT8
*DefaultImage
,
521 Extract information pertaining to the HiiHandle
525 HiiHandle - Hii handle
527 ImageLength - For input, length of DefaultImage;
528 For output, length of actually required
530 DefaultImage - Image buffer prepared by caller
532 Guid - Guid information about the form
536 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
538 EFI_BUFFER_TOO_SMALL - DefualtImage has no enough ImageLength
540 EFI_SUCCESS - Successfully extract data from Hii database.
546 FRAMEWORK_EFI_HII_HANDLE
548 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
554 Finds HII handle for given pack GUID previously registered with the HII.
557 HiiProtocol - pointer to pointer to HII protocol interface.
558 If NULL, the interface will be found but not returned.
559 If it points to NULL, the interface will be found and
560 written back to the pointer that is pointed to.
561 Guid - The GUID of the pack that registered with the HII.
564 Handle to the HII pack previously registered by the memory driver.
570 CreateSubTitleOpCode (
571 IN STRING_REF StringToken
,
572 IN OUT VOID
*FormBuffer
578 Create a SubTitle opcode independent of string creation
579 This is used primarily by users who need to create just one particular valid op-code and the string
580 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
581 location to pre-defined forms in HII)
585 StringToken - StringToken of the subtitle
587 FormBuffer - Output of subtitle as a form
591 EFI_SUCCESS - Subtitle created to be a form
598 IN STRING_REF StringToken
,
599 IN STRING_REF StringTokenTwo
,
600 IN STRING_REF StringTokenThree
,
603 IN OUT VOID
*FormBuffer
609 Create a Text opcode independent of string creation
610 This is used primarily by users who need to create just one particular valid op-code and the string
611 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
612 location to pre-defined forms in HII)
616 StringToken - First string token of the text
618 StringTokenTwo - Second string token of the text
620 StringTokenThree - Help string token of the text
622 Flags - Flag of the text
624 Key - Key of the text
626 FormBuffer - Output of text as a form
630 EFI_SUCCESS - Text created to be a form
638 IN STRING_REF StringToken
,
639 IN STRING_REF StringTokenTwo
,
642 IN OUT VOID
*FormBuffer
648 Create a hyperlink opcode independent of string creation
649 This is used primarily by users who need to create just one particular valid op-code and the string
650 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
651 location to pre-defined forms in HII)
655 FormId - Form ID of the hyperlink
657 StringToken - Prompt string token of the hyperlink
659 StringTokenTwo - Help string token of the hyperlink
661 Flags - Flags of the hyperlink
663 Key - Key of the hyperlink
665 FormBuffer - Output of hyperlink as a form
669 EFI_SUCCESS - Hyperlink created to be a form
676 IN UINT16 QuestionId
,
678 IN STRING_REF PromptToken
,
679 IN STRING_REF HelpToken
,
680 IN IFR_OPTION
*OptionsList
,
681 IN UINTN OptionCount
,
682 IN OUT VOID
*FormBuffer
688 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
689 This is used primarily by users who need to create just one particular valid op-code and the string
690 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
691 location to pre-defined forms in HII)
693 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
694 has been filled in since this routine will not generate StringToken values.
698 QuestionId - Question ID of the one-of box
700 DataWidth - DataWidth of the one-of box
702 PromptToken - Prompt string token of the one-of box
704 HelpToken - Help string token of the one-of box
706 OptionsList - Each string in it is an option of the one-of box
708 OptionCount - Option string count
710 FormBuffer - Output of One-Of box as a form
714 EFI_SUCCESS - One-Of box created to be a form
716 EFI_DEVICE_ERROR - DataWidth > 2
722 CreateOrderedListOpCode (
723 IN UINT16 QuestionId
,
725 IN STRING_REF PromptToken
,
726 IN STRING_REF HelpToken
,
727 IN IFR_OPTION
*OptionsList
,
728 IN UINTN OptionCount
,
729 IN OUT VOID
*FormBuffer
735 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
736 This is used primarily by users who need to create just one particular valid op-code and the string
737 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
738 location to pre-defined forms in HII)
740 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
741 has been filled in since this routine will not generate StringToken values.
745 QuestionId - Question ID of the ordered list
747 MaxEntries - MaxEntries of the ordered list
749 PromptToken - Prompt string token of the ordered list
751 HelpToken - Help string token of the ordered list
753 OptionsList - Each string in it is an option of the ordered list
755 OptionCount - Option string count
757 FormBuffer - Output of ordered list as a form
761 EFI_SUCCESS - Ordered list created to be a form
767 CreateCheckBoxOpCode (
768 IN UINT16 QuestionId
,
770 IN STRING_REF PromptToken
,
771 IN STRING_REF HelpToken
,
774 IN OUT VOID
*FormBuffer
780 Create a checkbox opcode independent of string creation
781 This is used primarily by users who need to create just one particular valid op-code and the string
782 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
783 location to pre-defined forms in HII)
787 QuestionId - Question ID of the check box
789 DataWidth - DataWidth of the check box
791 PromptToken - Prompt string token of the check box
793 HelpToken - Help string token of the check box
795 Flags - Flags of the check box
797 Key - Key of the check box
799 FormBuffer - Output of the check box as a form
803 EFI_SUCCESS - Checkbox created to be a form
805 EFI_DEVICE_ERROR - DataWidth > 1
811 CreateNumericOpCode (
812 IN UINT16 QuestionId
,
814 IN STRING_REF PromptToken
,
815 IN STRING_REF HelpToken
,
822 IN OUT VOID
*FormBuffer
828 Create a numeric opcode independent of string creation
829 This is used primarily by users who need to create just one particular valid op-code and the string
830 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
831 location to pre-defined forms in HII)
835 QuestionId - Question ID of the numeric
837 DataWidth - DataWidth of the numeric
839 PromptToken - Prompt string token of the numeric
841 HelpToken - Help string token of the numeric
843 Minimum - Minumun boundary of the numeric
845 Maximum - Maximum boundary of the numeric
847 Step - Step of the numeric
849 Default - Default value of the numeric
851 Flags - Flags of the numeric
853 Key - Key of the numeric
855 FormBuffer - Output of the numeric as a form
859 EFI_SUCCESS - The numeric created to be a form.
861 EFI_DEVICE_ERROR - DataWidth > 2
868 IN UINT16 QuestionId
,
870 IN STRING_REF PromptToken
,
871 IN STRING_REF HelpToken
,
876 IN OUT VOID
*FormBuffer
882 Create a numeric opcode independent of string creation
883 This is used primarily by users who need to create just one particular valid op-code and the string
884 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
885 location to pre-defined forms in HII)
889 QuestionId - Question ID of the string
891 DataWidth - DataWidth of the string
893 PromptToken - Prompt token of the string
895 HelpToken - Help token of the string
897 MinSize - Min size boundary of the string
899 MaxSize - Max size boundary of the string
901 Flags - Flags of the string
903 Key - Key of the string
905 FormBuffer - Output of the string as a form
909 EFI_SUCCESS - String created to be a form.
915 ValidateDataFromHiiHandle (
916 IN FRAMEWORK_EFI_HII_HANDLE HiiHandle
,
923 Validate that the data associated with the HiiHandle in NVRAM is within
924 the reasonable parameters for that FormSet. Values for strings and passwords
925 are not verified due to their not having the equivalent of valid range settings.
929 HiiHandle - Handle of the HII database entry to query
931 Results - If return Status is EFI_SUCCESS, Results provides valid data
932 TRUE = NVRAM Data is within parameters
933 FALSE = NVRAM Data is NOT within parameters
937 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
939 EFI_SUCCESS - Data successfully validated
946 IN UINT16 LineNumber
,
948 IN OUT VOID
*FormBuffer
954 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
958 Title - Title of the banner
960 LineNumber - LineNumber of the banner
962 Alignment - Alignment of the banner
964 FormBuffer - Output of banner as a form
968 EFI_SUCCESS - Banner created to be a form.
974 EfiLibHiiVariablePackGetMap (
975 IN EFI_HII_VARIABLE_PACK
*Pack
,
976 OUT CHAR16
**Name
, OPTIONAL
977 OUT EFI_GUID
**Guid
, OPTIONAL
978 OUT UINT16
*Id
, OPTIONAL
979 OUT VOID
**Var
, OPTIONAL
980 OUT UINTN
*Size OPTIONAL
986 Extracts a variable form a Pack.
990 Pack - List of variables
991 Name - Name of the variable/map
992 Guid - GUID of the variable/map
993 Var - Pointer to the variable/map
994 Size - Size of the variable/map in bytes
1004 EfiLibHiiVariablePackListGetMapCnt (
1005 IN EFI_HII_VARIABLE_PACK_LIST
*List
1009 Routine Description:
1011 Finds a count of the variables/maps in the List.
1015 List - List of variables
1019 Number of Map in the variable pack list.
1024 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
1033 Routine Description:
1035 type definition for the callback to be
1036 used with EfiLibHiiVariablePackListForEachVar().
1040 Id - Variable/Map ID
1041 Name - Name of the variable/map
1042 Guid - GUID of the variable/map
1043 Var - Pointer to the variable/map
1044 Size - Size of the variable/map in bytes
1054 EfiLibHiiVariablePackListForEachVar (
1055 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1056 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
1060 Routine Description:
1062 Will iterate all variable/maps as appearing
1063 in List and for each, it will call the Callback.
1067 List - List of variables
1068 Callback - Routine to be called for each iterated variable.
1078 EfiLibHiiVariablePackListGetMapByIdx (
1080 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1081 OUT CHAR16
**Name
, OPTIONAL
1082 OUT EFI_GUID
**Guid
, OPTIONAL
1083 OUT UINT16
*Id
, OPTIONAL
1089 Routine Description:
1091 Finds a variable form List given
1092 the order number as appears in the List.
1096 Idx - The index of the variable/map to retrieve
1097 List - List of variables
1098 Name - Name of the variable/map
1099 Guid - GUID of the variable/map
1100 Var - Pointer to the variable/map
1101 Size - Size of the variable/map in bytes
1105 EFI_SUCCESS - Variable is found, OUT parameters are valid
1106 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1112 EfiLibHiiVariablePackListGetMapById (
1114 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1115 OUT CHAR16
**Name
, OPTIONAL
1116 OUT EFI_GUID
**Guid
, OPTIONAL
1122 Routine Description:
1124 Finds a variable form List given the
1125 order number as appears in the List.
1129 Id - The ID of the variable/map to retrieve
1130 List - List of variables
1131 Name - Name of the variable/map
1132 Guid - GUID of the variable/map
1133 Var - Pointer to the variable/map
1134 Size - Size of the variable/map in bytes
1138 EFI_SUCCESS - Variable is found, OUT parameters are valid
1139 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1145 EfiLibHiiVariablePackListGetMap (
1146 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1155 Routine Description:
1157 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
1161 List - List of variables
1162 Name - Name of the variable/map to be found
1163 Guid - GUID of the variable/map to be found
1164 Var - Pointer to the variable/map found
1165 Size - Size of the variable/map in bytes found
1169 EFI_SUCCESS - variable is found, OUT parameters are valid
1170 EFI_NOT_FOUND - variable is not found, OUT parameters are not valid
1176 EfiLibHiiVariableRetrieveFromNv (
1184 Routine Description:
1185 Finds out if a variable of specific Name/Guid/Size exists in NV.
1186 If it does, it will retrieve it into the Var.
1189 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1190 Var - Variable will be retrieved into buffer pointed by this pointer.
1191 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
1193 EFI_SUCCESS - The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
1194 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1195 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1201 //// Variable override support.
1205 EfiLibHiiVariableOverrideIfSuffix (
1214 Routine Description:
1215 Overrrides the variable with NV data if found.
1216 But it only does it if the Name ends with specified Suffix.
1217 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
1218 the Suffix matches the end of Name, so the variable will be loaded from NV
1219 provided the variable exists and the GUID and Size matches.
1222 Suffix - Suffix the Name should end with.
1223 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1224 Var - Variable will be retrieved into this buffer.
1225 Caller is responsible for providing storage of exactly Size size in bytes.
1227 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1228 EFI_INVALID_PARAMETER - The name of the variable does not end with <Suffix>.
1229 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1230 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1236 EfiLibHiiVariableOverrideBySuffix (
1245 Routine Description:
1246 Overrrides the variable with NV data if found.
1247 But it only does it if the NV contains the same variable with Name is appended with Suffix.
1248 For example, if Suffix="MyOverride" and the Name="XyzSetup",
1249 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
1250 will be loaded from NV provided the variable exists and the GUID and Size matches.
1253 Suffix - Suffix the variable will be appended with.
1254 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1255 Var - Variable will be retrieved into this buffer.
1256 Caller is responsible for providing storage of exactly Size size in bytes.
1259 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1260 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1261 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.