2 The file contain all library function for Ifr Operations.
4 Copyright (c) 2006 - 2007, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #ifndef __IFRSUPPORTLIBRARY_H__
16 #define __IFRSUPPORTLIBRARY_H__
18 #define DEFAULT_FORM_BUFFER_SIZE 0xFFFF
19 #define DEFAULT_STRING_BUFFER_SIZE 0xFFFF
23 CHAR16
*OptionString
; // Passed in string to generate a token for in a truly dynamic form creation
24 STRING_REF StringToken
; // This is used when creating a single op-code without generating a StringToken (have one already)
39 Determine what is the current language setting
43 Lang - Pointer of system language
54 IN VOID
*StringBuffer
,
57 IN OUT STRING_REF
*StringToken
63 Add a string to the incoming buffer and return the token and offset data
67 StringBuffer - The incoming buffer
69 Language - Currrent language
71 String - The string to be added
73 StringToken - The index where the string placed
77 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
79 EFI_SUCCESS - String successfully added to the incoming buffer
87 IN OUT VOID
*OpCodeData
93 Add op-code data to the FormBuffer
97 FormBuffer - Form buffer to be inserted to
99 OpCodeData - Op-code data to be inserted
103 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
105 EFI_SUCCESS - Op-code data successfully inserted
112 IN CHAR16
*FormSetTitle
,
116 IN OUT VOID
**FormBuffer
,
117 IN OUT VOID
**StringBuffer
127 FormSetTitle - Title of formset
129 Guid - Guid of formset
131 Class - Class of formset
133 SubClass - Sub class of formset
135 FormBuffer - Pointer of the formset created
137 StringBuffer - Pointer of FormSetTitile string created
141 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
143 EFI_SUCCESS - Formset successfully created
150 IN CHAR16
*FormTitle
,
152 IN OUT VOID
*FormBuffer
,
153 IN OUT VOID
*StringBuffer
163 FormTitle - Title of the form
165 FormId - Id of the form
167 FormBuffer - Pointer of the form created
169 StringBuffer - Pointer of FormTitil string created
173 EFI_SUCCESS - Form successfully created
181 IN OUT VOID
*FormBuffer
,
182 IN OUT VOID
*StringBuffer
192 SubTitle - Sub title to be created
194 FormBuffer - Where this subtitle to add to
196 StringBuffer - String buffer created for subtitle
200 EFI_SUCCESS - Subtitle successfully created
212 IN OUT VOID
*FormBuffer
,
213 IN OUT VOID
*StringBuffer
219 Create a line of text
223 String - First string of the text
225 String2 - Second string of the text
227 String3 - Help string of the text
229 Flags - Flag of the text
231 Key - Key of the text
233 FormBuffer - The form where this text adds to
235 StringBuffer - String buffer created for String, String2 and String3
239 EFI_SUCCESS - Text successfully created
248 IN OUT VOID
*FormBuffer
,
249 IN OUT VOID
*StringBuffer
259 FormId - Form ID of the hyperlink
261 Prompt - Prompt of the hyperlink
263 FormBuffer - The form where this hyperlink adds to
265 StringBuffer - String buffer created for Prompt
269 EFI_SUCCESS - Hyperlink successfully created
276 IN UINT16 QuestionId
,
280 IN IFR_OPTION
*OptionsList
,
281 IN UINTN OptionCount
,
282 IN OUT VOID
*FormBuffer
,
283 IN OUT VOID
*StringBuffer
289 Create a one-of question with a set of options to choose from. The
290 OptionsList is a pointer to a null-terminated list of option descriptions.
294 QuestionId - Question ID of the one-of box
296 DataWidth - DataWidth of the one-of box
298 Prompt - Prompt of the one-of box
300 Help - Help of the one-of box
302 OptionsList - Each string in it is an option of the one-of box
304 OptionCount - Option string count
306 FormBuffer - The form where this one-of box adds to
308 StringBuffer - String buffer created for Prompt, Help and Option strings
312 EFI_DEVICE_ERROR - DataWidth > 2
314 EFI_SUCCESS - One-Of box successfully created.
321 IN UINT16 QuestionId
,
325 IN IFR_OPTION
*OptionsList
,
326 IN UINTN OptionCount
,
327 IN OUT VOID
*FormBuffer
,
328 IN OUT VOID
*StringBuffer
334 Create a one-of question with a set of options to choose from. The
335 OptionsList is a pointer to a null-terminated list of option descriptions.
339 QuestionId - Question ID of the ordered list
341 MaxEntries - MaxEntries of the ordered list
343 Prompt - Prompt of the ordered list
345 Help - Help of the ordered list
347 OptionsList - Each string in it is an option of the ordered list
349 OptionCount - Option string count
351 FormBuffer - The form where this ordered list adds to
353 StringBuffer - String buffer created for Prompt, Help and Option strings
357 EFI_SUCCESS - Ordered list successfully created.
364 IN UINT16 QuestionId
,
369 IN OUT VOID
*FormBuffer
,
370 IN OUT VOID
*StringBuffer
380 QuestionId - Question ID of the check box
382 DataWidth - DataWidth of the check box
384 Prompt - Prompt of the check box
386 Help - Help of the check box
388 Flags - Flags of the check box
390 FormBuffer - The form where this check box adds to
392 StringBuffer - String buffer created for Prompt and Help.
396 EFI_DEVICE_ERROR - DataWidth > 1
398 EFI_SUCCESS - Check box successfully created
405 IN UINT16 QuestionId
,
415 IN OUT VOID
*FormBuffer
,
416 IN OUT VOID
*StringBuffer
426 QuestionId - Question ID of the numeric
428 DataWidth - DataWidth of the numeric
430 Prompt - Prompt of the numeric
432 Help - Help of the numeric
434 Minimum - Minumun boundary of the numeric
436 Maximum - Maximum boundary of the numeric
438 Step - Step of the numeric
440 Default - Default value
442 Flags - Flags of the numeric
444 Key - Key of the numeric
446 FormBuffer - The form where this numeric adds to
448 StringBuffer - String buffer created for Prompt and Help.
452 EFI_DEVICE_ERROR - DataWidth > 2
454 EFI_SUCCESS - Numeric is successfully created
461 IN UINT16 QuestionId
,
469 IN OUT VOID
*FormBuffer
,
470 IN OUT VOID
*StringBuffer
480 QuestionId - Question ID of the string
482 DataWidth - DataWidth of the string
484 Prompt - Prompt of the string
486 Help - Help of the string
488 MinSize - Min size boundary of the string
490 MaxSize - Max size boundary of the string
492 Flags - Flags of the string
494 Key - Key of the string
496 FormBuffer - The form where this string adds to
498 StringBuffer - String buffer created for Prompt and Help.
502 EFI_SUCCESS - String successfully created.
508 ExtractDataFromHiiHandle (
509 IN EFI_HII_HANDLE HiiHandle
,
510 IN OUT UINT16
*ImageLength
,
511 OUT UINT8
*DefaultImage
,
518 Extract information pertaining to the HiiHandle
522 HiiHandle - Hii handle
524 ImageLength - For input, length of DefaultImage;
525 For output, length of actually required
527 DefaultImage - Image buffer prepared by caller
529 Guid - Guid information about the form
533 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
535 EFI_BUFFER_TOO_SMALL - DefualtImage has no enough ImageLength
537 EFI_SUCCESS - Successfully extract data from Hii database.
545 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
551 Finds HII handle for given pack GUID previously registered with the HII.
554 HiiProtocol - pointer to pointer to HII protocol interface.
555 If NULL, the interface will be found but not returned.
556 If it points to NULL, the interface will be found and
557 written back to the pointer that is pointed to.
558 Guid - The GUID of the pack that registered with the HII.
561 Handle to the HII pack previously registered by the memory driver.
567 CreateSubTitleOpCode (
568 IN STRING_REF StringToken
,
569 IN OUT VOID
*FormBuffer
575 Create a SubTitle opcode independent of string creation
576 This is used primarily by users who need to create just one particular valid op-code and the string
577 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
578 location to pre-defined forms in HII)
582 StringToken - StringToken of the subtitle
584 FormBuffer - Output of subtitle as a form
588 EFI_SUCCESS - Subtitle created to be a form
595 IN STRING_REF StringToken
,
596 IN STRING_REF StringTokenTwo
,
597 IN STRING_REF StringTokenThree
,
600 IN OUT VOID
*FormBuffer
606 Create a Text opcode independent of string creation
607 This is used primarily by users who need to create just one particular valid op-code and the string
608 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
609 location to pre-defined forms in HII)
613 StringToken - First string token of the text
615 StringTokenTwo - Second string token of the text
617 StringTokenThree - Help string token of the text
619 Flags - Flag of the text
621 Key - Key of the text
623 FormBuffer - Output of text as a form
627 EFI_SUCCESS - Text created to be a form
635 IN STRING_REF StringToken
,
636 IN STRING_REF StringTokenTwo
,
639 IN OUT VOID
*FormBuffer
645 Create a hyperlink opcode independent of string creation
646 This is used primarily by users who need to create just one particular valid op-code and the string
647 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
648 location to pre-defined forms in HII)
652 FormId - Form ID of the hyperlink
654 StringToken - Prompt string token of the hyperlink
656 StringTokenTwo - Help string token of the hyperlink
658 Flags - Flags of the hyperlink
660 Key - Key of the hyperlink
662 FormBuffer - Output of hyperlink as a form
666 EFI_SUCCESS - Hyperlink created to be a form
673 IN UINT16 QuestionId
,
675 IN STRING_REF PromptToken
,
676 IN STRING_REF HelpToken
,
677 IN IFR_OPTION
*OptionsList
,
678 IN UINTN OptionCount
,
679 IN OUT VOID
*FormBuffer
685 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
686 This is used primarily by users who need to create just one particular valid op-code and the string
687 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
688 location to pre-defined forms in HII)
690 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
691 has been filled in since this routine will not generate StringToken values.
695 QuestionId - Question ID of the one-of box
697 DataWidth - DataWidth of the one-of box
699 PromptToken - Prompt string token of the one-of box
701 HelpToken - Help string token of the one-of box
703 OptionsList - Each string in it is an option of the one-of box
705 OptionCount - Option string count
707 FormBuffer - Output of One-Of box as a form
711 EFI_SUCCESS - One-Of box created to be a form
713 EFI_DEVICE_ERROR - DataWidth > 2
719 CreateOrderedListOpCode (
720 IN UINT16 QuestionId
,
722 IN STRING_REF PromptToken
,
723 IN STRING_REF HelpToken
,
724 IN IFR_OPTION
*OptionsList
,
725 IN UINTN OptionCount
,
726 IN OUT VOID
*FormBuffer
732 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
733 This is used primarily by users who need to create just one particular valid op-code and the string
734 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
735 location to pre-defined forms in HII)
737 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
738 has been filled in since this routine will not generate StringToken values.
742 QuestionId - Question ID of the ordered list
744 MaxEntries - MaxEntries of the ordered list
746 PromptToken - Prompt string token of the ordered list
748 HelpToken - Help string token of the ordered list
750 OptionsList - Each string in it is an option of the ordered list
752 OptionCount - Option string count
754 FormBuffer - Output of ordered list as a form
758 EFI_SUCCESS - Ordered list created to be a form
764 CreateCheckBoxOpCode (
765 IN UINT16 QuestionId
,
767 IN STRING_REF PromptToken
,
768 IN STRING_REF HelpToken
,
771 IN OUT VOID
*FormBuffer
777 Create a checkbox opcode independent of string creation
778 This is used primarily by users who need to create just one particular valid op-code and the string
779 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
780 location to pre-defined forms in HII)
784 QuestionId - Question ID of the check box
786 DataWidth - DataWidth of the check box
788 PromptToken - Prompt string token of the check box
790 HelpToken - Help string token of the check box
792 Flags - Flags of the check box
794 Key - Key of the check box
796 FormBuffer - Output of the check box as a form
800 EFI_SUCCESS - Checkbox created to be a form
802 EFI_DEVICE_ERROR - DataWidth > 1
808 CreateNumericOpCode (
809 IN UINT16 QuestionId
,
811 IN STRING_REF PromptToken
,
812 IN STRING_REF HelpToken
,
819 IN OUT VOID
*FormBuffer
825 Create a numeric opcode independent of string creation
826 This is used primarily by users who need to create just one particular valid op-code and the string
827 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
828 location to pre-defined forms in HII)
832 QuestionId - Question ID of the numeric
834 DataWidth - DataWidth of the numeric
836 PromptToken - Prompt string token of the numeric
838 HelpToken - Help string token of the numeric
840 Minimum - Minumun boundary of the numeric
842 Maximum - Maximum boundary of the numeric
844 Step - Step of the numeric
846 Default - Default value of the numeric
848 Flags - Flags of the numeric
850 Key - Key of the numeric
852 FormBuffer - Output of the numeric as a form
856 EFI_SUCCESS - The numeric created to be a form.
858 EFI_DEVICE_ERROR - DataWidth > 2
865 IN UINT16 QuestionId
,
867 IN STRING_REF PromptToken
,
868 IN STRING_REF HelpToken
,
873 IN OUT VOID
*FormBuffer
879 Create a numeric opcode independent of string creation
880 This is used primarily by users who need to create just one particular valid op-code and the string
881 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
882 location to pre-defined forms in HII)
886 QuestionId - Question ID of the string
888 DataWidth - DataWidth of the string
890 PromptToken - Prompt token of the string
892 HelpToken - Help token of the string
894 MinSize - Min size boundary of the string
896 MaxSize - Max size boundary of the string
898 Flags - Flags of the string
900 Key - Key of the string
902 FormBuffer - Output of the string as a form
906 EFI_SUCCESS - String created to be a form.
912 ValidateDataFromHiiHandle (
913 IN EFI_HII_HANDLE HiiHandle
,
920 Validate that the data associated with the HiiHandle in NVRAM is within
921 the reasonable parameters for that FormSet. Values for strings and passwords
922 are not verified due to their not having the equivalent of valid range settings.
926 HiiHandle - Handle of the HII database entry to query
928 Results - If return Status is EFI_SUCCESS, Results provides valid data
929 TRUE = NVRAM Data is within parameters
930 FALSE = NVRAM Data is NOT within parameters
934 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
936 EFI_SUCCESS - Data successfully validated
943 IN UINT16 LineNumber
,
945 IN OUT VOID
*FormBuffer
951 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
955 Title - Title of the banner
957 LineNumber - LineNumber of the banner
959 Alignment - Alignment of the banner
961 FormBuffer - Output of banner as a form
965 EFI_SUCCESS - Banner created to be a form.
971 EfiLibHiiVariablePackGetMap (
972 IN EFI_HII_VARIABLE_PACK
*Pack
,
973 OUT CHAR16
**Name
, OPTIONAL
974 OUT EFI_GUID
**Guid
, OPTIONAL
975 OUT UINT16
*Id
, OPTIONAL
976 OUT VOID
**Var
, OPTIONAL
977 OUT UINTN
*Size OPTIONAL
983 Extracts a variable form a Pack.
987 Pack - List of variables
988 Name - Name of the variable/map
989 Guid - GUID of the variable/map
990 Var - Pointer to the variable/map
991 Size - Size of the variable/map in bytes
1001 EfiLibHiiVariablePackListGetMapCnt (
1002 IN EFI_HII_VARIABLE_PACK_LIST
*List
1006 Routine Description:
1008 Finds a count of the variables/maps in the List.
1012 List - List of variables
1016 Number of Map in the variable pack list.
1021 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
1030 Routine Description:
1032 type definition for the callback to be
1033 used with EfiLibHiiVariablePackListForEachVar().
1037 Id - Variable/Map ID
1038 Name - Name of the variable/map
1039 Guid - GUID of the variable/map
1040 Var - Pointer to the variable/map
1041 Size - Size of the variable/map in bytes
1051 EfiLibHiiVariablePackListForEachVar (
1052 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1053 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
1057 Routine Description:
1059 Will iterate all variable/maps as appearing
1060 in List and for each, it will call the Callback.
1064 List - List of variables
1065 Callback - Routine to be called for each iterated variable.
1075 EfiLibHiiVariablePackListGetMapByIdx (
1077 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1078 OUT CHAR16
**Name
, OPTIONAL
1079 OUT EFI_GUID
**Guid
, OPTIONAL
1080 OUT UINT16
*Id
, OPTIONAL
1086 Routine Description:
1088 Finds a variable form List given
1089 the order number as appears in the List.
1093 Idx - The index of the variable/map to retrieve
1094 List - List of variables
1095 Name - Name of the variable/map
1096 Guid - GUID of the variable/map
1097 Var - Pointer to the variable/map
1098 Size - Size of the variable/map in bytes
1102 EFI_SUCCESS - Variable is found, OUT parameters are valid
1103 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1109 EfiLibHiiVariablePackListGetMapById (
1111 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1112 OUT CHAR16
**Name
, OPTIONAL
1113 OUT EFI_GUID
**Guid
, OPTIONAL
1119 Routine Description:
1121 Finds a variable form List given the
1122 order number as appears in the List.
1126 Id - The ID of the variable/map to retrieve
1127 List - List of variables
1128 Name - Name of the variable/map
1129 Guid - GUID of the variable/map
1130 Var - Pointer to the variable/map
1131 Size - Size of the variable/map in bytes
1135 EFI_SUCCESS - Variable is found, OUT parameters are valid
1136 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1142 EfiLibHiiVariablePackListGetMap (
1143 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1152 Routine Description:
1154 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
1158 List - List of variables
1159 Name - Name of the variable/map to be found
1160 Guid - GUID of the variable/map to be found
1161 Var - Pointer to the variable/map found
1162 Size - Size of the variable/map in bytes found
1166 EFI_SUCCESS - variable is found, OUT parameters are valid
1167 EFI_NOT_FOUND - variable is not found, OUT parameters are not valid
1173 EfiLibHiiVariableRetrieveFromNv (
1181 Routine Description:
1182 Finds out if a variable of specific Name/Guid/Size exists in NV.
1183 If it does, it will retrieve it into the Var.
1186 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1187 Var - Variable will be retrieved into buffer pointed by this pointer.
1188 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
1190 EFI_SUCCESS - The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
1191 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1192 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1198 //// Variable override support.
1202 EfiLibHiiVariableOverrideIfSuffix (
1211 Routine Description:
1212 Overrrides the variable with NV data if found.
1213 But it only does it if the Name ends with specified Suffix.
1214 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
1215 the Suffix matches the end of Name, so the variable will be loaded from NV
1216 provided the variable exists and the GUID and Size matches.
1219 Suffix - Suffix the Name should end with.
1220 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1221 Var - Variable will be retrieved into this buffer.
1222 Caller is responsible for providing storage of exactly Size size in bytes.
1224 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1225 EFI_INVALID_PARAMETER - The name of the variable does not end with <Suffix>.
1226 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1227 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1233 EfiLibHiiVariableOverrideBySuffix (
1242 Routine Description:
1243 Overrrides the variable with NV data if found.
1244 But it only does it if the NV contains the same variable with Name is appended with Suffix.
1245 For example, if Suffix="MyOverride" and the Name="XyzSetup",
1246 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
1247 will be loaded from NV provided the variable exists and the GUID and Size matches.
1250 Suffix - Suffix the variable will be appended with.
1251 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1252 Var - Variable will be retrieved into this buffer.
1253 Caller is responsible for providing storage of exactly Size size in bytes.
1256 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1257 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1258 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.