From cb7d01c0c9fd199742d0fed6aa69dab0c79c3338 Mon Sep 17 00:00:00 2001 From: rsun3 Date: Tue, 14 Apr 2009 10:47:19 +0000 Subject: HII Library Class interface refine. The "HiiLib" prefix for all HII Library API function names changed to "Hii". Remove: HiiLibPreparePackageList(), replaced by HiiAddPackages() HiiLibNewString(), replaced by HiiSetString() HiiLibGetStringFromHandle(), replaced by HiiGetString() HiiLibGetStringFromToken(), replaced by HiiGetPackageString() HiiLibExtractGuidFromHiiHandle() HiiLibDevicePathToHiiHandle() HiiLibGetSupportedSecondaryLanguages() HiiLibGetSupportedLanguageNumber() HiiLibExportPackageLists() HiiLibListPackageLists() Interface change: HiiAddPackages() HiiSetString() HiiGetString() HiiGetHiiHandles() git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8083 6f19259b-4bc3-4df7-8a09-765794883524 --- MdeModulePkg/Include/Library/HiiLib.h | 496 +++++++++++----------------------- 1 file changed, 157 insertions(+), 339 deletions(-) (limited to 'MdeModulePkg/Include') diff --git a/MdeModulePkg/Include/Library/HiiLib.h b/MdeModulePkg/Include/Library/HiiLib.h index 37b59bf376..730f450fc5 100644 --- a/MdeModulePkg/Include/Library/HiiLib.h +++ b/MdeModulePkg/Include/Library/HiiLib.h @@ -17,281 +17,207 @@ /** - Assemble EFI_HII_PACKAGE_LIST according to the passed in packages. - - If GuidId is NULL, then ASSERT. - If not enough resource to complete the operation, then ASSERT. - - @param NumberOfPackages Number of packages. - @param GuidId Package GUID. - @param ... Variable argument list for packages to be assembled. - - @return Pointer of EFI_HII_PACKAGE_LIST_HEADER. - -**/ -EFI_HII_PACKAGE_LIST_HEADER * -EFIAPI -HiiLibPreparePackageList ( - IN UINTN NumberOfPackages, - IN CONST EFI_GUID *GuidId, - ... - ) -; - -/** - This function allocates pool for an EFI_HII_PACKAGE_LIST structure - with additional space that is big enough to host all packages described by the variable - argument list of package pointers. The allocated structure is initialized using NumberOfPackages, - GuidId, and the variable length argument list of package pointers. - - Then, EFI_HII_PACKAGE_LIST will be register to the default System HII Database. The - Handle to the newly registered Package List is returned throught HiiHandle. + Registers a list of packages in the HII Database and returns the HII Handle + associated with that registration. If an HII Handle has already been registered + with the same PackageListGuid, then NULL is returned. If there are not enough + resources to perform the registration, then NULL is returned. If an empty list + of packages is passed in, then NULL is returned. If the size of the list of + package is 0, then NULL is returned. - If HiiHandle is NULL, then ASSERT. + The variable arguments are pointers which point to package header that defined + by UEFI VFR compiler and StringGather tool. - @param NumberOfPackages The number of HII packages to register. - @param GuidId Package List GUID ID. - @param DriverHandle Optional. If not NULL, the DriverHandle on which an instance of DEVICE_PATH_PROTOCOL is installed. - This DriverHandle uniquely defines the device that the added packages are associated with. - @param HiiHandle On output, the HiiHandle is update with the handle which can be used to retrieve the Package - List later. If the functions failed to add the package to the default HII database, this value will - be set to NULL. - @param ... The variable argument list describing all HII Package. + #pragma pack (push, 1) + typedef struct { + UINT32 BinaryLength; + EFI_HII_PACKAGE_HEADER PackageHeader; + } EDKII_AUTOGEN_PACKAGES_HEADER; + #pragma pack (pop) + + @param[in] PackageListGuid The GUID of the package list. + @param[in] DeviceHandle If not NULL, the Device Handle on which + an instance of DEVICE_PATH_PROTOCOL is installed. + This Device Handle uniquely defines the device that + the added packages are associated with. + @param[in] ... The variable argument list that contains pointers + to packages terminated by a NULL. - @return EFI_SUCCESS If the packages are successfully added to the default HII database. - @return EFI_OUT_OF_RESOURCE Not enough resource to complete the operation. + @retval NULL A HII Handle has already been registered in the HII Database with + the same PackageListGuid. + @retval NULL The HII Handle could not be created. + @retval NULL An empty list of packages was passed in. + @retval NULL All packages are empty. + @retval Other The HII Handle associated with the newly registered package list. **/ -EFI_STATUS +EFI_HII_HANDLE EFIAPI -HiiLibAddPackages ( - IN UINTN NumberOfPackages, - IN CONST EFI_GUID *GuidId, - IN EFI_HANDLE DriverHandle, OPTIONAL - OUT EFI_HII_HANDLE *HiiHandle, +HiiAddPackages ( + IN CONST EFI_GUID *PackageListGuid, + IN EFI_HANDLE DeviceHandle OPTIONAL, ... ) ; /** - Removes a package list from the default HII database. + Removes a package list from the HII database. If HiiHandle is NULL, then ASSERT. - If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT. + If HiiHandle is not a valid EFI_HII_HANDLE in the HII database, then ASSERT. - @param HiiHandle The handle that was previously registered to the data base that is requested for removal. - List later. + @param[in] HiiHandle The handle that was previously registered in the HII database **/ VOID EFIAPI -HiiLibRemovePackages ( +HiiRemovePackages ( IN EFI_HII_HANDLE HiiHandle ) ; /** - This function adds the string into String Package of each language - supported by the package list. - - If String is NULL, then ASSERT. - If StringId is NULL, the ASSERT. - If PackageList could not be found in the default HII database, then ASSERT. - - @param PackageList Handle of the package list where this string will - be added. - @param StringId On return, contains the new strings id, which is - unique within PackageList. - @param String Points to the new null-terminated string. - - @retval EFI_SUCCESS The new string was added successfully. - @retval EFI_OUT_OF_RESOURCES Could not add the string due to lack of resources. - -**/ -EFI_STATUS -EFIAPI -HiiLibNewString ( - IN EFI_HII_HANDLE PackageList, - OUT EFI_STRING_ID *StringId, - IN CONST EFI_STRING String - ) -; - -/** - This function update the specified string in String Package of each language - supported by the package list. - - If String is NULL, then ASSERT. - If PackageList could not be found in the default HII database, then ASSERT. - If StringId is not found in PackageList, then ASSERT. - - @param PackageList Handle of the package list where this string will - be added. - @param StringId Ths String Id to be updated. - @param String Points to the new null-terminated string. - - @retval EFI_SUCCESS The new string was added successfully. - @retval EFI_OUT_OF_RESOURCES Could not add the string due to lack of resources. - -**/ -EFI_STATUS -EFIAPI -HiiLibSetString ( - IN EFI_HII_HANDLE PackageList, - IN EFI_STRING_ID StringId, - IN CONST EFI_STRING String - ) -; - -/** - This function try to retrieve string from String package of current language. - If fails, it try to retrieve string from String package of first language it support. - - If StringSize is NULL, then ASSERT. - If String is NULL and *StringSize is not 0, then ASSERT. - If PackageList could not be found in the default HII database, then ASSERT. - If StringId is not found in PackageList, then ASSERT. - - @param PackageList The package list in the HII database to search for - the specified string. - @param StringId The string's id, which is unique within - PackageList. - @param String Points to the new null-terminated string. - @param StringSize On entry, points to the size of the buffer pointed - to by String, in bytes. On return, points to the - length of the string, in bytes. - - @retval EFI_SUCCESS The string was returned successfully. - @retval EFI_NOT_FOUND The string specified by StringId is not available. - @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringLength is too small - to hold the string. - -**/ -EFI_STATUS -EFIAPI -HiiLibGetString ( - IN EFI_HII_HANDLE PackageList, - IN EFI_STRING_ID StringId, - OUT EFI_STRING String, - IN OUT UINTN *StringSize - ) -; - -/** - Get string specified by StringId form the HiiHandle. The caller - is responsible to free the *String. - - If String is NULL, then ASSERT. - If HiiHandle could not be found in the default HII database, then ASSERT. - If StringId is not found in PackageList, then ASSERT. - - @param HiiHandle The HII handle of package list. - @param StringId The String ID. - @param String The output string. - - @retval EFI_NOT_FOUND String is not found. - @retval EFI_SUCCESS Operation is successful. - @retval EFI_OUT_OF_RESOURCES There is not enought memory in the system. - -**/ -EFI_STATUS -EFIAPI -HiiLibGetStringFromHandle ( - IN EFI_HII_HANDLE HiiHandle, - IN EFI_STRING_ID StringId, - OUT EFI_STRING *String - ) -; - -/** - Get the string given the StringId and String package Producer's Guid. The caller - is responsible to free the *String. - - If PackageList with the matching ProducerGuid is not found, then ASSERT. - If PackageList with the matching ProducerGuid is found but no String is - specified by StringId is found, then ASSERT. + This function create a new string in String Package or updates an existing + string in a String Package. If StringId is 0, then a new string is added to + a String Package. If StringId is not zero, then a string in String Package is + updated. If SupportedLanguages is NULL, then the string is added or updated + for all the languages that the String Package supports. If SupportedLanguages + is not NULL, then the string is added or updated for the set of languages + specified by SupportedLanguages. + + If HiiHandle is NULL, then ASSERT(). + If String is NULL, then ASSERT(). - @param ProducerGuid The Guid of String package list. - @param StringId The String ID. - @param String The output string. + @param[in] HiiHandle A handle that was previously registered in the + HII Database. + @param[in] StringId If zero, then a new string is created in the + String Package associated with HiiHandle. If + non-zero, then the string specified by StringId + is updated in the String Package associated + with HiiHandle. + @param[in] String A pointer to the Null-terminated Unicode string + to add or update in the String Package associated + with HiiHandle. + @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string of + language codes. If this parameter is NULL, then + String is added or updated in the String Package + associated with HiiHandle for all the languages + that the String Package supports. If this + parameter is not NULL, then then String is added + or updated in the String Package associated with + HiiHandle for the set oflanguages specified by + SupportedLanguages. The format of + SupportedLanguages must follow the language + format assumed the HII Database. - @retval EFI_SUCCESS Operation is successful. - @retval EFI_OUT_OF_RESOURCES There is not enought memory in the system. + @retval 0 The string could not be added or updated in the String Package. + @retval Other The EFI_STRING_ID of the newly added or updated string. **/ -EFI_STATUS +EFI_STRING_ID EFIAPI -HiiLibGetStringFromToken ( - IN EFI_GUID *ProducerGuid, - IN EFI_STRING_ID StringId, - OUT EFI_STRING *String +HiiSetString ( + IN EFI_HII_HANDLE HiiHandle, + IN EFI_STRING_ID StringId, OPTIONAL + IN CONST EFI_STRING String, + IN CONST CHAR8 *SupportedLanguages OPTIONAL ) ; /** - Determines the handles that are currently active in the database. - It's the caller's responsibility to free handle buffer. - - If HandleBufferLength is NULL, then ASSERT. - If HiiHandleBuffer is NULL, then ASSERT. + Retrieves a string from a string package in a specific language. If the language + is not specified, then a string from a string package in the current platform + language is retrieved. If the string can not be retrieved using the specified + language or the current platform language, then the string is retrieved from + the string package in the first language the string package supports. The + returned string is allocated using AllocatePool(). The caller is responsible + for freeing the allocated buffer using FreePool(). + + If HiiHandle is NULL, then ASSERT(). + If StringId is 0, then ASSET. - @param HandleBufferLength On input, a pointer to the length of the handle - buffer. On output, the length of the handle buffer - that is required for the handles found. - @param HiiHandleBuffer Pointer to an array of Hii Handles returned. + @param[in] HiiHandle A handle that was previously registered in the HII Database. + @param[in] StringId The identifier of the string to retrieved from the string + package associated with HiiHandle. + @param[in] Language The language of the string to retrieve. If this parameter + is NULL, then the current platform language is used. The + format of Language must follow the language format assumed + the HII Database. - @retval EFI_SUCCESS Get an array of Hii Handles successfully. + @retval NULL The string specified by StringId is not present in the string package. + @retval Other The string was returned. **/ -EFI_STATUS +EFI_STRING EFIAPI -HiiLibGetHiiHandles ( - IN OUT UINTN *HandleBufferLength, - OUT EFI_HII_HANDLE **HiiHandleBuffer +HiiGetString ( + IN EFI_HII_HANDLE HiiHandle, + IN EFI_STRING_ID StringId, + IN CONST CHAR8 *Language OPTIONAL ) ; /** - Extract Hii package list GUID for given HII handle. - - If HiiHandle could not be found in the default HII database, then ASSERT. - If Guid is NULL, then ASSERT. + Retrieves a string from a string package names by GUID in a specific language. + If the language is not specified, then a string from a string package in the + current platform language is retrieved. If the string can not be retrieved + using the specified language or the current platform language, then the string + is retrieved from the string package in the first language the string package + supports. The returned string is allocated using AllocatePool(). The caller + is responsible for freeing the allocated buffer using FreePool(). + + If PackageListGuid is NULL, then ASSERT(). + If StringId is 0, then ASSERT. - @param Handle Hii handle - @param Guid Package list GUID + @param[in] PackageListGuid The GUID of a package list that was previously + registered in the HII Database. + @param[in] StringId The identifier of the string to retrieved from the + string package associated with PackageListGuid. + @param[in] Language The language of the string to retrieve. If this + parameter is NULL, then the current platform + language is used. The format of Language must + follow the language format assumed the HII Database. - @retval EFI_SUCCESS Successfully extract GUID from Hii database. + @retval NULL The package list specified by PackageListGuid is not present in the + HII Database. + @retval NULL The string specified by StringId is not present in the string package. + @retval Other The string was returned. **/ -EFI_STATUS +EFI_STRING EFIAPI -HiiLibExtractGuidFromHiiHandle ( - IN EFI_HII_HANDLE Handle, - OUT EFI_GUID *Guid +HiiGetPackageString ( + IN CONST EFI_GUID *PackageListGuid, + IN EFI_STRING_ID StringId, + IN CONST CHAR8 *Language OPTIONAL ) ; /** - Find HII Handle in the default HII database associated with given Device Path. - - If DevicePath is NULL, then ASSERT. + Retrieves the array of all the HII Handles or the HII handle of a specific + package list in the HII Database. + This array is terminated with a NULL HII Handle. + This function allocates the returned array using AllocatePool(). + The caller is responsible for freeing the array with FreePool(). - @param DevicePath Device Path associated with the HII package list - handle. + @param[in] PackageListGuid An optional parameter that is used to request + an HII Handle that is associatd with a specific + Package List GUID. If this parameter is NULL + then all the HII Handles in the HII Database + are returned. If this parameter is not NULL + then at most 1 HII Handle is returned. - @retval Handle HII package list Handle associated with the Device - Path. - @retval NULL Hii Package list handle is not found. + @retval NULL No HII handles were found in the HII database + @retval NULL The array of HII Handles could not be retrieved + @retval Other A pointer to the NULL terminated array of HII Handles **/ -EFI_HII_HANDLE +EFI_HII_HANDLE * EFIAPI -HiiLibDevicePathToHiiHandle ( - IN EFI_DEVICE_PATH_PROTOCOL *DevicePath +HiiGetHiiHandles ( + IN CONST EFI_GUID *PackageListGuid OPTIONAL ) ; - /** Get next language from language code list (with separator ';'). @@ -313,138 +239,30 @@ HiiLibGetNextLanguage ( ; /** - This function returns the list of supported languages, in the format specified - in UEFI specification Appendix M. - - If HiiHandle is not a valid Handle in the default HII database, then ASSERT. - - @param HiiHandle The HII package list handle. - - @retval !NULL The supported languages. - @retval NULL If Supported Languages can not be retrived. - -**/ -CHAR8 * -EFIAPI -HiiLibGetSupportedLanguages ( - IN EFI_HII_HANDLE HiiHandle - ) -; - -/** - This function returns the list of supported 2nd languages, in the format specified - in UEFI specification Appendix M. - - If HiiHandle is not a valid Handle in the default HII database, then ASSERT. - If not enough resource to complete the operation, then ASSERT. - - @param HiiHandle The HII package list handle. - @param FirstLanguage Pointer to language name buffer. + Retrieves a pointer to the a Null-terminated ASCII string containing the list + of languages that an HII handle in the HII Database supports. The returned + string is allocated using AllocatePool(). The caller is responsible for freeing + the returned string using FreePool(). The format of the returned string follows + the language format assumed the HII Database. - @return The supported languages. - -**/ -CHAR8 * -EFIAPI -HiiLibGetSupportedSecondaryLanguages ( - IN EFI_HII_HANDLE HiiHandle, - IN CONST CHAR8 *FirstLanguage - ) -; - - -/** - This function returns the number of supported languages on HiiHandle. - - If HiiHandle is not a valid Handle in the default HII database, then ASSERT. - If not enough resource to complete the operation, then ASSERT. + If HiiHandle is NULL, then ASSERT(). - @param HiiHandle The HII package list handle. + @param[in] HiiHandle A handle that was previously registered in the HII Database. - @return The number of supported languages. + @retval NULL HiiHandle is not registered in the HII database + @retval NULL There are not enough resources available to retrieve the suported + languages. + @retval NULL The list of suported languages could not be retrieved. + @retval Other A pointer to the Null-terminated ASCII string of supported languages. **/ -UINT16 +CHAR8 * EFIAPI -HiiLibGetSupportedLanguageNumber ( +HiiGetSupportedLanguages ( IN EFI_HII_HANDLE HiiHandle ) ; -/** - Exports the contents of one or all package lists in the HII database into a buffer. - - If Handle is not NULL and not a valid EFI_HII_HANDLE registered in the database, - then ASSERT. - If PackageListHeader is NULL, then ASSERT. - If PackageListSize is NULL, then ASSERT. - - @param Handle The HII Handle. - @param PackageListHeader A pointer to a buffer that will contain the results of - the export function. - @param PackageListSize On output, the length of the buffer that is required for the exported data. - - @retval EFI_SUCCESS Package exported. - - @retval EFI_OUT_OF_RESOURCES Not enought memory to complete the operations. - -**/ -EFI_STATUS -EFIAPI -HiiLibExportPackageLists ( - IN EFI_HII_HANDLE Handle, - OUT EFI_HII_PACKAGE_LIST_HEADER **PackageListHeader, - OUT UINTN *PackageListSize - ) -; - -/** - - This function returns a list of the package handles of the - specified type that are currently active in the HII database. The - pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package - handles to be listed. - - If HandleBufferLength is NULL, then ASSERT. - If HandleBuffer is NULL, the ASSERT. - If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is - NULL, then ASSERT. - If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not - NULL, then ASSERT. - - - @param PackageType Specifies the package type of the packages - to list or EFI_HII_PACKAGE_TYPE_ALL for - all packages to be listed. - - @param PackageGuid If PackageType is - EFI_HII_PACKAGE_TYPE_GUID, then this is - the pointer to the GUID which must match - the Guid field of - EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it - must be NULL. - - @param HandleBufferLength On output, the length of the handle buffer - that is required for the handles found. - - @param HandleBuffer On output, an array of EFI_HII_HANDLE instances returned. - The caller is responcible to free this pointer allocated. - - @retval EFI_SUCCESS The matching handles are outputed successfully. - HandleBufferLength is updated with the actual length. - @retval EFI_OUT_OF_RESOURCES Not enough resource to complete the operation. - @retval EFI_NOT_FOUND No matching handle could not be found in database. -**/ -EFI_STATUS -EFIAPI -HiiLibListPackageLists ( - IN UINT8 PackageType, - IN CONST EFI_GUID *PackageGuid, - IN OUT UINTN *HandleBufferLength, - OUT EFI_HII_HANDLE **Handle - ) -; - /** Convert language code from RFC3066 to ISO639-2. -- cgit v1.2.3