3 Copyright (c) 2006, 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.
18 The file contain all library function for Ifr Operations.
22 #ifndef _IFRSUPPORTLIBRARY_H
23 #define _IFRSUPPORTLIBRARY_H
25 #define DEFAULT_FORM_BUFFER_SIZE 0xFFFF
26 #define DEFAULT_STRING_BUFFER_SIZE 0xFFFF
30 CHAR16
*OptionString
; // Passed in string to generate a token for in a truly dynamic form creation
31 STRING_REF StringToken
; // This is used when creating a single op-code without generating a StringToken (have one already)
46 Determine what is the current language setting
50 Lang - Pointer of system language
61 IN VOID
*StringBuffer
,
64 IN OUT STRING_REF
*StringToken
70 Add a string to the incoming buffer and return the token and offset data
74 StringBuffer - The incoming buffer
76 Language - Currrent language
78 String - The string to be added
80 StringToken - The index where the string placed
84 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
86 EFI_SUCCESS - String successfully added to the incoming buffer
94 IN OUT VOID
*OpCodeData
100 Add op-code data to the FormBuffer
104 FormBuffer - Form buffer to be inserted to
106 OpCodeData - Op-code data to be inserted
110 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
112 EFI_SUCCESS - Op-code data successfully inserted
119 IN CHAR16
*FormSetTitle
,
123 IN OUT VOID
**FormBuffer
,
124 IN OUT VOID
**StringBuffer
134 FormSetTitle - Title of formset
136 Guid - Guid of formset
138 Class - Class of formset
140 SubClass - Sub class of formset
142 FormBuffer - Pointer of the formset created
144 StringBuffer - Pointer of FormSetTitile string created
148 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
150 EFI_SUCCESS - Formset successfully created
157 IN CHAR16
*FormTitle
,
159 IN OUT VOID
*FormBuffer
,
160 IN OUT VOID
*StringBuffer
170 FormTitle - Title of the form
172 FormId - Id of the form
174 FormBuffer - Pointer of the form created
176 StringBuffer - Pointer of FormTitil string created
180 EFI_SUCCESS - Form successfully created
188 IN OUT VOID
*FormBuffer
,
189 IN OUT VOID
*StringBuffer
199 SubTitle - Sub title to be created
201 FormBuffer - Where this subtitle to add to
203 StringBuffer - String buffer created for subtitle
207 EFI_SUCCESS - Subtitle successfully created
219 IN OUT VOID
*FormBuffer
,
220 IN OUT VOID
*StringBuffer
226 Create a line of text
230 String - First string of the text
232 String2 - Second string of the text
234 String3 - Help string of the text
236 Flags - Flag of the text
238 Key - Key of the text
240 FormBuffer - The form where this text adds to
242 StringBuffer - String buffer created for String, String2 and String3
246 EFI_SUCCESS - Text successfully created
255 IN OUT VOID
*FormBuffer
,
256 IN OUT VOID
*StringBuffer
266 FormId - Form ID of the hyperlink
268 Prompt - Prompt of the hyperlink
270 FormBuffer - The form where this hyperlink adds to
272 StringBuffer - String buffer created for Prompt
276 EFI_SUCCESS - Hyperlink successfully created
283 IN UINT16 QuestionId
,
287 IN IFR_OPTION
*OptionsList
,
288 IN UINTN OptionCount
,
289 IN OUT VOID
*FormBuffer
,
290 IN OUT VOID
*StringBuffer
296 Create a one-of question with a set of options to choose from. The
297 OptionsList is a pointer to a null-terminated list of option descriptions.
301 QuestionId - Question ID of the one-of box
303 DataWidth - DataWidth of the one-of box
305 Prompt - Prompt of the one-of box
307 Help - Help of the one-of box
309 OptionsList - Each string in it is an option of the one-of box
311 OptionCount - Option string count
313 FormBuffer - The form where this one-of box adds to
315 StringBuffer - String buffer created for Prompt, Help and Option strings
319 EFI_DEVICE_ERROR - DataWidth > 2
321 EFI_SUCCESS - One-Of box successfully created.
328 IN UINT16 QuestionId
,
332 IN IFR_OPTION
*OptionsList
,
333 IN UINTN OptionCount
,
334 IN OUT VOID
*FormBuffer
,
335 IN OUT VOID
*StringBuffer
341 Create a one-of question with a set of options to choose from. The
342 OptionsList is a pointer to a null-terminated list of option descriptions.
346 QuestionId - Question ID of the ordered list
348 MaxEntries - MaxEntries of the ordered list
350 Prompt - Prompt of the ordered list
352 Help - Help of the ordered list
354 OptionsList - Each string in it is an option of the ordered list
356 OptionCount - Option string count
358 FormBuffer - The form where this ordered list adds to
360 StringBuffer - String buffer created for Prompt, Help and Option strings
364 EFI_SUCCESS - Ordered list successfully created.
371 IN UINT16 QuestionId
,
376 IN OUT VOID
*FormBuffer
,
377 IN OUT VOID
*StringBuffer
387 QuestionId - Question ID of the check box
389 DataWidth - DataWidth of the check box
391 Prompt - Prompt of the check box
393 Help - Help of the check box
395 Flags - Flags of the check box
397 FormBuffer - The form where this check box adds to
399 StringBuffer - String buffer created for Prompt and Help.
403 EFI_DEVICE_ERROR - DataWidth > 1
405 EFI_SUCCESS - Check box successfully created
412 IN UINT16 QuestionId
,
422 IN OUT VOID
*FormBuffer
,
423 IN OUT VOID
*StringBuffer
433 QuestionId - Question ID of the numeric
435 DataWidth - DataWidth of the numeric
437 Prompt - Prompt of the numeric
439 Help - Help of the numeric
441 Minimum - Minumun boundary of the numeric
443 Maximum - Maximum boundary of the numeric
445 Step - Step of the numeric
447 Default - Default value
449 Flags - Flags of the numeric
451 Key - Key of the numeric
453 FormBuffer - The form where this numeric adds to
455 StringBuffer - String buffer created for Prompt and Help.
459 EFI_DEVICE_ERROR - DataWidth > 2
461 EFI_SUCCESS - Numeric is successfully created
468 IN UINT16 QuestionId
,
476 IN OUT VOID
*FormBuffer
,
477 IN OUT VOID
*StringBuffer
487 QuestionId - Question ID of the string
489 DataWidth - DataWidth of the string
491 Prompt - Prompt of the string
493 Help - Help of the string
495 MinSize - Min size boundary of the string
497 MaxSize - Max size boundary of the string
499 Flags - Flags of the string
501 Key - Key of the string
503 FormBuffer - The form where this string adds to
505 StringBuffer - String buffer created for Prompt and Help.
509 EFI_SUCCESS - String successfully created.
515 ExtractDataFromHiiHandle (
516 IN EFI_HII_HANDLE HiiHandle
,
517 IN OUT UINT16
*ImageLength
,
518 OUT UINT8
*DefaultImage
,
525 Extract information pertaining to the HiiHandle
529 HiiHandle - Hii handle
531 ImageLength - For input, length of DefaultImage;
532 For output, length of actually required
534 DefaultImage - Image buffer prepared by caller
536 Guid - Guid information about the form
540 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
542 EFI_BUFFER_TOO_SMALL - DefualtImage has no enough ImageLength
544 EFI_SUCCESS - Successfully extract data from Hii database.
552 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
558 Finds HII handle for given pack GUID previously registered with the HII.
561 HiiProtocol - pointer to pointer to HII protocol interface.
562 If NULL, the interface will be found but not returned.
563 If it points to NULL, the interface will be found and
564 written back to the pointer that is pointed to.
565 Guid - The GUID of the pack that registered with the HII.
568 Handle to the HII pack previously registered by the memory driver.
574 CreateSubTitleOpCode (
575 IN STRING_REF StringToken
,
576 IN OUT VOID
*FormBuffer
582 Create a SubTitle opcode independent of string creation
583 This is used primarily by users who need to create just one particular valid op-code and the string
584 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
585 location to pre-defined forms in HII)
589 StringToken - StringToken of the subtitle
591 FormBuffer - Output of subtitle as a form
595 EFI_SUCCESS - Subtitle created to be a form
602 IN STRING_REF StringToken
,
603 IN STRING_REF StringTokenTwo
,
604 IN STRING_REF StringTokenThree
,
607 IN OUT VOID
*FormBuffer
613 Create a Text opcode independent of string creation
614 This is used primarily by users who need to create just one particular valid op-code and the string
615 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
616 location to pre-defined forms in HII)
620 StringToken - First string token of the text
622 StringTokenTwo - Second string token of the text
624 StringTokenThree - Help string token of the text
626 Flags - Flag of the text
628 Key - Key of the text
630 FormBuffer - Output of text as a form
634 EFI_SUCCESS - Text created to be a form
642 IN STRING_REF StringToken
,
643 IN STRING_REF StringTokenTwo
,
646 IN OUT VOID
*FormBuffer
652 Create a hyperlink opcode independent of string creation
653 This is used primarily by users who need to create just one particular valid op-code and the string
654 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
655 location to pre-defined forms in HII)
659 FormId - Form ID of the hyperlink
661 StringToken - Prompt string token of the hyperlink
663 StringTokenTwo - Help string token of the hyperlink
665 Flags - Flags of the hyperlink
667 Key - Key of the hyperlink
669 FormBuffer - Output of hyperlink as a form
673 EFI_SUCCESS - Hyperlink created to be a form
680 IN UINT16 QuestionId
,
682 IN STRING_REF PromptToken
,
683 IN STRING_REF HelpToken
,
684 IN IFR_OPTION
*OptionsList
,
685 IN UINTN OptionCount
,
686 IN OUT VOID
*FormBuffer
692 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
693 This is used primarily by users who need to create just one particular valid op-code and the string
694 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
695 location to pre-defined forms in HII)
697 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
698 has been filled in since this routine will not generate StringToken values.
702 QuestionId - Question ID of the one-of box
704 DataWidth - DataWidth of the one-of box
706 PromptToken - Prompt string token of the one-of box
708 HelpToken - Help string token of the one-of box
710 OptionsList - Each string in it is an option of the one-of box
712 OptionCount - Option string count
714 FormBuffer - Output of One-Of box as a form
718 EFI_SUCCESS - One-Of box created to be a form
720 EFI_DEVICE_ERROR - DataWidth > 2
726 CreateOrderedListOpCode (
727 IN UINT16 QuestionId
,
729 IN STRING_REF PromptToken
,
730 IN STRING_REF HelpToken
,
731 IN IFR_OPTION
*OptionsList
,
732 IN UINTN OptionCount
,
733 IN OUT VOID
*FormBuffer
739 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
740 This is used primarily by users who need to create just one particular valid op-code and the string
741 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
742 location to pre-defined forms in HII)
744 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
745 has been filled in since this routine will not generate StringToken values.
749 QuestionId - Question ID of the ordered list
751 MaxEntries - MaxEntries of the ordered list
753 PromptToken - Prompt string token of the ordered list
755 HelpToken - Help string token of the ordered list
757 OptionsList - Each string in it is an option of the ordered list
759 OptionCount - Option string count
761 FormBuffer - Output of ordered list as a form
765 EFI_SUCCESS - Ordered list created to be a form
771 CreateCheckBoxOpCode (
772 IN UINT16 QuestionId
,
774 IN STRING_REF PromptToken
,
775 IN STRING_REF HelpToken
,
778 IN OUT VOID
*FormBuffer
784 Create a checkbox opcode independent of string creation
785 This is used primarily by users who need to create just one particular valid op-code and the string
786 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
787 location to pre-defined forms in HII)
791 QuestionId - Question ID of the check box
793 DataWidth - DataWidth of the check box
795 PromptToken - Prompt string token of the check box
797 HelpToken - Help string token of the check box
799 Flags - Flags of the check box
801 Key - Key of the check box
803 FormBuffer - Output of the check box as a form
807 EFI_SUCCESS - Checkbox created to be a form
809 EFI_DEVICE_ERROR - DataWidth > 1
815 CreateNumericOpCode (
816 IN UINT16 QuestionId
,
818 IN STRING_REF PromptToken
,
819 IN STRING_REF HelpToken
,
826 IN OUT VOID
*FormBuffer
832 Create a numeric opcode independent of string creation
833 This is used primarily by users who need to create just one particular valid op-code and the string
834 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
835 location to pre-defined forms in HII)
839 QuestionId - Question ID of the numeric
841 DataWidth - DataWidth of the numeric
843 PromptToken - Prompt string token of the numeric
845 HelpToken - Help string token of the numeric
847 Minimum - Minumun boundary of the numeric
849 Maximum - Maximum boundary of the numeric
851 Step - Step of the numeric
853 Default - Default value of the numeric
855 Flags - Flags of the numeric
857 Key - Key of the numeric
859 FormBuffer - Output of the numeric as a form
863 EFI_SUCCESS - The numeric created to be a form.
865 EFI_DEVICE_ERROR - DataWidth > 2
872 IN UINT16 QuestionId
,
874 IN STRING_REF PromptToken
,
875 IN STRING_REF HelpToken
,
880 IN OUT VOID
*FormBuffer
886 Create a numeric opcode independent of string creation
887 This is used primarily by users who need to create just one particular valid op-code and the string
888 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
889 location to pre-defined forms in HII)
893 QuestionId - Question ID of the string
895 DataWidth - DataWidth of the string
897 PromptToken - Prompt token of the string
899 HelpToken - Help token of the string
901 MinSize - Min size boundary of the string
903 MaxSize - Max size boundary of the string
905 Flags - Flags of the string
907 Key - Key of the string
909 FormBuffer - Output of the string as a form
913 EFI_SUCCESS - String created to be a form.
919 ValidateDataFromHiiHandle (
920 IN EFI_HII_HANDLE HiiHandle
,
927 Validate that the data associated with the HiiHandle in NVRAM is within
928 the reasonable parameters for that FormSet. Values for strings and passwords
929 are not verified due to their not having the equivalent of valid range settings.
933 HiiHandle - Handle of the HII database entry to query
935 Results - If return Status is EFI_SUCCESS, Results provides valid data
936 TRUE = NVRAM Data is within parameters
937 FALSE = NVRAM Data is NOT within parameters
941 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
943 EFI_SUCCESS - Data successfully validated
950 IN UINT16 LineNumber
,
952 IN OUT VOID
*FormBuffer
958 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
962 Title - Title of the banner
964 LineNumber - LineNumber of the banner
966 Alignment - Alignment of the banner
968 FormBuffer - Output of banner as a form
972 EFI_SUCCESS - Banner created to be a form.
978 EfiLibHiiVariablePackGetMap (
979 IN EFI_HII_VARIABLE_PACK
*Pack
,
980 OUT CHAR16
**Name
, OPTIONAL
981 OUT EFI_GUID
**Guid
, OPTIONAL
982 OUT UINT16
*Id
, OPTIONAL
983 OUT VOID
**Var
, OPTIONAL
984 OUT UINTN
*Size OPTIONAL
990 Extracts a variable form a Pack.
994 Pack - List of variables
995 Name - Name of the variable/map
996 Guid - GUID of the variable/map
997 Var - Pointer to the variable/map
998 Size - Size of the variable/map in bytes
1008 EfiLibHiiVariablePackListGetMapCnt (
1009 IN EFI_HII_VARIABLE_PACK_LIST
*List
1013 Routine Description:
1015 Finds a count of the variables/maps in the List.
1019 List - List of variables
1023 Number of Map in the variable pack list.
1028 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
1037 Routine Description:
1039 type definition for the callback to be
1040 used with EfiLibHiiVariablePackListForEachVar().
1044 Id - Variable/Map ID
1045 Name - Name of the variable/map
1046 Guid - GUID of the variable/map
1047 Var - Pointer to the variable/map
1048 Size - Size of the variable/map in bytes
1058 EfiLibHiiVariablePackListForEachVar (
1059 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1060 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
1064 Routine Description:
1066 Will iterate all variable/maps as appearing
1067 in List and for each, it will call the Callback.
1071 List - List of variables
1072 Callback - Routine to be called for each iterated variable.
1082 EfiLibHiiVariablePackListGetMapByIdx (
1084 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1085 OUT CHAR16
**Name
, OPTIONAL
1086 OUT EFI_GUID
**Guid
, OPTIONAL
1087 OUT UINT16
*Id
, OPTIONAL
1093 Routine Description:
1095 Finds a variable form List given
1096 the order number as appears in the List.
1100 Idx - The index of the variable/map to retrieve
1101 List - List of variables
1102 Name - Name of the variable/map
1103 Guid - GUID of the variable/map
1104 Var - Pointer to the variable/map
1105 Size - Size of the variable/map in bytes
1109 EFI_SUCCESS - Variable is found, OUT parameters are valid
1110 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1116 EfiLibHiiVariablePackListGetMapById (
1118 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1119 OUT CHAR16
**Name
, OPTIONAL
1120 OUT EFI_GUID
**Guid
, OPTIONAL
1126 Routine Description:
1128 Finds a variable form List given the
1129 order number as appears in the List.
1133 Id - The ID 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 EfiLibHiiVariablePackListGetMap (
1150 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1159 Routine Description:
1161 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
1165 List - List of variables
1166 Name - Name of the variable/map to be found
1167 Guid - GUID of the variable/map to be found
1168 Var - Pointer to the variable/map found
1169 Size - Size of the variable/map in bytes found
1173 EFI_SUCCESS - variable is found, OUT parameters are valid
1174 EFI_NOT_FOUND - variable is not found, OUT parameters are not valid
1180 EfiLibHiiVariableRetrieveFromNv (
1188 Routine Description:
1189 Finds out if a variable of specific Name/Guid/Size exists in NV.
1190 If it does, it will retrieve it into the Var.
1193 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1194 Var - Variable will be retrieved into buffer pointed by this pointer.
1195 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
1197 EFI_SUCCESS - The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
1198 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1199 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1205 //// Variable override support.
1209 EfiLibHiiVariableOverrideIfSuffix (
1218 Routine Description:
1219 Overrrides the variable with NV data if found.
1220 But it only does it if the Name ends with specified Suffix.
1221 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
1222 the Suffix matches the end of Name, so the variable will be loaded from NV
1223 provided the variable exists and the GUID and Size matches.
1226 Suffix - Suffix the Name should end with.
1227 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1228 Var - Variable will be retrieved into this buffer.
1229 Caller is responsible for providing storage of exactly Size size in bytes.
1231 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1232 EFI_INVALID_PARAMETER - The name of the variable does not end with <Suffix>.
1233 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1234 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1240 EfiLibHiiVariableOverrideBySuffix (
1249 Routine Description:
1250 Overrrides the variable with NV data if found.
1251 But it only does it if the NV contains the same variable with Name is appended with Suffix.
1252 For example, if Suffix="MyOverride" and the Name="XyzSetup",
1253 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
1254 will be loaded from NV provided the variable exists and the GUID and Size matches.
1257 Suffix - Suffix the variable will be appended with.
1258 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1259 Var - Variable will be retrieved into this buffer.
1260 Caller is responsible for providing storage of exactly Size size in bytes.
1263 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1264 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1265 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.