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)
35 Determine what is the current language setting.
37 The setting is stored in language variable in flash. This routine
38 will get setting by accesssing that variable. If failed to access
39 language variable, then use default setting that 'eng' as current
42 @param Lang Pointer of system language
44 @return whether sucess to get setting from variable
52 Add a string to the incoming buffer and return the token and offset data.
54 @param StringBuffer The incoming buffer
55 @param Language Currrent language
56 @param String The string to be added
57 @param StringToken The index where the string placed
59 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
60 @retval EFI_SUCCESS String successfully added to the incoming buffer
64 IN VOID
*StringBuffer
,
67 IN OUT STRING_REF
*StringToken
71 Add op-code data to the FormBuffer.
73 @param FormBuffer Form buffer to be inserted to
74 @param OpCodeData Op-code data to be inserted
76 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
77 @retval EFI_SUCCESS Op-code data successfully inserted
82 IN OUT VOID
*OpCodeData
88 The form package is a collection of forms that are intended to describe the pages that will be
89 displayed to the user.
91 @param FormSetTitle Title of formset
92 @param Guid Guid of formset
93 @param Class Class of formset
94 @param SubClass Sub class of formset
95 @param FormBuffer Pointer of the formset created
96 @param StringBuffer Pointer of FormSetTitile string created
98 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
99 @retval EFI_SUCCESS Formset successfully created
103 IN CHAR16
*FormSetTitle
,
107 IN OUT VOID
**FormBuffer
,
108 IN OUT VOID
**StringBuffer
113 A form is the encapsulation of what amounts to a browser page. The header defines a FormId,
114 which is referenced by the form package, among others. It also defines a FormTitle, which is a
115 string to be used as the title for the form
117 @param FormTitle Title of the form
118 @param FormId Id of the form
119 @param FormBuffer Pointer of the form created
120 @param StringBuffer Pointer of FormTitil string created
122 @retval EFI_SUCCESS Form successfully created
126 IN CHAR16
*FormTitle
,
128 IN OUT VOID
*FormBuffer
,
129 IN OUT VOID
*StringBuffer
135 Subtitle strings are intended to be used by authors to separate sections of questions into semantic
138 @param SubTitle Sub title to be created
139 @param FormBuffer Where this subtitle to add to
140 @param StringBuffer String buffer created for subtitle
142 @retval EFI_SUCCESS Subtitle successfully created
147 IN OUT VOID
*FormBuffer
,
148 IN OUT VOID
*StringBuffer
152 Create a line of text
153 Unlike HTML, text is simply another tag.
154 This tag type enables IFR to be more easily localized.
156 @param String First string of the text
157 @param String2 Second string of the text
158 @param String3 Help string of the text
159 @param Flags Flag of the text
160 @param Key Key of the text
161 @param FormBuffer The form where this text adds to
162 @param StringBuffer String buffer created for String, String2 and String3
164 @retval EFI_SUCCESS Text successfully created
173 IN OUT VOID
*FormBuffer
,
174 IN OUT VOID
*StringBuffer
180 @param FormId Form ID of the hyperlink
181 @param Prompt Prompt of the hyperlink
182 @param FormBuffer The form where this hyperlink adds to
183 @param StringBuffer String buffer created for Prompt
185 @retval EFI_SUCCESS Hyperlink successfully created
191 IN OUT VOID
*FormBuffer
,
192 IN OUT VOID
*StringBuffer
196 Create a one-of question with a set of options to choose from. The
197 OptionsList is a pointer to a null-terminated list of option descriptions.
199 @param QuestionId Question ID of the one-of box
200 @param DataWidth DataWidth of the one-of box
201 @param Prompt Prompt of the one-of box
202 @param Help Help of the one-of box
203 @param OptionsList Each string in it is an option of the one-of box
204 @param OptionCount Option string count
205 @param FormBuffer The form where this one-of box adds to
206 @param StringBuffer String buffer created for Prompt, Help and Option strings
208 @retval EFI_DEVICE_ERROR DataWidth > 2
209 @retval EFI_SUCCESS One-Of box successfully created.
213 IN UINT16 QuestionId
,
217 IN IFR_OPTION
*OptionsList
,
218 IN UINTN OptionCount
,
219 IN OUT VOID
*FormBuffer
,
220 IN OUT VOID
*StringBuffer
224 Create a one-of question with a set of options to choose from. The
225 OptionsList is a pointer to a null-terminated list of option descriptions.
227 @param QuestionId Question ID of the ordered list
228 @param MaxEntries MaxEntries of the ordered list
229 @param Prompt Prompt of the ordered list
230 @param Help Help of the ordered list
231 @param OptionsList Each string in it is an option of the ordered list
232 @param OptionCount Option string count
233 @param FormBuffer The form where this ordered list adds to
234 @param StringBuffer String buffer created for Prompt, Help and Option strings
236 @retval EFI_SUCCESS Ordered list successfully created.
240 IN UINT16 QuestionId
,
244 IN IFR_OPTION
*OptionsList
,
245 IN UINTN OptionCount
,
246 IN OUT VOID
*FormBuffer
,
247 IN OUT VOID
*StringBuffer
253 @param QuestionId Question ID of the check box
254 @param DataWidth DataWidth of the check box
255 @param Prompt Prompt of the check box
256 @param Help Help of the check box
257 @param Flags Flags of the check box
258 @param FormBuffer The form where this check box adds to
259 @param StringBuffer String buffer created for Prompt and Help.
261 @retval EFI_DEVICE_ERROR DataWidth > 1
262 @retval EFI_SUCCESS Check box successfully created
266 IN UINT16 QuestionId
,
271 IN OUT VOID
*FormBuffer
,
272 IN OUT VOID
*StringBuffer
278 @param QuestionId Question ID of the numeric
279 @param DataWidth DataWidth of the numeric
280 @param Prompt Prompt of the numeric
281 @param Help Help of the numeric
282 @param Minimum Minumun boundary of the numeric
283 @param Maximum Maximum boundary of the numeric
284 @param Step Step of the numeric
285 @param Default Default value
286 @param Flags Flags of the numeric
287 @param Key Key of the numeric
288 @param FormBuffer The form where this numeric adds to
289 @param StringBuffer String buffer created for Prompt and Help.
291 @retval EFI_DEVICE_ERROR DataWidth > 2
292 @retval EFI_SUCCESS Numeric is successfully created
296 IN UINT16 QuestionId
,
306 IN OUT VOID
*FormBuffer
,
307 IN OUT VOID
*StringBuffer
313 @param QuestionId Question ID of the string
314 @param DataWidth DataWidth of the string
315 @param Prompt Prompt of the string
316 @param Help Help of the string
317 @param MinSize Min size boundary of the string
318 @param MaxSize Max size boundary of the string
319 @param Flags Flags of the string
320 @param Key Key of the string
321 @param FormBuffer The form where this string adds to
322 @param StringBuffer String buffer created for Prompt and Help.
323 @retval EFI_SUCCESS String successfully created.
327 IN UINT16 QuestionId
,
335 IN OUT VOID
*FormBuffer
,
336 IN OUT VOID
*StringBuffer
340 Extract information pertaining to the HiiHandle.
342 @param HiiHandle Hii handle
343 @param ImageLength For input, length of DefaultImage;
344 For output, length of actually required
345 @param DefaultImage Image buffer prepared by caller
346 @param Guid Guid information about the form
348 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
349 @retval EFI_BUFFER_TOO_SMALL DefualtImage has no enough ImageLength
350 @retval EFI_SUCCESS Successfully extract data from Hii database.
353 ExtractDataFromHiiHandle (
354 IN FRAMEWORK_EFI_HII_HANDLE HiiHandle
,
355 IN OUT UINT16
*ImageLength
,
356 OUT UINT8
*DefaultImage
,
361 Finds HII handle for given pack GUID previously registered with the HII.
363 @param HiiProtocol pointer to pointer to HII protocol interface.
364 If NULL, the interface will be found but not returned.
365 If it points to NULL, the interface will be found and
366 written back to the pointer that is pointed to.
367 @param Guid The GUID of the pack that registered with the HII.
369 @return Handle to the HII pack previously registered by the memory driver.
371 FRAMEWORK_EFI_HII_HANDLE
373 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
378 Create a SubTitle opcode independent of string creation
379 This is used primarily by users who need to create just one particular valid op-code and the string
380 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
381 location to pre-defined forms in HII)
383 @param StringToken StringToken of the subtitle
384 @param FormBuffer Output of subtitle as a form
386 @retval EFI_SUCCESS Subtitle created to be a form
389 CreateSubTitleOpCode (
390 IN STRING_REF StringToken
,
391 IN OUT VOID
*FormBuffer
395 Create a Text opcode independent of string creation.
397 This is used primarily by users who need to create just one particular valid op-code and the string
398 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
399 location to pre-defined forms in HII)
401 @param StringToken First string token of the text
402 @param StringTokenTwo Second string token of the text
403 @param StringTokenThree Help string token of the text
404 @param Flags Flag of the text
405 @param Key Key of the text
406 @param FormBuffer Output of text as a form
408 @retval EFI_SUCCESS Text created to be a form
412 IN STRING_REF StringToken
,
413 IN STRING_REF StringTokenTwo
,
414 IN STRING_REF StringTokenThree
,
417 IN OUT VOID
*FormBuffer
421 Create a hyperlink opcode independent of string creation.
423 This is used primarily by users who need to create just one particular valid op-code and the string
424 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
425 location to pre-defined forms in HII)
428 @param FormId Form ID of the hyperlink
429 @param StringToken Prompt string token of the hyperlink
430 @param StringTokenTwo Help string token of the hyperlink
431 @param Flags Flags of the hyperlink
432 @param Key Key of the hyperlink
433 @param FormBuffer Output of hyperlink as a form
434 @retval EFI_SUCCESS Hyperlink created to be a form
439 IN STRING_REF StringToken
,
440 IN STRING_REF StringTokenTwo
,
443 IN OUT VOID
*FormBuffer
447 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
448 This is used primarily by users who need to create just one particular valid op-code and the string
449 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
450 location to pre-defined forms in HII)
452 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
453 has been filled in since this routine will not generate StringToken values.
455 @param QuestionId Question ID of the one-of box
456 @param DataWidth DataWidth of the one-of box
457 @param PromptToken Prompt string token of the one-of box
458 @param HelpToken Help string token of the one-of box
459 @param OptionsList Each string in it is an option of the one-of box
460 @param OptionCount Option string count
461 @param FormBuffer Output of One-Of box as a form
464 @retval EFI_SUCCESS One-Of box created to be a form
465 @retval EFI_DEVICE_ERROR DataWidth > 2
469 IN UINT16 QuestionId
,
471 IN STRING_REF PromptToken
,
472 IN STRING_REF HelpToken
,
473 IN IFR_OPTION
*OptionsList
,
474 IN UINTN OptionCount
,
475 IN OUT VOID
*FormBuffer
479 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
480 This is used primarily by users who need to create just one particular valid op-code and the string
481 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
482 location to pre-defined forms in HII)
484 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
485 has been filled in since this routine will not generate StringToken values.
487 @param QuestionId Question ID of the ordered list
488 @param MaxEntries MaxEntries of the ordered list
489 @param PromptToken Prompt string token of the ordered list
490 @param HelpToken Help string token of the ordered list
491 @param OptionsList Each string in it is an option of the ordered list
492 @param OptionCount Option string count
493 @param FormBuffer Output of ordered list as a form
495 @retval EFI_SUCCESS Ordered list created to be a form
498 CreateOrderedListOpCode (
499 IN UINT16 QuestionId
,
501 IN STRING_REF PromptToken
,
502 IN STRING_REF HelpToken
,
503 IN IFR_OPTION
*OptionsList
,
504 IN UINTN OptionCount
,
505 IN OUT VOID
*FormBuffer
509 Create a checkbox opcode independent of string creation
510 This is used primarily by users who need to create just one particular valid op-code and the string
511 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
512 location to pre-defined forms in HII)
514 @param QuestionId Question ID of the check box
515 @param DataWidth DataWidth of the check box
516 @param PromptToken Prompt string token of the check box
517 @param HelpToken Help string token of the check box
518 @param Flags Flags of the check box
519 @param Key Key of the check box
520 @param FormBuffer Output of the check box as a form
522 @retval EFI_SUCCESS Checkbox created to be a form
523 @retval EFI_DEVICE_ERROR DataWidth > 1
526 CreateCheckBoxOpCode (
527 IN UINT16 QuestionId
,
529 IN STRING_REF PromptToken
,
530 IN STRING_REF HelpToken
,
533 IN OUT VOID
*FormBuffer
537 Create a numeric opcode independent of string creation.
538 This is used primarily by users who need to create just one particular valid op-code and the string
539 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
540 location to pre-defined forms in HII)
542 @param QuestionId Question ID of the numeric
543 @param DataWidth DataWidth of the numeric
544 @param PromptToken Prompt string token of the numeric
545 @param HelpToken Help string token of the numeric
546 @param Minimum Minumun boundary of the numeric
547 @param Maximum Maximum boundary of the numeric
548 @param Step Step of the numeric
549 @param Default Default value of the numeric
550 @param Flags Flags of the numeric
551 @param Key Key of the numeric
552 @param FormBuffer Output of the numeric as a form
555 @retval EFI_SUCCESS The numeric created to be a form.
556 @retval EFI_DEVICE_ERROR DataWidth > 2
559 CreateNumericOpCode (
560 IN UINT16 QuestionId
,
562 IN STRING_REF PromptToken
,
563 IN STRING_REF HelpToken
,
570 IN OUT VOID
*FormBuffer
574 Create a numeric opcode independent of string creation
575 This is used primarily by users who need to create just one particular valid op-code and the string
576 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
577 location to pre-defined forms in HII)
579 @param QuestionId Question ID of the string
580 @param DataWidth DataWidth of the string
581 @param PromptToken Prompt token of the string
582 @param HelpToken Help token of the string
583 @param MinSize Min size boundary of the string
584 @param MaxSize Max size boundary of the string
585 @param Flags Flags of the string
586 @param Key Key of the string
587 @param FormBuffer Output of the string as a form
589 @retval EFI_SUCCESS String created to be a form.
593 IN UINT16 QuestionId
,
595 IN STRING_REF PromptToken
,
596 IN STRING_REF HelpToken
,
601 IN OUT VOID
*FormBuffer
605 Validate that the data associated with the HiiHandle in NVRAM is within
606 the reasonable parameters for that FormSet. Values for strings and passwords
607 are not verified due to their not having the equivalent of valid range settings.
609 @param HiiHandle Handle of the HII database entry to query
611 @param Results If return Status is EFI_SUCCESS, Results provides valid data
612 TRUE = NVRAM Data is within parameters
613 FALSE = NVRAM Data is NOT within parameters
614 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
615 @retval EFI_SUCCESS Data successfully validated
618 ValidateDataFromHiiHandle (
619 IN FRAMEWORK_EFI_HII_HANDLE HiiHandle
,
624 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
626 @param Title Title of the banner
627 @param LineNumber LineNumber of the banner
628 @param Alignment Alignment of the banner
629 @param FormBuffer Output of banner as a form
631 @retval EFI_SUCCESS Banner created to be a form.
636 IN UINT16 LineNumber
,
638 IN OUT VOID
*FormBuffer
642 Extracts a variable form a Pack.
644 @param Pack List of variables
645 @param Name Name of the variable/map
646 @param Guid GUID of the variable/map
647 @param Id The index of the variable/map to retrieve
648 @param Var Pointer to the variable/map
649 @param Size Size of the variable/map in bytes
652 EfiLibHiiVariablePackGetMap (
653 IN EFI_HII_VARIABLE_PACK
*Pack
,
654 OUT CHAR16
**Name
, OPTIONAL
655 OUT EFI_GUID
**Guid
, OPTIONAL
656 OUT UINT16
*Id
, OPTIONAL
657 OUT VOID
**Var
, OPTIONAL
658 OUT UINTN
*Size OPTIONAL
662 Finds a count of the variables/maps in the List.
664 @param List List of variables
666 @return The number of map count.
669 EfiLibHiiVariablePackListGetMapCnt (
670 IN EFI_HII_VARIABLE_PACK_LIST
*List
674 type definition for the callback to be
675 used with EfiLibHiiVariablePackListForEachVar().
677 @param Id Variable/Map ID
678 @param Name Name of the variable/map
679 @param Guid GUID of the variable/map
680 @param Var Pointer to the variable/map
681 @param Size Size of the variable/map in bytes
683 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
692 Will iterate all variable/maps as appearing
693 in List and for each, it will call the Callback.
695 @param List List of variables
696 @param Callback Routine to be called for each iterated variable.
699 EfiLibHiiVariablePackListForEachVar (
700 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
701 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
705 Finds a variable form List given
706 the order number as appears in the List.
708 @param Idx The index of the variable/map to retrieve
709 @param List List of variables
710 @param Name Name of the variable/map
711 @param Guid GUID of the variable/map
712 @param Id Id of the variable/map
713 @param Var Pointer to the variable/map
714 @param Size Size of the variable/map in bytes
716 @return EFI_SUCCESS Variable is found, OUT parameters are valid
717 @return EFI_NOT_FOUND Variable is not found, OUT parameters are not valid
720 EfiLibHiiVariablePackListGetMapByIdx (
722 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
723 OUT CHAR16
**Name
, OPTIONAL
724 OUT EFI_GUID
**Guid
, OPTIONAL
725 OUT UINT16
*Id
, OPTIONAL
731 Finds a variable form List given the
732 order number as appears in the List.
734 @param Id The ID of the variable/map to retrieve
735 @param List List of variables
736 @param Name Name of the variable/map
737 @param Guid GUID of the variable/map
738 @param Var Pointer to the variable/map
739 @param Size Size of the variable/map in bytes
741 @retval EFI_SUCCESS Variable is found, OUT parameters are valid
742 @retval EFI_NOT_FOUND Variable is not found, OUT parameters are not valid
745 EfiLibHiiVariablePackListGetMapById (
747 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
748 OUT CHAR16
**Name
, OPTIONAL
749 OUT EFI_GUID
**Guid
, OPTIONAL
755 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
757 @param List List of variables
758 @param Name Name of the variable/map to be found
759 @param Guid GUID of the variable/map to be found
760 @param Id Id of the variable/map to be found
761 @param Var Pointer to the variable/map found
762 @param Size Size of the variable/map in bytes found
764 @retval EFI_SUCCESS variable is found, OUT parameters are valid
765 @retval EFI_NOT_FOUND variable is not found, OUT parameters are not valid
768 EfiLibHiiVariablePackListGetMap (
769 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
778 Finds out if a variable of specific Name/Guid/Size exists in NV.
779 If it does, it will retrieve it into the Var.
781 @param Name Parameters of the variable to retrieve. Must match exactly.
782 @param Guid Parameters of the variable to retrieve. Must match exactly.
783 @param Size Parameters of the variable to retrieve. Must match exactly.
784 @param Var Variable will be retrieved into buffer pointed by this pointer.
785 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
787 @retval EFI_SUCCESS The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
788 @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV.
789 @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error.
792 EfiLibHiiVariableRetrieveFromNv (
800 Overrrides the variable with NV data if found.
801 But it only does it if the Name ends with specified Suffix.
802 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
803 the Suffix matches the end of Name, so the variable will be loaded from NV
804 provided the variable exists and the GUID and Size matches.
806 @param Suffix Suffix the Name should end with.
807 @param Name Name of the variable to retrieve.
808 @Param Guid Guid of the variable to retrieve.
809 @Param Size Parameters of the variable to retrieve.
810 @param Var Variable will be retrieved into this buffer.
811 Caller is responsible for providing storage of exactly Size size in bytes.
813 @retval EFI_SUCCESS The variable was overriden with NV variable of same Name/Guid/Size.
814 @retval EFI_INVALID_PARAMETER The name of the variable does not end with <Suffix>.
815 @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV.
816 @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error.
819 EfiLibHiiVariableOverrideIfSuffix (
828 Overrrides the variable with NV data if found.
829 But it only does it if the NV contains the same variable with Name is appended with Suffix.
830 For example, if Suffix="MyOverride" and the Name="XyzSetup",
831 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
832 will be loaded from NV provided the variable exists and the GUID and Size matches.
834 @param Suffix Suffix the variable will be appended with.
835 @param Name Parameters of the Name variable to retrieve.
836 @param Guid Parameters of the Guid variable to retrieve.
837 @param Size Parameters of the Size variable to retrieve.
838 @param Var Variable will be retrieved into this buffer.
839 Caller is responsible for providing storage of exactly Size size in bytes.
841 @retval EFI_SUCCESS The variable was overriden with NV variable of same Name/Guid/Size.
842 @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV.
843 @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error.
846 EfiLibHiiVariableOverrideBySuffix (