3 Copyright (c) 2004 - 2005, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 The file contain all library function for Ifr Operations.
25 #include "EfiDriverLib.h"
27 #include EFI_PROTOCOL_DEFINITION (Hii)
28 #include EFI_GUID_DEFINITION (GlobalVariable)
30 #define DEFAULT_FORM_BUFFER_SIZE 0xFFFF
31 #define DEFAULT_STRING_BUFFER_SIZE 0xFFFF
35 CHAR16
*OptionString
; // Passed in string to generate a token for in a truly dynamic form creation
36 STRING_REF StringToken
; // This is used when creating a single op-code without generating a StringToken (have one already)
51 Determine what is the current language setting
55 Lang - Pointer of system language
64 #ifdef SUPPORT_DEPRECATED_IFRSUPPORTLIB_API
67 IN VOID
*StringBuffer
,
70 IN OUT STRING_REF
*StringToken
76 Add a string to the incoming buffer and return the token and offset data
80 StringBuffer - The incoming buffer
82 Language - Currrent language
84 String - The string to be added
86 StringToken - The index where the string placed
90 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
92 EFI_SUCCESS - String successfully added to the incoming buffer
100 IN OUT VOID
*OpCodeData
106 Add op-code data to the FormBuffer
110 FormBuffer - Form buffer to be inserted to
112 OpCodeData - Op-code data to be inserted
116 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
118 EFI_SUCCESS - Op-code data successfully inserted
125 IN CHAR16
*FormSetTitle
,
129 IN OUT VOID
**FormBuffer
,
130 IN OUT VOID
**StringBuffer
140 FormSetTitle - Title of formset
142 Guid - Guid of formset
144 Class - Class of formset
146 SubClass - Sub class of formset
148 FormBuffer - Pointer of the formset created
150 StringBuffer - Pointer of FormSetTitile string created
154 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
156 EFI_SUCCESS - Formset successfully created
163 IN CHAR16
*FormTitle
,
165 IN OUT VOID
*FormBuffer
,
166 IN OUT VOID
*StringBuffer
176 FormTitle - Title of the form
178 FormId - Id of the form
180 FormBuffer - Pointer of the form created
182 StringBuffer - Pointer of FormTitil string created
186 EFI_SUCCESS - Form successfully created
194 IN OUT VOID
*FormBuffer
,
195 IN OUT VOID
*StringBuffer
205 SubTitle - Sub title to be created
207 FormBuffer - Where this subtitle to add to
209 StringBuffer - String buffer created for subtitle
213 EFI_SUCCESS - Subtitle successfully created
225 IN OUT VOID
*FormBuffer
,
226 IN OUT VOID
*StringBuffer
232 Create a line of text
236 String - First string of the text
238 String2 - Second string of the text
240 String3 - Help string of the text
242 Flags - Flag of the text
244 Key - Key of the text
246 FormBuffer - The form where this text adds to
248 StringBuffer - String buffer created for String, String2 and String3
252 EFI_SUCCESS - Text successfully created
261 IN OUT VOID
*FormBuffer
,
262 IN OUT VOID
*StringBuffer
272 FormId - Form ID of the hyperlink
274 Prompt - Prompt of the hyperlink
276 FormBuffer - The form where this hyperlink adds to
278 StringBuffer - String buffer created for Prompt
282 EFI_SUCCESS - Hyperlink successfully created
289 IN UINT16 QuestionId
,
293 IN IFR_OPTION
*OptionsList
,
294 IN UINTN OptionCount
,
295 IN OUT VOID
*FormBuffer
,
296 IN OUT VOID
*StringBuffer
302 Create a one-of question with a set of options to choose from. The
303 OptionsList is a pointer to a null-terminated list of option descriptions.
307 QuestionId - Question ID of the one-of box
309 DataWidth - DataWidth of the one-of box
311 Prompt - Prompt of the one-of box
313 Help - Help of the one-of box
315 OptionsList - Each string in it is an option of the one-of box
317 OptionCount - Option string count
319 FormBuffer - The form where this one-of box adds to
321 StringBuffer - String buffer created for Prompt, Help and Option strings
325 EFI_DEVICE_ERROR - DataWidth > 2
327 EFI_SUCCESS - One-Of box successfully created.
334 IN UINT16 QuestionId
,
338 IN IFR_OPTION
*OptionsList
,
339 IN UINTN OptionCount
,
340 IN OUT VOID
*FormBuffer
,
341 IN OUT VOID
*StringBuffer
347 Create a one-of question with a set of options to choose from. The
348 OptionsList is a pointer to a null-terminated list of option descriptions.
352 QuestionId - Question ID of the ordered list
354 MaxEntries - MaxEntries of the ordered list
356 Prompt - Prompt of the ordered list
358 Help - Help of the ordered list
360 OptionsList - Each string in it is an option of the ordered list
362 OptionCount - Option string count
364 FormBuffer - The form where this ordered list adds to
366 StringBuffer - String buffer created for Prompt, Help and Option strings
370 EFI_SUCCESS - Ordered list successfully created.
377 IN UINT16 QuestionId
,
382 IN OUT VOID
*FormBuffer
,
383 IN OUT VOID
*StringBuffer
393 QuestionId - Question ID of the check box
395 DataWidth - DataWidth of the check box
397 Prompt - Prompt of the check box
399 Help - Help of the check box
401 Flags - Flags of the check box
403 FormBuffer - The form where this check box adds to
405 StringBuffer - String buffer created for Prompt and Help.
409 EFI_DEVICE_ERROR - DataWidth > 1
411 EFI_SUCCESS - Check box successfully created
418 IN UINT16 QuestionId
,
428 IN OUT VOID
*FormBuffer
,
429 IN OUT VOID
*StringBuffer
439 QuestionId - Question ID of the numeric
441 DataWidth - DataWidth of the numeric
443 Prompt - Prompt of the numeric
445 Help - Help of the numeric
447 Minimum - Minumun boundary of the numeric
449 Maximum - Maximum boundary of the numeric
451 Step - Step of the numeric
453 Default - Default value
455 Flags - Flags of the numeric
457 Key - Key of the numeric
459 FormBuffer - The form where this numeric adds to
461 StringBuffer - String buffer created for Prompt and Help.
465 EFI_DEVICE_ERROR - DataWidth > 2
467 EFI_SUCCESS - Numeric is successfully created
474 IN UINT16 QuestionId
,
482 IN OUT VOID
*FormBuffer
,
483 IN OUT VOID
*StringBuffer
493 QuestionId - Question ID of the string
495 DataWidth - DataWidth of the string
497 Prompt - Prompt of the string
499 Help - Help of the string
501 MinSize - Min size boundary of the string
503 MaxSize - Max size boundary of the string
505 Flags - Flags of the string
507 Key - Key of the string
509 FormBuffer - The form where this string adds to
511 StringBuffer - String buffer created for Prompt and Help.
515 EFI_SUCCESS - String successfully created.
522 ExtractDataFromHiiHandle (
523 IN EFI_HII_HANDLE HiiHandle
,
524 IN OUT UINT16
*ImageLength
,
525 OUT UINT8
*DefaultImage
,
532 Extract information pertaining to the HiiHandle
536 HiiHandle - Hii handle
538 ImageLength - For input, length of DefaultImage;
539 For output, length of actually required
541 DefaultImage - Image buffer prepared by caller
543 Guid - Guid information about the form
547 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
549 EFI_BUFFER_TOO_SMALL - DefualtImage has no enough ImageLength
551 EFI_SUCCESS - Successfully extract data from Hii database.
559 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
565 Finds HII handle for given pack GUID previously registered with the HII.
568 HiiProtocol - pointer to pointer to HII protocol interface.
569 If NULL, the interface will be found but not returned.
570 If it points to NULL, the interface will be found and
571 written back to the pointer that is pointed to.
572 Guid - The GUID of the pack that registered with the HII.
575 Handle to the HII pack previously registered by the memory driver.
581 CreateSubTitleOpCode (
582 IN STRING_REF StringToken
,
583 IN OUT VOID
*FormBuffer
589 Create a SubTitle opcode independent of string creation
590 This is used primarily by users who need to create just one particular valid op-code and the string
591 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
592 location to pre-defined forms in HII)
596 StringToken - StringToken of the subtitle
598 FormBuffer - Output of subtitle as a form
602 EFI_SUCCESS - Subtitle created to be a form
609 IN STRING_REF StringToken
,
610 IN STRING_REF StringTokenTwo
,
611 IN STRING_REF StringTokenThree
,
614 IN OUT VOID
*FormBuffer
620 Create a Text opcode independent of string creation
621 This is used primarily by users who need to create just one particular valid op-code and the string
622 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
623 location to pre-defined forms in HII)
627 StringToken - First string token of the text
629 StringTokenTwo - Second string token of the text
631 StringTokenThree - Help string token of the text
633 Flags - Flag of the text
635 Key - Key of the text
637 FormBuffer - Output of text as a form
641 EFI_SUCCESS - Text created to be a form
649 IN STRING_REF StringToken
,
650 IN STRING_REF StringTokenTwo
,
653 IN OUT VOID
*FormBuffer
659 Create a hyperlink opcode independent of string creation
660 This is used primarily by users who need to create just one particular valid op-code and the string
661 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
662 location to pre-defined forms in HII)
666 FormId - Form ID of the hyperlink
668 StringToken - Prompt string token of the hyperlink
670 StringTokenTwo - Help string token of the hyperlink
672 Flags - Flags of the hyperlink
674 Key - Key of the hyperlink
676 FormBuffer - Output of hyperlink as a form
680 EFI_SUCCESS - Hyperlink created to be a form
687 IN UINT16 QuestionId
,
689 IN STRING_REF PromptToken
,
690 IN STRING_REF HelpToken
,
691 IN IFR_OPTION
*OptionsList
,
692 IN UINTN OptionCount
,
693 IN OUT VOID
*FormBuffer
699 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
700 This is used primarily by users who need to create just one particular valid op-code and the string
701 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
702 location to pre-defined forms in HII)
704 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
705 has been filled in since this routine will not generate StringToken values.
709 QuestionId - Question ID of the one-of box
711 DataWidth - DataWidth of the one-of box
713 PromptToken - Prompt string token of the one-of box
715 HelpToken - Help string token of the one-of box
717 OptionsList - Each string in it is an option of the one-of box
719 OptionCount - Option string count
721 FormBuffer - Output of One-Of box as a form
725 EFI_SUCCESS - One-Of box created to be a form
727 EFI_DEVICE_ERROR - DataWidth > 2
733 CreateOrderedListOpCode (
734 IN UINT16 QuestionId
,
736 IN STRING_REF PromptToken
,
737 IN STRING_REF HelpToken
,
738 IN IFR_OPTION
*OptionsList
,
739 IN UINTN OptionCount
,
740 IN OUT VOID
*FormBuffer
746 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
747 This is used primarily by users who need to create just one particular valid op-code and the string
748 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
749 location to pre-defined forms in HII)
751 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
752 has been filled in since this routine will not generate StringToken values.
756 QuestionId - Question ID of the ordered list
758 MaxEntries - MaxEntries of the ordered list
760 PromptToken - Prompt string token of the ordered list
762 HelpToken - Help string token of the ordered list
764 OptionsList - Each string in it is an option of the ordered list
766 OptionCount - Option string count
768 FormBuffer - Output of ordered list as a form
772 EFI_SUCCESS - Ordered list created to be a form
778 CreateCheckBoxOpCode (
779 IN UINT16 QuestionId
,
781 IN STRING_REF PromptToken
,
782 IN STRING_REF HelpToken
,
785 IN OUT VOID
*FormBuffer
791 Create a checkbox opcode independent of string creation
792 This is used primarily by users who need to create just one particular valid op-code and the string
793 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
794 location to pre-defined forms in HII)
798 QuestionId - Question ID of the check box
800 DataWidth - DataWidth of the check box
802 PromptToken - Prompt string token of the check box
804 HelpToken - Help string token of the check box
806 Flags - Flags of the check box
808 Key - Key of the check box
810 FormBuffer - Output of the check box as a form
814 EFI_SUCCESS - Checkbox created to be a form
816 EFI_DEVICE_ERROR - DataWidth > 1
822 CreateNumericOpCode (
823 IN UINT16 QuestionId
,
825 IN STRING_REF PromptToken
,
826 IN STRING_REF HelpToken
,
833 IN OUT VOID
*FormBuffer
839 Create a numeric opcode independent of string creation
840 This is used primarily by users who need to create just one particular valid op-code and the string
841 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
842 location to pre-defined forms in HII)
846 QuestionId - Question ID of the numeric
848 DataWidth - DataWidth of the numeric
850 PromptToken - Prompt string token of the numeric
852 HelpToken - Help string token of the numeric
854 Minimum - Minumun boundary of the numeric
856 Maximum - Maximum boundary of the numeric
858 Step - Step of the numeric
860 Default - Default value of the numeric
862 Flags - Flags of the numeric
864 Key - Key of the numeric
866 FormBuffer - Output of the numeric as a form
870 EFI_SUCCESS - The numeric created to be a form.
872 EFI_DEVICE_ERROR - DataWidth > 2
879 IN UINT16 QuestionId
,
881 IN STRING_REF PromptToken
,
882 IN STRING_REF HelpToken
,
887 IN OUT VOID
*FormBuffer
893 Create a numeric opcode independent of string creation
894 This is used primarily by users who need to create just one particular valid op-code and the string
895 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
896 location to pre-defined forms in HII)
900 QuestionId - Question ID of the string
902 DataWidth - DataWidth of the string
904 PromptToken - Prompt token of the string
906 HelpToken - Help token of the string
908 MinSize - Min size boundary of the string
910 MaxSize - Max size boundary of the string
912 Flags - Flags of the string
914 Key - Key of the string
916 FormBuffer - Output of the string as a form
920 EFI_SUCCESS - String created to be a form.
925 #ifdef SUPPORT_DEPRECATED_IFRSUPPORTLIB_API
927 ValidateDataFromHiiHandle (
928 IN EFI_HII_HANDLE HiiHandle
,
935 Validate that the data associated with the HiiHandle in NVRAM is within
936 the reasonable parameters for that FormSet. Values for strings and passwords
937 are not verified due to their not having the equivalent of valid range settings.
941 HiiHandle - Handle of the HII database entry to query
943 Results - If return Status is EFI_SUCCESS, Results provides valid data
944 TRUE = NVRAM Data is within parameters
945 FALSE = NVRAM Data is NOT within parameters
949 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
951 EFI_SUCCESS - Data successfully validated
959 IN UINT16 LineNumber
,
961 IN OUT VOID
*FormBuffer
967 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
971 Title - Title of the banner
973 LineNumber - LineNumber of the banner
975 Alignment - Alignment of the banner
977 FormBuffer - Output of banner as a form
981 EFI_SUCCESS - Banner created to be a form.
988 IN UINTN NumberOfPackages
,
996 Assemble EFI_HII_PACKAGES according to the passed in packages.
1000 NumberOfPackages - Number of packages.
1001 GuidId - Package GUID.
1005 Pointer of EFI_HII_PACKAGES.
1011 EfiLibHiiVariablePackGetMap (
1012 IN EFI_HII_VARIABLE_PACK
*Pack
,
1013 OUT CHAR16
**Name
, OPTIONAL
1014 OUT EFI_GUID
**Guid
, OPTIONAL
1015 OUT UINT16
*Id
, OPTIONAL
1016 OUT VOID
**Var
, OPTIONAL
1017 OUT UINTN
*Size OPTIONAL
1021 Routine Description:
1023 Extracts a variable form a Pack.
1027 Pack - List of variables
1028 Name - Name of the variable/map
1029 Guid - GUID of the variable/map
1030 Var - Pointer to the variable/map
1031 Size - Size of the variable/map in bytes
1041 EfiLibHiiVariablePackListGetMapCnt (
1042 IN EFI_HII_VARIABLE_PACK_LIST
*List
1046 Routine Description:
1048 Finds a count of the variables/maps in the List.
1052 List - List of variables
1056 Number of Map in the variable pack list.
1061 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
1070 Routine Description:
1072 type definition for the callback to be
1073 used with EfiLibHiiVariablePackListForEachVar().
1077 Id - Variable/Map ID
1078 Name - Name of the variable/map
1079 Guid - GUID of the variable/map
1080 Var - Pointer to the variable/map
1081 Size - Size of the variable/map in bytes
1091 EfiLibHiiVariablePackListForEachVar (
1092 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1093 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
1097 Routine Description:
1099 Will iterate all variable/maps as appearing
1100 in List and for each, it will call the Callback.
1104 List - List of variables
1105 Callback - Routine to be called for each iterated variable.
1115 EfiLibHiiVariablePackListGetMapByIdx (
1117 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1118 OUT CHAR16
**Name
, OPTIONAL
1119 OUT EFI_GUID
**Guid
, OPTIONAL
1120 OUT UINT16
*Id
, OPTIONAL
1126 Routine Description:
1128 Finds a variable form List given
1129 the order number as appears in the List.
1133 Idx - The index of the variable/map to retrieve
1134 List - List of variables
1135 Name - Name of the variable/map
1136 Guid - GUID of the variable/map
1137 Var - Pointer to the variable/map
1138 Size - Size of the variable/map in bytes
1142 EFI_SUCCESS - Variable is found, OUT parameters are valid
1143 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1149 EfiLibHiiVariablePackListGetMapById (
1151 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1152 OUT CHAR16
**Name
, OPTIONAL
1153 OUT EFI_GUID
**Guid
, OPTIONAL
1159 Routine Description:
1161 Finds a variable form List given the
1162 order number as appears in the List.
1166 Id - The ID of the variable/map to retrieve
1167 List - List of variables
1168 Name - Name of the variable/map
1169 Guid - GUID of the variable/map
1170 Var - Pointer to the variable/map
1171 Size - Size of the variable/map in bytes
1175 EFI_SUCCESS - Variable is found, OUT parameters are valid
1176 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1182 EfiLibHiiVariablePackListGetMap (
1183 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1192 Routine Description:
1194 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
1198 List - List of variables
1199 Name - Name of the variable/map to be found
1200 Guid - GUID of the variable/map to be found
1201 Var - Pointer to the variable/map found
1202 Size - Size of the variable/map in bytes found
1206 EFI_SUCCESS - variable is found, OUT parameters are valid
1207 EFI_NOT_FOUND - variable is not found, OUT parameters are not valid
1213 EfiLibHiiVariableRetrieveFromNv (
1221 Routine Description:
1222 Finds out if a variable of specific Name/Guid/Size exists in NV.
1223 If it does, it will retrieve it into the Var.
1226 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1227 Var - Variable will be retrieved into buffer pointed by this pointer.
1228 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
1230 EFI_SUCCESS - The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
1231 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1232 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1238 //// Variable override support.
1242 EfiLibHiiVariableOverrideIfSuffix (
1251 Routine Description:
1252 Overrrides the variable with NV data if found.
1253 But it only does it if the Name ends with specified Suffix.
1254 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
1255 the Suffix matches the end of Name, so the variable will be loaded from NV
1256 provided the variable exists and the GUID and Size matches.
1259 Suffix - Suffix the Name should end with.
1260 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1261 Var - Variable will be retrieved into this buffer.
1262 Caller is responsible for providing storage of exactly Size size in bytes.
1264 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1265 EFI_INVALID_PARAMETER - The name of the variable does not end with <Suffix>.
1266 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1267 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1273 EfiLibHiiVariableOverrideBySuffix (
1282 Routine Description:
1283 Overrrides the variable with NV data if found.
1284 But it only does it if the NV contains the same variable with Name is appended with Suffix.
1285 For example, if Suffix="MyOverride" and the Name="XyzSetup",
1286 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
1287 will be loaded from NV provided the variable exists and the GUID and Size matches.
1290 Suffix - Suffix the variable will be appended with.
1291 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1292 Var - Variable will be retrieved into this buffer.
1293 Caller is responsible for providing storage of exactly Size size in bytes.
1296 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1297 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1298 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.