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 #error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."
20 #define DEFAULT_FORM_BUFFER_SIZE 0xFFFF
21 #define DEFAULT_STRING_BUFFER_SIZE 0xFFFF
25 CHAR16
*OptionString
; // Passed in string to generate a token for in a truly dynamic form creation
26 STRING_REF StringToken
; // This is used when creating a single op-code without generating a StringToken (have one already)
41 Determine what is the current language setting
45 Lang - Pointer of system language
56 IN VOID
*StringBuffer
,
59 IN OUT STRING_REF
*StringToken
65 Add a string to the incoming buffer and return the token and offset data
69 StringBuffer - The incoming buffer
71 Language - Currrent language
73 String - The string to be added
75 StringToken - The index where the string placed
79 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
81 EFI_SUCCESS - String successfully added to the incoming buffer
89 IN OUT VOID
*OpCodeData
95 Add op-code data to the FormBuffer
99 FormBuffer - Form buffer to be inserted to
101 OpCodeData - Op-code data to be inserted
105 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
107 EFI_SUCCESS - Op-code data successfully inserted
114 IN CHAR16
*FormSetTitle
,
118 IN OUT VOID
**FormBuffer
,
119 IN OUT VOID
**StringBuffer
129 FormSetTitle - Title of formset
131 Guid - Guid of formset
133 Class - Class of formset
135 SubClass - Sub class of formset
137 FormBuffer - Pointer of the formset created
139 StringBuffer - Pointer of FormSetTitile string created
143 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
145 EFI_SUCCESS - Formset successfully created
152 IN CHAR16
*FormTitle
,
154 IN OUT VOID
*FormBuffer
,
155 IN OUT VOID
*StringBuffer
165 FormTitle - Title of the form
167 FormId - Id of the form
169 FormBuffer - Pointer of the form created
171 StringBuffer - Pointer of FormTitil string created
175 EFI_SUCCESS - Form successfully created
183 IN OUT VOID
*FormBuffer
,
184 IN OUT VOID
*StringBuffer
194 SubTitle - Sub title to be created
196 FormBuffer - Where this subtitle to add to
198 StringBuffer - String buffer created for subtitle
202 EFI_SUCCESS - Subtitle successfully created
214 IN OUT VOID
*FormBuffer
,
215 IN OUT VOID
*StringBuffer
221 Create a line of text
225 String - First string of the text
227 String2 - Second string of the text
229 String3 - Help string of the text
231 Flags - Flag of the text
233 Key - Key of the text
235 FormBuffer - The form where this text adds to
237 StringBuffer - String buffer created for String, String2 and String3
241 EFI_SUCCESS - Text successfully created
250 IN OUT VOID
*FormBuffer
,
251 IN OUT VOID
*StringBuffer
261 FormId - Form ID of the hyperlink
263 Prompt - Prompt of the hyperlink
265 FormBuffer - The form where this hyperlink adds to
267 StringBuffer - String buffer created for Prompt
271 EFI_SUCCESS - Hyperlink successfully created
278 IN UINT16 QuestionId
,
282 IN IFR_OPTION
*OptionsList
,
283 IN UINTN OptionCount
,
284 IN OUT VOID
*FormBuffer
,
285 IN OUT VOID
*StringBuffer
291 Create a one-of question with a set of options to choose from. The
292 OptionsList is a pointer to a null-terminated list of option descriptions.
296 QuestionId - Question ID of the one-of box
298 DataWidth - DataWidth of the one-of box
300 Prompt - Prompt of the one-of box
302 Help - Help of the one-of box
304 OptionsList - Each string in it is an option of the one-of box
306 OptionCount - Option string count
308 FormBuffer - The form where this one-of box adds to
310 StringBuffer - String buffer created for Prompt, Help and Option strings
314 EFI_DEVICE_ERROR - DataWidth > 2
316 EFI_SUCCESS - One-Of box successfully created.
323 IN UINT16 QuestionId
,
327 IN IFR_OPTION
*OptionsList
,
328 IN UINTN OptionCount
,
329 IN OUT VOID
*FormBuffer
,
330 IN OUT VOID
*StringBuffer
336 Create a one-of question with a set of options to choose from. The
337 OptionsList is a pointer to a null-terminated list of option descriptions.
341 QuestionId - Question ID of the ordered list
343 MaxEntries - MaxEntries of the ordered list
345 Prompt - Prompt of the ordered list
347 Help - Help of the ordered list
349 OptionsList - Each string in it is an option of the ordered list
351 OptionCount - Option string count
353 FormBuffer - The form where this ordered list adds to
355 StringBuffer - String buffer created for Prompt, Help and Option strings
359 EFI_SUCCESS - Ordered list successfully created.
366 IN UINT16 QuestionId
,
371 IN OUT VOID
*FormBuffer
,
372 IN OUT VOID
*StringBuffer
382 QuestionId - Question ID of the check box
384 DataWidth - DataWidth of the check box
386 Prompt - Prompt of the check box
388 Help - Help of the check box
390 Flags - Flags of the check box
392 FormBuffer - The form where this check box adds to
394 StringBuffer - String buffer created for Prompt and Help.
398 EFI_DEVICE_ERROR - DataWidth > 1
400 EFI_SUCCESS - Check box successfully created
407 IN UINT16 QuestionId
,
417 IN OUT VOID
*FormBuffer
,
418 IN OUT VOID
*StringBuffer
428 QuestionId - Question ID of the numeric
430 DataWidth - DataWidth of the numeric
432 Prompt - Prompt of the numeric
434 Help - Help of the numeric
436 Minimum - Minumun boundary of the numeric
438 Maximum - Maximum boundary of the numeric
440 Step - Step of the numeric
442 Default - Default value
444 Flags - Flags of the numeric
446 Key - Key of the numeric
448 FormBuffer - The form where this numeric adds to
450 StringBuffer - String buffer created for Prompt and Help.
454 EFI_DEVICE_ERROR - DataWidth > 2
456 EFI_SUCCESS - Numeric is successfully created
463 IN UINT16 QuestionId
,
471 IN OUT VOID
*FormBuffer
,
472 IN OUT VOID
*StringBuffer
482 QuestionId - Question ID of the string
484 DataWidth - DataWidth of the string
486 Prompt - Prompt of the string
488 Help - Help of the string
490 MinSize - Min size boundary of the string
492 MaxSize - Max size boundary of the string
494 Flags - Flags of the string
496 Key - Key of the string
498 FormBuffer - The form where this string adds to
500 StringBuffer - String buffer created for Prompt and Help.
504 EFI_SUCCESS - String successfully created.
510 ExtractDataFromHiiHandle (
511 IN EFI_HII_HANDLE HiiHandle
,
512 IN OUT UINT16
*ImageLength
,
513 OUT UINT8
*DefaultImage
,
520 Extract information pertaining to the HiiHandle
524 HiiHandle - Hii handle
526 ImageLength - For input, length of DefaultImage;
527 For output, length of actually required
529 DefaultImage - Image buffer prepared by caller
531 Guid - Guid information about the form
535 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
537 EFI_BUFFER_TOO_SMALL - DefualtImage has no enough ImageLength
539 EFI_SUCCESS - Successfully extract data from Hii database.
547 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
553 Finds HII handle for given pack GUID previously registered with the HII.
556 HiiProtocol - pointer to pointer to HII protocol interface.
557 If NULL, the interface will be found but not returned.
558 If it points to NULL, the interface will be found and
559 written back to the pointer that is pointed to.
560 Guid - The GUID of the pack that registered with the HII.
563 Handle to the HII pack previously registered by the memory driver.
569 CreateSubTitleOpCode (
570 IN STRING_REF StringToken
,
571 IN OUT VOID
*FormBuffer
577 Create a SubTitle opcode independent of string creation
578 This is used primarily by users who need to create just one particular valid op-code and the string
579 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
580 location to pre-defined forms in HII)
584 StringToken - StringToken of the subtitle
586 FormBuffer - Output of subtitle as a form
590 EFI_SUCCESS - Subtitle created to be a form
597 IN STRING_REF StringToken
,
598 IN STRING_REF StringTokenTwo
,
599 IN STRING_REF StringTokenThree
,
602 IN OUT VOID
*FormBuffer
608 Create a Text opcode independent of string creation
609 This is used primarily by users who need to create just one particular valid op-code and the string
610 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
611 location to pre-defined forms in HII)
615 StringToken - First string token of the text
617 StringTokenTwo - Second string token of the text
619 StringTokenThree - Help string token of the text
621 Flags - Flag of the text
623 Key - Key of the text
625 FormBuffer - Output of text as a form
629 EFI_SUCCESS - Text created to be a form
637 IN STRING_REF StringToken
,
638 IN STRING_REF StringTokenTwo
,
641 IN OUT VOID
*FormBuffer
647 Create a hyperlink opcode independent of string creation
648 This is used primarily by users who need to create just one particular valid op-code and the string
649 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
650 location to pre-defined forms in HII)
654 FormId - Form ID of the hyperlink
656 StringToken - Prompt string token of the hyperlink
658 StringTokenTwo - Help string token of the hyperlink
660 Flags - Flags of the hyperlink
662 Key - Key of the hyperlink
664 FormBuffer - Output of hyperlink as a form
668 EFI_SUCCESS - Hyperlink created to be a form
675 IN UINT16 QuestionId
,
677 IN STRING_REF PromptToken
,
678 IN STRING_REF HelpToken
,
679 IN IFR_OPTION
*OptionsList
,
680 IN UINTN OptionCount
,
681 IN OUT VOID
*FormBuffer
687 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
688 This is used primarily by users who need to create just one particular valid op-code and the string
689 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
690 location to pre-defined forms in HII)
692 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
693 has been filled in since this routine will not generate StringToken values.
697 QuestionId - Question ID of the one-of box
699 DataWidth - DataWidth of the one-of box
701 PromptToken - Prompt string token of the one-of box
703 HelpToken - Help string token of the one-of box
705 OptionsList - Each string in it is an option of the one-of box
707 OptionCount - Option string count
709 FormBuffer - Output of One-Of box as a form
713 EFI_SUCCESS - One-Of box created to be a form
715 EFI_DEVICE_ERROR - DataWidth > 2
721 CreateOrderedListOpCode (
722 IN UINT16 QuestionId
,
724 IN STRING_REF PromptToken
,
725 IN STRING_REF HelpToken
,
726 IN IFR_OPTION
*OptionsList
,
727 IN UINTN OptionCount
,
728 IN OUT VOID
*FormBuffer
734 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
735 This is used primarily by users who need to create just one particular valid op-code and the string
736 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
737 location to pre-defined forms in HII)
739 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
740 has been filled in since this routine will not generate StringToken values.
744 QuestionId - Question ID of the ordered list
746 MaxEntries - MaxEntries of the ordered list
748 PromptToken - Prompt string token of the ordered list
750 HelpToken - Help string token of the ordered list
752 OptionsList - Each string in it is an option of the ordered list
754 OptionCount - Option string count
756 FormBuffer - Output of ordered list as a form
760 EFI_SUCCESS - Ordered list created to be a form
766 CreateCheckBoxOpCode (
767 IN UINT16 QuestionId
,
769 IN STRING_REF PromptToken
,
770 IN STRING_REF HelpToken
,
773 IN OUT VOID
*FormBuffer
779 Create a checkbox opcode independent of string creation
780 This is used primarily by users who need to create just one particular valid op-code and the string
781 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
782 location to pre-defined forms in HII)
786 QuestionId - Question ID of the check box
788 DataWidth - DataWidth of the check box
790 PromptToken - Prompt string token of the check box
792 HelpToken - Help string token of the check box
794 Flags - Flags of the check box
796 Key - Key of the check box
798 FormBuffer - Output of the check box as a form
802 EFI_SUCCESS - Checkbox created to be a form
804 EFI_DEVICE_ERROR - DataWidth > 1
810 CreateNumericOpCode (
811 IN UINT16 QuestionId
,
813 IN STRING_REF PromptToken
,
814 IN STRING_REF HelpToken
,
821 IN OUT VOID
*FormBuffer
827 Create a numeric opcode independent of string creation
828 This is used primarily by users who need to create just one particular valid op-code and the string
829 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
830 location to pre-defined forms in HII)
834 QuestionId - Question ID of the numeric
836 DataWidth - DataWidth of the numeric
838 PromptToken - Prompt string token of the numeric
840 HelpToken - Help string token of the numeric
842 Minimum - Minumun boundary of the numeric
844 Maximum - Maximum boundary of the numeric
846 Step - Step of the numeric
848 Default - Default value of the numeric
850 Flags - Flags of the numeric
852 Key - Key of the numeric
854 FormBuffer - Output of the numeric as a form
858 EFI_SUCCESS - The numeric created to be a form.
860 EFI_DEVICE_ERROR - DataWidth > 2
867 IN UINT16 QuestionId
,
869 IN STRING_REF PromptToken
,
870 IN STRING_REF HelpToken
,
875 IN OUT VOID
*FormBuffer
881 Create a numeric opcode independent of string creation
882 This is used primarily by users who need to create just one particular valid op-code and the string
883 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
884 location to pre-defined forms in HII)
888 QuestionId - Question ID of the string
890 DataWidth - DataWidth of the string
892 PromptToken - Prompt token of the string
894 HelpToken - Help token of the string
896 MinSize - Min size boundary of the string
898 MaxSize - Max size boundary of the string
900 Flags - Flags of the string
902 Key - Key of the string
904 FormBuffer - Output of the string as a form
908 EFI_SUCCESS - String created to be a form.
914 ValidateDataFromHiiHandle (
915 IN EFI_HII_HANDLE HiiHandle
,
922 Validate that the data associated with the HiiHandle in NVRAM is within
923 the reasonable parameters for that FormSet. Values for strings and passwords
924 are not verified due to their not having the equivalent of valid range settings.
928 HiiHandle - Handle of the HII database entry to query
930 Results - If return Status is EFI_SUCCESS, Results provides valid data
931 TRUE = NVRAM Data is within parameters
932 FALSE = NVRAM Data is NOT within parameters
936 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
938 EFI_SUCCESS - Data successfully validated
945 IN UINT16 LineNumber
,
947 IN OUT VOID
*FormBuffer
953 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
957 Title - Title of the banner
959 LineNumber - LineNumber of the banner
961 Alignment - Alignment of the banner
963 FormBuffer - Output of banner as a form
967 EFI_SUCCESS - Banner created to be a form.
973 EfiLibHiiVariablePackGetMap (
974 IN EFI_HII_VARIABLE_PACK
*Pack
,
975 OUT CHAR16
**Name
, OPTIONAL
976 OUT EFI_GUID
**Guid
, OPTIONAL
977 OUT UINT16
*Id
, OPTIONAL
978 OUT VOID
**Var
, OPTIONAL
979 OUT UINTN
*Size OPTIONAL
985 Extracts a variable form a Pack.
989 Pack - List of variables
990 Name - Name of the variable/map
991 Guid - GUID of the variable/map
992 Var - Pointer to the variable/map
993 Size - Size of the variable/map in bytes
1003 EfiLibHiiVariablePackListGetMapCnt (
1004 IN EFI_HII_VARIABLE_PACK_LIST
*List
1008 Routine Description:
1010 Finds a count of the variables/maps in the List.
1014 List - List of variables
1018 Number of Map in the variable pack list.
1023 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
1032 Routine Description:
1034 type definition for the callback to be
1035 used with EfiLibHiiVariablePackListForEachVar().
1039 Id - Variable/Map ID
1040 Name - Name of the variable/map
1041 Guid - GUID of the variable/map
1042 Var - Pointer to the variable/map
1043 Size - Size of the variable/map in bytes
1053 EfiLibHiiVariablePackListForEachVar (
1054 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1055 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
1059 Routine Description:
1061 Will iterate all variable/maps as appearing
1062 in List and for each, it will call the Callback.
1066 List - List of variables
1067 Callback - Routine to be called for each iterated variable.
1077 EfiLibHiiVariablePackListGetMapByIdx (
1079 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1080 OUT CHAR16
**Name
, OPTIONAL
1081 OUT EFI_GUID
**Guid
, OPTIONAL
1082 OUT UINT16
*Id
, OPTIONAL
1088 Routine Description:
1090 Finds a variable form List given
1091 the order number as appears in the List.
1095 Idx - The index of the variable/map to retrieve
1096 List - List of variables
1097 Name - Name of the variable/map
1098 Guid - GUID of the variable/map
1099 Var - Pointer to the variable/map
1100 Size - Size of the variable/map in bytes
1104 EFI_SUCCESS - Variable is found, OUT parameters are valid
1105 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1111 EfiLibHiiVariablePackListGetMapById (
1113 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1114 OUT CHAR16
**Name
, OPTIONAL
1115 OUT EFI_GUID
**Guid
, OPTIONAL
1121 Routine Description:
1123 Finds a variable form List given the
1124 order number as appears in the List.
1128 Id - The ID of the variable/map to retrieve
1129 List - List of variables
1130 Name - Name of the variable/map
1131 Guid - GUID of the variable/map
1132 Var - Pointer to the variable/map
1133 Size - Size of the variable/map in bytes
1137 EFI_SUCCESS - Variable is found, OUT parameters are valid
1138 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1144 EfiLibHiiVariablePackListGetMap (
1145 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1154 Routine Description:
1156 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
1160 List - List of variables
1161 Name - Name of the variable/map to be found
1162 Guid - GUID of the variable/map to be found
1163 Var - Pointer to the variable/map found
1164 Size - Size of the variable/map in bytes found
1168 EFI_SUCCESS - variable is found, OUT parameters are valid
1169 EFI_NOT_FOUND - variable is not found, OUT parameters are not valid
1175 EfiLibHiiVariableRetrieveFromNv (
1183 Routine Description:
1184 Finds out if a variable of specific Name/Guid/Size exists in NV.
1185 If it does, it will retrieve it into the Var.
1188 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1189 Var - Variable will be retrieved into buffer pointed by this pointer.
1190 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
1192 EFI_SUCCESS - The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
1193 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1194 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1200 //// Variable override support.
1204 EfiLibHiiVariableOverrideIfSuffix (
1213 Routine Description:
1214 Overrrides the variable with NV data if found.
1215 But it only does it if the Name ends with specified Suffix.
1216 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
1217 the Suffix matches the end of Name, so the variable will be loaded from NV
1218 provided the variable exists and the GUID and Size matches.
1221 Suffix - Suffix the Name should end with.
1222 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1223 Var - Variable will be retrieved into this buffer.
1224 Caller is responsible for providing storage of exactly Size size in bytes.
1226 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1227 EFI_INVALID_PARAMETER - The name of the variable does not end with <Suffix>.
1228 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1229 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1235 EfiLibHiiVariableOverrideBySuffix (
1244 Routine Description:
1245 Overrrides the variable with NV data if found.
1246 But it only does it if the NV contains the same variable with Name is appended with Suffix.
1247 For example, if Suffix="MyOverride" and the Name="XyzSetup",
1248 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
1249 will be loaded from NV provided the variable exists and the GUID and Size matches.
1252 Suffix - Suffix the variable will be appended with.
1253 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1254 Var - Variable will be retrieved into this buffer.
1255 Caller is responsible for providing storage of exactly Size size in bytes.
1258 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1259 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1260 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.