X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FHiiString.h;h=b8439c95a6fb3b5bef57d9bf51fe2102a74feec5;hp=e120e9e470e0fc43c813d63d35d8d0621249fd78;hb=9344f0921518309295da89c221d10cbead8531aa;hpb=7d582d6b499ed30268da033cc17fbde6e7b02a9d
diff --git a/MdePkg/Include/Protocol/HiiString.h b/MdePkg/Include/Protocol/HiiString.h
index e120e9e470..b8439c95a6 100644
--- a/MdePkg/Include/Protocol/HiiString.h
+++ b/MdePkg/Include/Protocol/HiiString.h
@@ -1,129 +1,105 @@
/** @file
The file provides services to manipulate string data.
-
- Copyright (c) 2006 - 2007, Intel Corporation
- All rights reserved. This program and the accompanying materials
- are licensed and made available under the terms and conditions of the BSD License
- which accompanies this distribution. The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
+SPDX-License-Identifier: BSD-2-Clause-Patent
+
+ @par Revision Reference:
+ This Protocol was introduced in UEFI Specification 2.1.
**/
#ifndef __HII_STRING_H__
#define __HII_STRING_H__
-#define EFI_HII_STRING_PROTOCOL_GUID \
- { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
-
-#include
#include
+#define EFI_HII_STRING_PROTOCOL_GUID \
+ { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL;
-
-
/**
- This function adds the string String to the group of strings
- owned by PackageList, with the specified font information
- StringFontInfo and returns a new string id.
-
- @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
-
- @param PackageList Handle of the package list where this
- string will be added.
-
- @param Language Points to the language for the new string.
-
- @param String Points to the new null-terminated string.
-
- @param StringFontInfo Points to the new string's font
- information or NULL if the string should
- have the default system font, size and
- style. StringId On return, contains the
- new strings id, which is unique within
- PackageList.
-
- @retval EFI_SUCCESS The new string was added successfully
-
- @retval EFI_OUT_OF_RESOURCES Could not add the string.
-
- @retval EFI_INVALID_PARAMETER String is NULL or StringId is
- NULL or Language is NULL.
-
+ This function adds the string String to the group of strings owned by PackageList, with the
+ specified font information StringFontInfo, and returns a new string id.
+ The new string identifier is guaranteed to be unique within the package list.
+ That new string identifier is reserved for all languages in the package list.
+
+ @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
+ @param PackageList The 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 Language Points to the language for the new string.
+ @param LanguageName Points to the printable language name to associate
+ with the passed in Language field.If LanguageName
+ is not NULL and the string package header's
+ LanguageName associated with a given Language is
+ not zero, the LanguageName being passed in will
+ be ignored.
+ @param String Points to the new null-terminated string.
+ @param StringFontInfo Points to the new string's font information or
+ NULL if the string should have the default system
+ font, size and style.
+
+ @retval EFI_SUCCESS The new string was added successfully.
+ @retval EFI_NOT_FOUND The specified PackageList could not be found in
+ database.
+ @retval EFI_OUT_OF_RESOURCES Could not add the string due to lack of resources.
+ @retval EFI_INVALID_PARAMETER String is NULL, or StringId is NULL, or Language is NULL.
+ @retval EFI_INVALID_PARAMETER The specified StringFontInfo does not exist in
+ current database.
**/
typedef
EFI_STATUS
-(EFIAPI *EFI_HII_NEW_STRING) (
+(EFIAPI *EFI_HII_NEW_STRING)(
IN CONST EFI_HII_STRING_PROTOCOL *This,
IN EFI_HII_HANDLE PackageList,
OUT EFI_STRING_ID *StringId,
IN CONST CHAR8 *Language,
- IN CONST CHAR16 *LanguageName, OPTIONAL
+ IN CONST CHAR16 *LanguageName, OPTIONAL
IN CONST EFI_STRING String,
IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL
);
/**
+ This function retrieves the string specified by StringId which is associated
+ with the specified PackageList in the language Language and copies it into
+ the buffer specified by String.
+
+ @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
+ @param Language Points to the language for the retrieved string.
+ @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.
+ @param StringFontInfo If not NULL, points to the string's font
+ information. It's caller's responsibility to free
+ this buffer.
+
+ @retval EFI_SUCCESS The string was returned successfully.
+ @retval EFI_NOT_FOUND The string specified by StringId is not available.
+ The specified PackageList is not in the database.
+ @retval EFI_INVALID_LANGUAGE The string specified by StringId is available but
+ not in the specified language.
+ @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringSize is too small to
+ hold the string.
+ @retval EFI_INVALID_PARAMETER The Language or StringSize was NULL.
+ @retval EFI_INVALID_PARAMETER The value referenced by StringSize was not zero and
+ String was NULL.
+ @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the
+ request.
- This function retrieves the string specified by StringId which
- is associated with the specified PackageList in the language
- Language and copies it into the buffer specified by String. If
- the string specified by StringId is not present in the
- specified PackageList, then EFI_NOT_FOUND is returned. If the
- string specified by StringId is present, but not in the
- specified language then EFI_INVALID_LANGUAGE is returned. If
- the buffer specified by StringSize is too small to hold the
- string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize
- will be updated to the size of buffer actually required to
- hold the string.
-
- @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
-
- @param PackageList The package list in the HII database to
- search for the specified string.
-
- @param Language Points to the language for the retrieved
- 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.
-
- @param StringFontInfo Points to the string's font
- information or NULL if the string font
- information is not desired.
-
- @retval EFI_SUCCESS The string was returned successfully.
-
- @retval EFI_NOT_FOUND The string specified by StringId is not
- available.
-
- @retval EFI_INVALID_LANGUAGE The string specified by StringId
- is available but not in the
- specified language.
-
- @retval EFI_BUFFER_TOO_SMALL The buffer specified by
- StringLength is too small to
- hold the string.
-
- @retval EFI_INVALID_PARAMETER The String or Language was NULL.
-
**/
typedef
EFI_STATUS
-(EFIAPI *EFI_HII_GET_STRING) (
+(EFIAPI *EFI_HII_GET_STRING)(
IN CONST EFI_HII_STRING_PROTOCOL *This,
IN CONST CHAR8 *Language,
IN EFI_HII_HANDLE PackageList,
@@ -134,41 +110,31 @@ EFI_STATUS
);
/**
- This function updates the string specified by StringId in the
- specified PackageList to the text specified by String and,
- optionally, the font information specified by StringFontInfo.
- There is no way to change the font information without changing
- the string text.
-
- @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
-
- @param PackageList The package list containing the strings.
-
- @param Language Points to the language for the updated string.
-
- @param StringId The string id, which is unique within
- PackageList.
-
- @param String Points to the new null-terminated string.
-
- @param StringFontInfo Points to the string's font information
- or NULL if the string font information
- is not changed.
-
- @retval EFI_SUCCESS The string was successfully updated.
-
- @retval EFI_NOT_FOUND The string specified by StringId is not
- in the database.
-
- @retval EFI_INVALID_PARAMETER The String or Language was NULL.
-
- @retval EFI_OUT_OF_RESOURCES The system is out of resources
- to accomplish the task.
+ This function updates the string specified by StringId in the specified PackageList to the text
+ specified by String and, optionally, the font information specified by StringFontInfo.
+
+ @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
+ @param PackageList The package list containing the strings.
+ @param StringId The string's id, which is unique within
+ PackageList.
+ @param Language Points to the language for the updated string.
+ @param String Points to the new null-terminated string.
+ @param StringFontInfo Points to the string's font information or NULL if
+ the string font information is not changed.
+
+ @retval EFI_SUCCESS The string was updated successfully.
+ @retval EFI_NOT_FOUND The string specified by StringId is not in the
+ database.
+ @retval EFI_INVALID_PARAMETER The String or Language was NULL.
+ @retval EFI_INVALID_PARAMETER The specified StringFontInfo does not exist in
+ current database.
+ @retval EFI_OUT_OF_RESOURCES The system is out of resources to accomplish the
+ task.
**/
typedef
EFI_STATUS
-(EFIAPI *EFI_HII_SET_STRING) (
+(EFIAPI *EFI_HII_SET_STRING)(
IN CONST EFI_HII_STRING_PROTOCOL *This,
IN EFI_HII_HANDLE PackageList,
IN EFI_STRING_ID StringId,
@@ -179,37 +145,30 @@ EFI_STATUS
/**
-
This function returns the list of supported languages.
- @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
-
- @param PackageList The package list to examine.
-
- @param Languages Points to the buffer to hold the returned
- string.
-
- @param LanguageSize On entry, points to the size of the
- buffer pointed to by Languages, in
- bytes. On return, points to the length
- of Languages, in bytes.
-
-
- @retval EFI_SUCCESS The languages were returned successfully.
-
- @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small
- to hold the list of supported
- languages. LanguageSize is
- updated to contain the required
- size.
-
- @retval EFI_INVALID_PARAMETER Languages is NULL.
-
+ @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
+ @param PackageList The package list to examine.
+ @param Languages Points to the buffer to hold the returned
+ null-terminated ASCII string.
+ @param LanguagesSize On entry, points to the size of the buffer pointed
+ to by Languages, in bytes. On return, points to
+ the length of Languages, in bytes.
+
+ @retval EFI_SUCCESS The languages were returned successfully.
+ @retval EFI_INVALID_PARAMETER The LanguagesSize was NULL.
+ @retval EFI_INVALID_PARAMETER The value referenced by LanguagesSize is not zero
+ and Languages is NULL.
+ @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small to hold the list of
+ supported languages. LanguageSize is updated to
+ contain the required size.
+ @retval EFI_NOT_FOUND Could not find string package in specified
+ packagelist.
**/
typedef
EFI_STATUS
-(EFIAPI *EFI_HII_GET_LANGUAGES) (
+(EFIAPI *EFI_HII_GET_LANGUAGES)(
IN CONST EFI_HII_STRING_PROTOCOL *This,
IN EFI_HII_HANDLE PackageList,
IN OUT CHAR8 *Languages,
@@ -218,78 +177,52 @@ EFI_STATUS
/**
-
- Each string package has associated with it a single primary
- language and zero or more secondary languages. This routine
- returns the secondary languages associated with a package list.
-
- @param This A pointer to the EFI_HII_STRING_PROTOCOL
- instance.
-
- @param PackageList The package list to examine.
-
- @param FirstLanguage Points to the primary language.
-
- @param Languages are specified in the format specified in
- Appendix M of the UEFI 2.0 specification.
-
- @param SecondaryLanguages Points to the buffer to hold the
- returned list of secondary languages
- for the specified FirstLanguage. If
- there are no secondary languages,
- the function returns successfully,
- but this is set to NULL.
-
- @param SecondaryLanguageSize On entry, points to the size of
- the buffer pointed to by
- Languages, in bytes. On return,
- points to the length of
- Languages in bytes.
-
- @retval EFI_SUCCESS Secondary languages correctly returned
-
- @retval EFI_BUFFER_TOO_SMALL The buffer specified by
- SecondLanguagesSize is too small
- to hold the returned
- information. SecondLanguageSize
- is updated to hold the size of
- the buffer required.
-
- @retval EFI_INVALID_LANGUAGE The language specified by
- FirstLanguage is not present in
- the specified package list.
-
- @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or
- SecondLanguage is NULL.
+ Each string package has associated with it a single primary language and zero
+ or more secondary languages. This routine returns the secondary languages
+ associated with a package list.
+
+ @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
+ @param PackageList The package list to examine.
+ @param PrimaryLanguage Points to the null-terminated ASCII string that specifies
+ the primary language. Languages are specified in the
+ format specified in Appendix M of the UEFI 2.0 specification.
+ @param SecondaryLanguages Points to the buffer to hold the returned null-terminated
+ ASCII string that describes the list of
+ secondary languages for the specified
+ PrimaryLanguage. If there are no secondary
+ languages, the function returns successfully, but
+ this is set to NULL.
+ @param SecondaryLanguagesSize On entry, points to the size of the buffer pointed
+ to by SecondaryLanguages, in bytes. On return,
+ points to the length of SecondaryLanguages in bytes.
+
+ @retval EFI_SUCCESS Secondary languages were correctly returned.
+ @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguagesSize was NULL.
+ @retval EFI_INVALID_PARAMETER The value referenced by SecondaryLanguagesSize is not
+ zero and SecondaryLanguages is NULL.
+ @retval EFI_BUFFER_TOO_SMALL The buffer specified by SecondaryLanguagesSize is
+ too small to hold the returned information.
+ SecondaryLanguageSize is updated to hold the size of
+ the buffer required.
+ @retval EFI_INVALID_LANGUAGE The language specified by PrimaryLanguage is not
+ present in the specified package list.
+ @retval EFI_NOT_FOUND The specified PackageList is not in the Database.
**/
typedef
EFI_STATUS
-(EFIAPI *EFI_HII_GET_2ND_LANGUAGES) (
+(EFIAPI *EFI_HII_GET_2ND_LANGUAGES)(
IN CONST EFI_HII_STRING_PROTOCOL *This,
IN EFI_HII_HANDLE PackageList,
- IN CONST CHAR8 *FirstLanguage,
- IN OUT CHAR8 *SecondLanguages,
- IN OUT UINTN *SecondLanguagesSize
+ IN CONST CHAR8 *PrimaryLanguage,
+ IN OUT CHAR8 *SecondaryLanguages,
+ IN OUT UINTN *SecondaryLanguagesSize
);
-/**
- Services to manipulate the string.
-
- @param NewString Add a new string. GetString Retrieve a
- string and related string information.
-
- @param SetString Change a string.
-
- @param GetLanguages List the languages for a particular
- package list.
-
- @param GetSecondaryLanguages List supported secondary
- languages for a particular
- primary language.
-
-**/
+///
+/// Services to manipulate the string.
+///
struct _EFI_HII_STRING_PROTOCOL {
EFI_HII_NEW_STRING NewString;
EFI_HII_GET_STRING GetString;
@@ -303,4 +236,3 @@ extern EFI_GUID gEfiHiiStringProtocolGuid;
#endif
-