From dddb694d3ed0cb0d095fdfccf806c3d374a8eb5c Mon Sep 17 00:00:00 2001 From: gdong1 Date: Tue, 23 Dec 2008 03:12:54 +0000 Subject: correct the comments style. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7092 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Include/Library/FrameworkIfrSupportLib.h | 1332 +++++++------------- 1 file changed, 460 insertions(+), 872 deletions(-) (limited to 'IntelFrameworkPkg') diff --git a/IntelFrameworkPkg/Include/Library/FrameworkIfrSupportLib.h b/IntelFrameworkPkg/Include/Library/FrameworkIfrSupportLib.h index a062f87177..ca380ee9c6 100644 --- a/IntelFrameworkPkg/Include/Library/FrameworkIfrSupportLib.h +++ b/IntelFrameworkPkg/Include/Library/FrameworkIfrSupportLib.h @@ -15,8 +15,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ -#ifndef _IFRSUPPORTLIBRARY_H -#define _IFRSUPPORTLIBRARY_H +#ifndef _IFRSUPPORTLIBRARY_H_ +#define _IFRSUPPORTLIBRARY_H_ #define DEFAULT_FORM_BUFFER_SIZE 0xFFFF #define DEFAULT_STRING_BUFFER_SIZE 0xFFFF @@ -31,85 +31,73 @@ typedef struct { } IFR_OPTION; #pragma pack() +/** + Determine what is the current language setting. + + The setting is stored in language variable in flash. This routine + will get setting by accesssing that variable. If failed to access + language variable, then use default setting that 'eng' as current + language setting. + + @param Lang Pointer of system language + + @return whether sucess to get setting from variable +**/ EFI_STATUS GetCurrentLanguage ( OUT CHAR16 *Lang - ) -/*++ - -Routine Description: - - Determine what is the current language setting - -Arguments: + ); - Lang - Pointer of system language +/** + Add a string to the incoming buffer and return the token and offset data. -Returns: + @param StringBuffer The incoming buffer + @param Language Currrent language + @param String The string to be added + @param StringToken The index where the string placed - Status code - ---*/ -; - + @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate + @retval EFI_SUCCESS String successfully added to the incoming buffer +**/ EFI_STATUS AddString ( IN VOID *StringBuffer, IN CHAR16 *Language, IN CHAR16 *String, IN OUT STRING_REF *StringToken - ) -/*++ - -Routine Description: + ); - Add a string to the incoming buffer and return the token and offset data - -Arguments: - - StringBuffer - The incoming buffer - - Language - Currrent language +/** + Add op-code data to the FormBuffer. - String - The string to be added + @param FormBuffer Form buffer to be inserted to + @param OpCodeData Op-code data to be inserted - StringToken - The index where the string placed - -Returns: - - EFI_OUT_OF_RESOURCES - No enough buffer to allocate - - EFI_SUCCESS - String successfully added to the incoming buffer - ---*/ -; - + @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate + @retval EFI_SUCCESS Op-code data successfully inserted +**/ EFI_STATUS AddOpCode ( IN VOID *FormBuffer, IN OUT VOID *OpCodeData - ) -/*++ - -Routine Description: + ); - Add op-code data to the FormBuffer - -Arguments: - - FormBuffer - Form buffer to be inserted to +/** + Create a formset - OpCodeData - Op-code data to be inserted + The form package is a collection of forms that are intended to describe the pages that will be + displayed to the user. -Returns: - - EFI_OUT_OF_RESOURCES - No enough buffer to allocate + @param FormSetTitle Title of formset + @param Guid Guid of formset + @param Class Class of formset + @param SubClass Sub class of formset + @param FormBuffer Pointer of the formset created + @param StringBuffer Pointer of FormSetTitile string created - EFI_SUCCESS - Op-code data successfully inserted - ---*/ -; - + @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate + @retval EFI_SUCCESS Formset successfully created +**/ EFI_STATUS CreateFormSet ( IN CHAR16 *FormSetTitle, @@ -118,93 +106,63 @@ CreateFormSet ( IN UINT8 SubClass, IN OUT VOID **FormBuffer, IN OUT VOID **StringBuffer - ) -/*++ + ); -Routine Description: - - Create a formset - -Arguments: - - FormSetTitle - Title of formset - - Guid - Guid of formset - - Class - Class of formset - - SubClass - Sub class of formset +/** + Create a form. + A form is the encapsulation of what amounts to a browser page. The header defines a FormId, + which is referenced by the form package, among others. It also defines a FormTitle, which is a + string to be used as the title for the form - FormBuffer - Pointer of the formset created + @param FormTitle Title of the form + @param FormId Id of the form + @param FormBuffer Pointer of the form created + @param StringBuffer Pointer of FormTitil string created - StringBuffer - Pointer of FormSetTitile string created - -Returns: - - EFI_OUT_OF_RESOURCES - No enough buffer to allocate - - EFI_SUCCESS - Formset successfully created - ---*/ -; - + @retval EFI_SUCCESS Form successfully created +**/ EFI_STATUS CreateForm ( IN CHAR16 *FormTitle, IN UINT16 FormId, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: + ); - Create a form - -Arguments: - - FormTitle - Title of the form - - FormId - Id of the form +/** + Create a SubTitle - FormBuffer - Pointer of the form created + Subtitle strings are intended to be used by authors to separate sections of questions into semantic + groups. - StringBuffer - Pointer of FormTitil string created + @param SubTitle Sub title to be created + @param FormBuffer Where this subtitle to add to + @param StringBuffer String buffer created for subtitle -Returns: - - EFI_SUCCESS - Form successfully created - ---*/ -; - + @retval EFI_SUCCESS Subtitle successfully created +**/ EFI_STATUS CreateSubTitle ( IN CHAR16 *SubTitle, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: - - Create a SubTitle - -Arguments: - - SubTitle - Sub title to be created - - FormBuffer - Where this subtitle to add to - - StringBuffer - String buffer created for subtitle - -Returns: - - EFI_SUCCESS - Subtitle successfully created - ---*/ -; + ); +/** + Create a line of text + Unlike HTML, text is simply another tag. + This tag type enables IFR to be more easily localized. + + @param String First string of the text + @param String2 Second string of the text + @param String3 Help string of the text + @param Flags Flag of the text + @param Key Key of the text + @param FormBuffer The form where this text adds to + @param StringBuffer String buffer created for String, String2 and String3 + + @retval EFI_SUCCESS Text successfully created +**/ EFI_STATUS CreateText ( IN CHAR16 *String, @@ -214,66 +172,42 @@ CreateText ( IN UINT16 Key, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ + ); -Routine Description: - - Create a line of text - -Arguments: - - String - First string of the text - - String2 - Second string of the text - - String3 - Help string of the text - - Flags - Flag of the text +/** + Create a hyperlink. - Key - Key of the text + @param FormId Form ID of the hyperlink + @param Prompt Prompt of the hyperlink + @param FormBuffer The form where this hyperlink adds to + @param StringBuffer String buffer created for Prompt - FormBuffer - The form where this text adds to - - StringBuffer - String buffer created for String, String2 and String3 - -Returns: - - EFI_SUCCESS - Text successfully created - ---*/ -; - + @retval EFI_SUCCESS Hyperlink successfully created +**/ EFI_STATUS CreateGoto ( IN UINT16 FormId, IN CHAR16 *Prompt, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: - - Create a hyperlink - -Arguments: - - FormId - Form ID of the hyperlink - - Prompt - Prompt of the hyperlink - - FormBuffer - The form where this hyperlink adds to - - StringBuffer - String buffer created for Prompt - -Returns: - - EFI_SUCCESS - Hyperlink successfully created + ); ---*/ -; +/** + Create a one-of question with a set of options to choose from. The + OptionsList is a pointer to a null-terminated list of option descriptions. + @param QuestionId Question ID of the one-of box + @param DataWidth DataWidth of the one-of box + @param Prompt Prompt of the one-of box + @param Help Help of the one-of box + @param OptionsList Each string in it is an option of the one-of box + @param OptionCount Option string count + @param FormBuffer The form where this one-of box adds to + @param StringBuffer String buffer created for Prompt, Help and Option strings + + @retval EFI_DEVICE_ERROR DataWidth > 2 + @retval EFI_SUCCESS One-Of box successfully created. +**/ EFI_STATUS CreateOneOf ( IN UINT16 QuestionId, @@ -284,41 +218,23 @@ CreateOneOf ( IN UINTN OptionCount, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: + ); +/** Create a one-of question with a set of options to choose from. The OptionsList is a pointer to a null-terminated list of option descriptions. -Arguments: - - QuestionId - Question ID of the one-of box - - DataWidth - DataWidth of the one-of box - - Prompt - Prompt of the one-of box - - Help - Help of the one-of box - - OptionsList - Each string in it is an option of the one-of box - - OptionCount - Option string count - - FormBuffer - The form where this one-of box adds to - - StringBuffer - String buffer created for Prompt, Help and Option strings + @param QuestionId Question ID of the ordered list + @param MaxEntries MaxEntries of the ordered list + @param Prompt Prompt of the ordered list + @param Help Help of the ordered list + @param OptionsList Each string in it is an option of the ordered list + @param OptionCount Option string count + @param FormBuffer The form where this ordered list adds to + @param StringBuffer String buffer created for Prompt, Help and Option strings -Returns: - - EFI_DEVICE_ERROR - DataWidth > 2 - - EFI_SUCCESS - One-Of box successfully created. - ---*/ -; - + @retval EFI_SUCCESS Ordered list successfully created. +**/ EFI_STATUS CreateOrderedList ( IN UINT16 QuestionId, @@ -329,39 +245,22 @@ CreateOrderedList ( IN UINTN OptionCount, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: + ); - Create a one-of question with a set of options to choose from. The - OptionsList is a pointer to a null-terminated list of option descriptions. - -Arguments: - - QuestionId - Question ID of the ordered list - - MaxEntries - MaxEntries of the ordered list - - Prompt - Prompt of the ordered list - - Help - Help of the ordered list - - OptionsList - Each string in it is an option of the ordered list - - OptionCount - Option string count - - FormBuffer - The form where this ordered list adds to +/** + Create a checkbox - StringBuffer - String buffer created for Prompt, Help and Option strings + @param QuestionId Question ID of the check box + @param DataWidth DataWidth of the check box + @param Prompt Prompt of the check box + @param Help Help of the check box + @param Flags Flags of the check box + @param FormBuffer The form where this check box adds to + @param StringBuffer String buffer created for Prompt and Help. -Returns: - - EFI_SUCCESS - Ordered list successfully created. - ---*/ -; - + @retval EFI_DEVICE_ERROR DataWidth > 1 + @retval EFI_SUCCESS Check box successfully created +**/ EFI_STATUS CreateCheckBox ( IN UINT16 QuestionId, @@ -371,38 +270,27 @@ CreateCheckBox ( IN UINT8 Flags, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: + ); - Create a checkbox - -Arguments: - - QuestionId - Question ID of the check box - - DataWidth - DataWidth of the check box - - Prompt - Prompt of the check box - - Help - Help of the check box - - Flags - Flags of the check box - - FormBuffer - The form where this check box adds to - - StringBuffer - String buffer created for Prompt and Help. +/** + Create a numeric -Returns: - - EFI_DEVICE_ERROR - DataWidth > 1 - - EFI_SUCCESS - Check box successfully created - ---*/ -; - + @param QuestionId Question ID of the numeric + @param DataWidth DataWidth of the numeric + @param Prompt Prompt of the numeric + @param Help Help of the numeric + @param Minimum Minumun boundary of the numeric + @param Maximum Maximum boundary of the numeric + @param Step Step of the numeric + @param Default Default value + @param Flags Flags of the numeric + @param Key Key of the numeric + @param FormBuffer The form where this numeric adds to + @param StringBuffer String buffer created for Prompt and Help. + + @retval EFI_DEVICE_ERROR DataWidth > 2 + @retval EFI_SUCCESS Numeric is successfully created +**/ EFI_STATUS CreateNumeric ( IN UINT16 QuestionId, @@ -417,48 +305,23 @@ CreateNumeric ( IN UINT16 Key, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: - - Create a numeric - -Arguments: - - QuestionId - Question ID of the numeric - - DataWidth - DataWidth of the numeric - - Prompt - Prompt of the numeric - - Help - Help of the numeric - - Minimum - Minumun boundary of the numeric - - Maximum - Maximum boundary of the numeric - - Step - Step of the numeric - - Default - Default value - - Flags - Flags of the numeric - - Key - Key of the numeric - - FormBuffer - The form where this numeric adds to - - StringBuffer - String buffer created for Prompt and Help. - -Returns: - - EFI_DEVICE_ERROR - DataWidth > 2 - - EFI_SUCCESS - Numeric is successfully created - ---*/ -; - + ); + +/** + Create a string. + + @param QuestionId Question ID of the string + @param DataWidth DataWidth of the string + @param Prompt Prompt of the string + @param Help Help of the string + @param MinSize Min size boundary of the string + @param MaxSize Max size boundary of the string + @param Flags Flags of the string + @param Key Key of the string + @param FormBuffer The form where this string adds to + @param StringBuffer String buffer created for Prompt and Help. + @retval EFI_SUCCESS String successfully created. +**/ EFI_STATUS CreateString ( IN UINT16 QuestionId, @@ -471,128 +334,79 @@ CreateString ( IN UINT16 Key, IN OUT VOID *FormBuffer, IN OUT VOID *StringBuffer - ) -/*++ - -Routine Description: - - Create a string - -Arguments: + ); - QuestionId - Question ID of the string - - DataWidth - DataWidth of the string - - Prompt - Prompt of the string - - Help - Help of the string - - MinSize - Min size boundary of the string - - MaxSize - Max size boundary of the string - - Flags - Flags of the string - - Key - Key of the string +/** + Extract information pertaining to the HiiHandle. - FormBuffer - The form where this string adds to + @param HiiHandle Hii handle + @param ImageLength For input, length of DefaultImage; + For output, length of actually required + @param DefaultImage Image buffer prepared by caller + @param Guid Guid information about the form - StringBuffer - String buffer created for Prompt and Help. - -Returns: - - EFI_SUCCESS - String successfully created. - ---*/ -; - + @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate + @retval EFI_BUFFER_TOO_SMALL DefualtImage has no enough ImageLength + @retval EFI_SUCCESS Successfully extract data from Hii database. +**/ EFI_STATUS ExtractDataFromHiiHandle ( - IN FRAMEWORK_EFI_HII_HANDLE HiiHandle, + IN FRAMEWORK_EFI_HII_HANDLE HiiHandle, IN OUT UINT16 *ImageLength, OUT UINT8 *DefaultImage, OUT EFI_GUID *Guid - ) -/*++ - -Routine Description: + ); - Extract information pertaining to the HiiHandle - -Arguments: - - HiiHandle - Hii handle - - ImageLength - For input, length of DefaultImage; - For output, length of actually required - - DefaultImage - Image buffer prepared by caller - - Guid - Guid information about the form - -Returns: - - EFI_OUT_OF_RESOURCES - No enough buffer to allocate - - EFI_BUFFER_TOO_SMALL - DefualtImage has no enough ImageLength - - EFI_SUCCESS - Successfully extract data from Hii database. - +/** + Finds HII handle for given pack GUID previously registered with the HII. ---*/ -; + @param HiiProtocol pointer to pointer to HII protocol interface. + If NULL, the interface will be found but not returned. + If it points to NULL, the interface will be found and + written back to the pointer that is pointed to. + @param Guid The GUID of the pack that registered with the HII. + @return Handle to the HII pack previously registered by the memory driver. +**/ FRAMEWORK_EFI_HII_HANDLE FindHiiHandle ( IN OUT EFI_HII_PROTOCOL **HiiProtocol, OPTIONAL IN EFI_GUID *Guid - ) -/*++ - -Routine Description: - Finds HII handle for given pack GUID previously registered with the HII. - -Arguments: - HiiProtocol - pointer to pointer to HII protocol interface. - If NULL, the interface will be found but not returned. - If it points to NULL, the interface will be found and - written back to the pointer that is pointed to. - Guid - The GUID of the pack that registered with the HII. - -Returns: - Handle to the HII pack previously registered by the memory driver. - ---*/ -; + ); +/** + Create a SubTitle opcode independent of string creation + This is used primarily by users who need to create just one particular valid op-code and the string + data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label + location to pre-defined forms in HII) + + @param StringToken StringToken of the subtitle + @param FormBuffer Output of subtitle as a form + + @retval EFI_SUCCESS Subtitle created to be a form +**/ EFI_STATUS CreateSubTitleOpCode ( IN STRING_REF StringToken, IN OUT VOID *FormBuffer - ) -/*++ - -Routine Description: + ); - Create a SubTitle opcode independent of string creation +/** + Create a Text opcode independent of string creation. + This is used primarily by users who need to create just one particular valid op-code and the string data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label location to pre-defined forms in HII) - -Arguments: - StringToken - StringToken of the subtitle - - FormBuffer - Output of subtitle as a form - -Returns: - - EFI_SUCCESS - Subtitle created to be a form - ---*/ -; + @param StringToken First string token of the text + @param StringTokenTwo Second string token of the text + @param StringTokenThree Help string token of the text + @param Flags Flag of the text + @param Key Key of the text + @param FormBuffer Output of text as a form + @retval EFI_SUCCESS Text created to be a form +**/ EFI_STATUS CreateTextOpCode ( IN STRING_REF StringToken, @@ -601,37 +415,24 @@ CreateTextOpCode ( IN UINT8 Flags, IN UINT16 Key, IN OUT VOID *FormBuffer - ) -/*++ - -Routine Description: + ); - Create a Text opcode independent of string creation +/** + Create a hyperlink opcode independent of string creation. + This is used primarily by users who need to create just one particular valid op-code and the string data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label location to pre-defined forms in HII) -Arguments: - - StringToken - First string token of the text - - StringTokenTwo - Second string token of the text - - StringTokenThree - Help string token of the text - - Flags - Flag of the text - - Key - Key of the text - - FormBuffer - Output of text as a form - -Returns: - - EFI_SUCCESS - Text created to be a form - ---*/ -; + @param FormId Form ID of the hyperlink + @param StringToken Prompt string token of the hyperlink + @param StringTokenTwo Help string token of the hyperlink + @param Flags Flags of the hyperlink + @param Key Key of the hyperlink + @param FormBuffer Output of hyperlink as a form + @retval EFI_SUCCESS Hyperlink created to be a form +**/ EFI_STATUS CreateGotoOpCode ( IN UINT16 FormId, @@ -640,37 +441,29 @@ CreateGotoOpCode ( IN UINT8 Flags, IN UINT16 Key, IN OUT VOID *FormBuffer - ) -/*++ + ); -Routine Description: - - Create a hyperlink opcode independent of string creation +/** + Create a one-of opcode with a set of option op-codes to choose from independent of string creation. This is used primarily by users who need to create just one particular valid op-code and the string data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label location to pre-defined forms in HII) - -Arguments: - FormId - Form ID of the hyperlink - - StringToken - Prompt string token of the hyperlink - - StringTokenTwo - Help string token of the hyperlink - - Flags - Flags of the hyperlink - - Key - Key of the hyperlink + OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken + has been filled in since this routine will not generate StringToken values. - FormBuffer - Output of hyperlink as a form + @param QuestionId Question ID of the one-of box + @param DataWidth DataWidth of the one-of box + @param PromptToken Prompt string token of the one-of box + @param HelpToken Help string token of the one-of box + @param OptionsList Each string in it is an option of the one-of box + @param OptionCount Option string count + @param FormBuffer Output of One-Of box as a form -Returns: - - EFI_SUCCESS - Hyperlink created to be a form - ---*/ -; + @retval EFI_SUCCESS One-Of box created to be a form + @retval EFI_DEVICE_ERROR DataWidth > 2 +**/ EFI_STATUS CreateOneOfOpCode ( IN UINT16 QuestionId, @@ -680,12 +473,10 @@ CreateOneOfOpCode ( IN IFR_OPTION *OptionsList, IN UINTN OptionCount, IN OUT VOID *FormBuffer - ) -/*++ + ); -Routine Description: - - Create a one-of opcode with a set of option op-codes to choose from independent of string creation. +/** + Create a ordered list opcode with a set of option op-codes to choose from independent of string creation. This is used primarily by users who need to create just one particular valid op-code and the string data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label location to pre-defined forms in HII) @@ -693,31 +484,16 @@ Routine Description: OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken has been filled in since this routine will not generate StringToken values. -Arguments: - - QuestionId - Question ID of the one-of box - - DataWidth - DataWidth of the one-of box + @param QuestionId Question ID of the ordered list + @param MaxEntries MaxEntries of the ordered list + @param PromptToken Prompt string token of the ordered list + @param HelpToken Help string token of the ordered list + @param OptionsList Each string in it is an option of the ordered list + @param OptionCount Option string count + @param FormBuffer Output of ordered list as a form - PromptToken - Prompt string token of the one-of box - - HelpToken - Help string token of the one-of box - - OptionsList - Each string in it is an option of the one-of box - - OptionCount - Option string count - - FormBuffer - Output of One-Of box as a form - -Returns: - - EFI_SUCCESS - One-Of box created to be a form - - EFI_DEVICE_ERROR - DataWidth > 2 - ---*/ -; - + @retval EFI_SUCCESS Ordered list created to be a form +**/ EFI_STATUS CreateOrderedListOpCode ( IN UINT16 QuestionId, @@ -727,42 +503,25 @@ CreateOrderedListOpCode ( IN IFR_OPTION *OptionsList, IN UINTN OptionCount, IN OUT VOID *FormBuffer - ) -/*++ - -Routine Description: + ); - Create a ordered list opcode with a set of option op-codes to choose from independent of string creation. +/** + Create a checkbox opcode independent of string creation This is used primarily by users who need to create just one particular valid op-code and the string data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label location to pre-defined forms in HII) - OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken - has been filled in since this routine will not generate StringToken values. - -Arguments: - - QuestionId - Question ID of the ordered list - - MaxEntries - MaxEntries of the ordered list - - PromptToken - Prompt string token of the ordered list - - HelpToken - Help string token of the ordered list - - OptionsList - Each string in it is an option of the ordered list - - OptionCount - Option string count - - FormBuffer - Output of ordered list as a form - -Returns: - - EFI_SUCCESS - Ordered list created to be a form - ---*/ -; + @param QuestionId Question ID of the check box + @param DataWidth DataWidth of the check box + @param PromptToken Prompt string token of the check box + @param HelpToken Help string token of the check box + @param Flags Flags of the check box + @param Key Key of the check box + @param FormBuffer Output of the check box as a form + @retval EFI_SUCCESS Checkbox created to be a form + @retval EFI_DEVICE_ERROR DataWidth > 1 +**/ EFI_STATUS CreateCheckBoxOpCode ( IN UINT16 QuestionId, @@ -772,41 +531,30 @@ CreateCheckBoxOpCode ( IN UINT8 Flags, IN UINT16 Key, IN OUT VOID *FormBuffer - ) -/*++ - -Routine Description: + ); - Create a checkbox opcode independent of string creation +/** + Create a numeric opcode independent of string creation. This is used primarily by users who need to create just one particular valid op-code and the string data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label location to pre-defined forms in HII) -Arguments: - - QuestionId - Question ID of the check box - - DataWidth - DataWidth of the check box - - PromptToken - Prompt string token of the check box - - HelpToken - Help string token of the check box - - Flags - Flags of the check box - - Key - Key of the check box - - FormBuffer - Output of the check box as a form - -Returns: - - EFI_SUCCESS - Checkbox created to be a form - - EFI_DEVICE_ERROR - DataWidth > 1 - ---*/ -; - + @param QuestionId Question ID of the numeric + @param DataWidth DataWidth of the numeric + @param PromptToken Prompt string token of the numeric + @param HelpToken Help string token of the numeric + @param Minimum Minumun boundary of the numeric + @param Maximum Maximum boundary of the numeric + @param Step Step of the numeric + @param Default Default value of the numeric + @param Flags Flags of the numeric + @param Key Key of the numeric + @param FormBuffer Output of the numeric as a form + + + @retval EFI_SUCCESS The numeric created to be a form. + @retval EFI_DEVICE_ERROR DataWidth > 2 +**/ EFI_STATUS CreateNumericOpCode ( IN UINT16 QuestionId, @@ -820,49 +568,26 @@ CreateNumericOpCode ( IN UINT8 Flags, IN UINT16 Key, IN OUT VOID *FormBuffer - ) -/*++ - -Routine Description: + ); +/** Create a numeric opcode independent of string creation This is used primarily by users who need to create just one particular valid op-code and the string data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label location to pre-defined forms in HII) -Arguments: - - QuestionId - Question ID of the numeric - - DataWidth - DataWidth of the numeric - - PromptToken - Prompt string token of the numeric - - HelpToken - Help string token of the numeric - - Minimum - Minumun boundary of the numeric - - Maximum - Maximum boundary of the numeric - - Step - Step of the numeric - - Default - Default value of the numeric - - Flags - Flags of the numeric - - Key - Key of the numeric - - FormBuffer - Output of the numeric as a form - -Returns: - - EFI_SUCCESS - The numeric created to be a form. - - EFI_DEVICE_ERROR - DataWidth > 2 - ---*/ -; - + @param QuestionId Question ID of the string + @param DataWidth DataWidth of the string + @param PromptToken Prompt token of the string + @param HelpToken Help token of the string + @param MinSize Min size boundary of the string + @param MaxSize Max size boundary of the string + @param Flags Flags of the string + @param Key Key of the string + @param FormBuffer Output of the string as a form + + @retval EFI_SUCCESS String created to be a form. +**/ EFI_STATUS CreateStringOpCode ( IN UINT16 QuestionId, @@ -874,240 +599,148 @@ CreateStringOpCode ( IN UINT8 Flags, IN UINT16 Key, IN OUT VOID *FormBuffer - ) -/*++ - -Routine Description: - - Create a numeric opcode independent of string creation - This is used primarily by users who need to create just one particular valid op-code and the string - data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label - location to pre-defined forms in HII) - -Arguments: + ); - QuestionId - Question ID of the string - - DataWidth - DataWidth of the string - - PromptToken - Prompt token of the string - - HelpToken - Help token of the string - - MinSize - Min size boundary of the string - - MaxSize - Max size boundary of the string - - Flags - Flags of the string - - Key - Key of the string - - FormBuffer - Output of the string as a form - -Returns: - - EFI_SUCCESS - String created to be a form. +/** + Validate that the data associated with the HiiHandle in NVRAM is within + the reasonable parameters for that FormSet. Values for strings and passwords + are not verified due to their not having the equivalent of valid range settings. ---*/ -; + @param HiiHandle Handle of the HII database entry to query + @param Results If return Status is EFI_SUCCESS, Results provides valid data + TRUE = NVRAM Data is within parameters + FALSE = NVRAM Data is NOT within parameters + @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate + @retval EFI_SUCCESS Data successfully validated +**/ EFI_STATUS ValidateDataFromHiiHandle ( IN FRAMEWORK_EFI_HII_HANDLE HiiHandle, OUT BOOLEAN *Results - ) -/*++ - -Routine Description: + ); - Validate that the data associated with the HiiHandle in NVRAM is within - the reasonable parameters for that FormSet. Values for strings and passwords - are not verified due to their not having the equivalent of valid range settings. - -Arguments: - - HiiHandle - Handle of the HII database entry to query - - Results - If return Status is EFI_SUCCESS, Results provides valid data - TRUE = NVRAM Data is within parameters - FALSE = NVRAM Data is NOT within parameters - -Returns: - - EFI_OUT_OF_RESOURCES - No enough buffer to allocate +/** + Create a banner opcode. This is primarily used by the FrontPage implementation from BDS. - EFI_SUCCESS - Data successfully validated ---*/ -; + @param Title Title of the banner + @param LineNumber LineNumber of the banner + @param Alignment Alignment of the banner + @param FormBuffer Output of banner as a form + @retval EFI_SUCCESS Banner created to be a form. +**/ EFI_STATUS CreateBannerOpCode ( IN UINT16 Title, IN UINT16 LineNumber, IN UINT8 Alignment, IN OUT VOID *FormBuffer - ) -/*++ - -Routine Description: - - Create a banner opcode. This is primarily used by the FrontPage implementation from BDS. - -Arguments: - - Title - Title of the banner - - LineNumber - LineNumber of the banner - - Alignment - Alignment of the banner - - FormBuffer - Output of banner as a form - -Returns: - - EFI_SUCCESS - Banner created to be a form. - ---*/ -; + ); + +/** + Extracts a variable form a Pack. + @param Pack List of variables + @param Name Name of the variable/map + @param Guid GUID of the variable/map + @param Id The index of the variable/map to retrieve + @param Var Pointer to the variable/map + @param Size Size of the variable/map in bytes +**/ VOID EfiLibHiiVariablePackGetMap ( - IN EFI_HII_VARIABLE_PACK *Pack, - OUT CHAR16 **Name, OPTIONAL - OUT EFI_GUID **Guid, OPTIONAL - OUT UINT16 *Id, OPTIONAL - OUT VOID **Var, OPTIONAL - OUT UINTN *Size OPTIONAL - ) -/*++ - -Routine Description: - - Extracts a variable form a Pack. - -Arguments: - - Pack - List of variables - Name - Name of the variable/map - Guid - GUID of the variable/map - Var - Pointer to the variable/map - Size - Size of the variable/map in bytes - -Returns: - - VOID. + IN EFI_HII_VARIABLE_PACK *Pack, + OUT CHAR16 **Name, OPTIONAL + OUT EFI_GUID **Guid, OPTIONAL + OUT UINT16 *Id, OPTIONAL + OUT VOID **Var, OPTIONAL + OUT UINTN *Size OPTIONAL + ); + +/** + Finds a count of the variables/maps in the List. ---*/ -; + @param List List of variables + @return The number of map count. +**/ UINTN EfiLibHiiVariablePackListGetMapCnt ( IN EFI_HII_VARIABLE_PACK_LIST *List - ) -/*++ - -Routine Description: - - Finds a count of the variables/maps in the List. - -Arguments: - - List - List of variables - -Returns: - - Number of Map in the variable pack list. - ---*/ -; - -typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK) ( - IN CHAR16 *Name, - IN EFI_GUID *Guid, - IN UINT16 Id, - IN VOID *Var, - IN UINTN Size - ) -/*++ - -Routine Description: - + ); + +/** type definition for the callback to be used with EfiLibHiiVariablePackListForEachVar(). -Arguments: - - Id - Variable/Map ID - Name - Name of the variable/map - Guid - GUID of the variable/map - Var - Pointer to the variable/map - Size - Size of the variable/map in bytes - -Returns: - - VOID - ---*/ -; + @param Id Variable/Map ID + @param Name Name of the variable/map + @param Guid GUID of the variable/map + @param Var Pointer to the variable/map + @param Size Size of the variable/map in bytes +**/ +typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK) ( + IN CHAR16 *Name, + IN EFI_GUID *Guid, + IN UINT16 Id, + IN VOID *Var, + IN UINTN Size + ); + +/** + Will iterate all variable/maps as appearing + in List and for each, it will call the Callback. + @param List List of variables + @param Callback Routine to be called for each iterated variable. +**/ VOID EfiLibHiiVariablePackListForEachVar ( IN EFI_HII_VARIABLE_PACK_LIST *List, IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK *Callback - ) -/*++ - -Routine Description: - - Will iterate all variable/maps as appearing - in List and for each, it will call the Callback. - -Arguments: - - List - List of variables - Callback - Routine to be called for each iterated variable. - -Returns: - - VOID + ); + +/** + Finds a variable form List given + the order number as appears in the List. ---*/ -; + @param Idx The index of the variable/map to retrieve + @param List List of variables + @param Name Name of the variable/map + @param Guid GUID of the variable/map + @param Id Id of the variable/map + @param Var Pointer to the variable/map + @param Size Size of the variable/map in bytes + @return EFI_SUCCESS Variable is found, OUT parameters are valid + @return EFI_NOT_FOUND Variable is not found, OUT parameters are not valid +**/ EFI_STATUS EfiLibHiiVariablePackListGetMapByIdx ( IN UINTN Idx, IN EFI_HII_VARIABLE_PACK_LIST *List, OUT CHAR16 **Name, OPTIONAL OUT EFI_GUID **Guid, OPTIONAL - OUT UINT16 *Id, OPTIONAL + OUT UINT16 *Id, OPTIONAL OUT VOID **Var, OUT UINTN *Size - ) -/*++ - -Routine Description: - - Finds a variable form List given - the order number as appears in the List. - -Arguments: - - Idx - The index of the variable/map to retrieve - List - List of variables - Name - Name of the variable/map - Guid - GUID of the variable/map - Var - Pointer to the variable/map - Size - Size of the variable/map in bytes - -Returns: - - EFI_SUCCESS - Variable is found, OUT parameters are valid - EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid + ); + +/** + Finds a variable form List given the + order number as appears in the List. ---*/ -; + @param Id The ID of the variable/map to retrieve + @param List List of variables + @param Name Name of the variable/map + @param Guid GUID of the variable/map + @param Var Pointer to the variable/map + @param Size Size of the variable/map in bytes + @retval EFI_SUCCESS Variable is found, OUT parameters are valid + @retval EFI_NOT_FOUND Variable is not found, OUT parameters are not valid +**/ EFI_STATUS EfiLibHiiVariablePackListGetMapById ( IN UINT16 Id, @@ -1116,31 +749,21 @@ EfiLibHiiVariablePackListGetMapById ( OUT EFI_GUID **Guid, OPTIONAL OUT VOID **Var, OUT UINTN *Size - ) -/*++ - -Routine Description: - - Finds a variable form List given the - order number as appears in the List. - -Arguments: - - Id - The ID of the variable/map to retrieve - List - List of variables - Name - Name of the variable/map - Guid - GUID of the variable/map - Var - Pointer to the variable/map - Size - Size of the variable/map in bytes + ); -Returns: - - EFI_SUCCESS - Variable is found, OUT parameters are valid - EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid +/** + Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID. ---*/ -; + @param List List of variables + @param Name Name of the variable/map to be found + @param Guid GUID of the variable/map to be found + @param Id Id of the variable/map to be found + @param Var Pointer to the variable/map found + @param Size Size of the variable/map in bytes found + @retval EFI_SUCCESS variable is found, OUT parameters are valid + @retval EFI_NOT_FOUND variable is not found, OUT parameters are not valid +**/ EFI_STATUS EfiLibHiiVariablePackListGetMap ( IN EFI_HII_VARIABLE_PACK_LIST *List, @@ -1149,118 +772,83 @@ EfiLibHiiVariablePackListGetMap ( OUT UINT16 *Id, OUT VOID **Var, OUT UINTN *Size - ) -/*++ - -Routine Description: - - Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID. - -Arguments: + ); - List - List of variables - Name - Name of the variable/map to be found - Guid - GUID of the variable/map to be found - Var - Pointer to the variable/map found - Size - Size of the variable/map in bytes found - -Returns: - - EFI_SUCCESS - variable is found, OUT parameters are valid - EFI_NOT_FOUND - variable is not found, OUT parameters are not valid +/** + Finds out if a variable of specific Name/Guid/Size exists in NV. + If it does, it will retrieve it into the Var. ---*/ -; + @param Name Parameters of the variable to retrieve. Must match exactly. + @param Guid Parameters of the variable to retrieve. Must match exactly. + @param Size Parameters of the variable to retrieve. Must match exactly. + @param Var Variable will be retrieved into buffer pointed by this pointer. + If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer. + @retval EFI_SUCCESS The variable of exact Name/Guid/Size parameters was retrieved and written to Var. + @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV. + @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error. +**/ EFI_STATUS EfiLibHiiVariableRetrieveFromNv ( IN CHAR16 *Name, IN EFI_GUID *Guid, IN UINTN Size, OUT VOID **Var - ) -/*++ - -Routine Description: - Finds out if a variable of specific Name/Guid/Size exists in NV. - If it does, it will retrieve it into the Var. - -Arguments: - Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly. - Var - Variable will be retrieved into buffer pointed by this pointer. - If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer. -Returns: - EFI_SUCCESS - The variable of exact Name/Guid/Size parameters was retrieved and written to Var. - EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV. - EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error. - ---*/ -; - -//// -//// Variable override support. -//// - -EFI_STATUS -EfiLibHiiVariableOverrideIfSuffix ( - IN CHAR16 *Suffix, - IN CHAR16 *Name, - IN EFI_GUID *Guid, - IN UINTN Size, - OUT VOID *Var - ) -/*++ + ); -Routine Description: +/** Overrrides the variable with NV data if found. But it only does it if the Name ends with specified Suffix. For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride", the Suffix matches the end of Name, so the variable will be loaded from NV provided the variable exists and the GUID and Size matches. -Arguments: - Suffix - Suffix the Name should end with. - Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly. - Var - Variable will be retrieved into this buffer. - Caller is responsible for providing storage of exactly Size size in bytes. -Returns: - EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size. - EFI_INVALID_PARAMETER - The name of the variable does not end with . - EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV. - EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error. - ---*/ -; - + @param Suffix Suffix the Name should end with. + @param Name Name of the variable to retrieve. + @Param Guid Guid of the variable to retrieve. + @Param Size Parameters of the variable to retrieve. + @param Var Variable will be retrieved into this buffer. + Caller is responsible for providing storage of exactly Size size in bytes. + + @retval EFI_SUCCESS The variable was overriden with NV variable of same Name/Guid/Size. + @retval EFI_INVALID_PARAMETER The name of the variable does not end with . + @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV. + @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error. +**/ EFI_STATUS -EfiLibHiiVariableOverrideBySuffix ( +EfiLibHiiVariableOverrideIfSuffix ( IN CHAR16 *Suffix, IN CHAR16 *Name, IN EFI_GUID *Guid, IN UINTN Size, OUT VOID *Var - ) -/*++ + ); -Routine Description: +/** Overrrides the variable with NV data if found. But it only does it if the NV contains the same variable with Name is appended with Suffix. For example, if Suffix="MyOverride" and the Name="XyzSetup", the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride" will be loaded from NV provided the variable exists and the GUID and Size matches. -Arguments: - Suffix - Suffix the variable will be appended with. - Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly. - Var - Variable will be retrieved into this buffer. - Caller is responsible for providing storage of exactly Size size in bytes. + @param Suffix Suffix the variable will be appended with. + @param Name Parameters of the Name variable to retrieve. + @param Guid Parameters of the Guid variable to retrieve. + @param Size Parameters of the Size variable to retrieve. + @param Var Variable will be retrieved into this buffer. + Caller is responsible for providing storage of exactly Size size in bytes. -Returns: - EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size. - EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV. - EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error. - ---*/ -; + @retval EFI_SUCCESS The variable was overriden with NV variable of same Name/Guid/Size. + @retval EFI_NOT_FOUND The variable of this Name/Guid was not found in the NV. + @retval EFI_LOAD_ERROR The variable in the NV was of different size, or NV API returned error. +**/ +EFI_STATUS +EfiLibHiiVariableOverrideBySuffix ( + IN CHAR16 *Suffix, + IN CHAR16 *Name, + IN EFI_GUID *Guid, + IN UINTN Size, + OUT VOID *Var + ); #endif -- cgit v1.2.3