From 61e334303b59d28e0baa1737a5e5751aad301e32 Mon Sep 17 00:00:00 2001 From: qhuang8 Date: Thu, 8 May 2008 03:10:39 +0000 Subject: [PATCH] Add doxygen style comments for functions in English module. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5179 6f19259b-4bc3-4df7-8a09-765794883524 --- .../EnglishDxe/UnicodeCollationEng.c | 233 +++++++----------- .../EnglishDxe/UnicodeCollationEng.h | 85 ++++++- 2 files changed, 177 insertions(+), 141 deletions(-) diff --git a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c index 6d0b556561..07bb2f446d 100644 --- a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c +++ b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c @@ -1,5 +1,5 @@ /** @file - Unicode Collation Protocol (English) + Driver to implement English version of Unicode Collation Protocol. Copyright (c) 2006 - 2008, Intel Corporation.
All rights reserved. This program and the accompanying materials @@ -79,33 +79,25 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_COLLATION_PROTOCOL Unicode2Eng = { "en" }; -// -// Driver entry point. -// +/** + The user Entry Point for English module. + + This function initializes unicode character mapping and then installs Unicode + Collation & Unicode Collation 2 Protocols based on the feature flags. + + @param ImageHandle The firmware allocated handle for the EFI image. + @param SystemTable A pointer to the EFI System Table. + + @retval EFI_SUCCESS The entry point is executed successfully. + @retval other Some error occurs when executing this entry point. + +**/ EFI_STATUS EFIAPI InitializeUnicodeCollationEng ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - -Routine Description: - - Initializes the Unicode Collation Driver - -Arguments: - - ImageHandle - - - SystemTable - - -Returns: - - EFI_SUCCESS - EFI_OUT_OF_RESOURCES - ---*/ { EFI_STATUS Status; UINTN Index; @@ -177,67 +169,55 @@ Returns: return Status; } + +/** + Performs a case-insensitive comparison of two Null-terminated Unicode + strings. + + @param This Protocol instance pointer. + @param Str1 A pointer to a Null-terminated Unicode string. + @param Str2 A pointer to a Null-terminated Unicode string. + + @retval 0 Str1 is equivalent to Str2 + @retval > 0 Str1 is lexically greater than Str2 + @retval < 0 Str1 is lexically less than Str2 + +**/ INTN EFIAPI EngStriColl ( IN EFI_UNICODE_COLLATION_PROTOCOL *This, - IN CHAR16 *s1, - IN CHAR16 *s2 + IN CHAR16 *Str1, + IN CHAR16 *Str2 ) -/*++ - -Routine Description: - - Performs a case-insensitive comparison of two Null-terminated Unicode strings. - -Arguments: - - This - s1 - s2 - -Returns: - ---*/ { - while (*s1) { - if (ToUpper (*s1) != ToUpper (*s2)) { + while (*Str1) { + if (ToUpper (*Str1) != ToUpper (*Str2)) { break; } - s1 += 1; - s2 += 1; + Str1 += 1; + Str2 += 1; } - return ToUpper (*s1) - ToUpper (*s2); + return ToUpper (*Str1) - ToUpper (*Str2); } + +/** + Converts all the Unicode characters in a Null-terminated Unicode string to + lower case Unicode characters. + + @param This Protocol instance pointer. + @param Str A pointer to a Null-terminated Unicode string. + +**/ VOID EFIAPI EngStrLwr ( IN EFI_UNICODE_COLLATION_PROTOCOL *This, IN OUT CHAR16 *Str ) -/*++ - -Routine Description: - - Converts all the Unicode characters in a Null-terminated Unicode string - to lower case Unicode characters. - -Arguments: - - This - A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance. - Str1 - A pointer to a Null-terminated Unicode string. - Str2 - A pointer to a Null-terminated Unicode string. - -Returns: - - 0 - s1 is equivalent to s2. - > 0 - s1 is lexically greater than s2. - < 0 - s1 is lexically less than s2. - ---*/ { while (*Str) { *Str = ToLower (*Str); @@ -245,27 +225,21 @@ Returns: } } + +/** + Converts all the Unicode characters in a Null-terminated Unicode string to upper + case Unicode characters. + + @param This Protocol instance pointer. + @param Str A pointer to a Null-terminated Unicode string. + +**/ VOID EFIAPI EngStrUpr ( IN EFI_UNICODE_COLLATION_PROTOCOL *This, IN OUT CHAR16 *Str ) -/*++ - -Routine Description: - - Converts all the Unicode characters in a Null-terminated - Unicode string to upper case Unicode characters. - -Arguments: - This - Str - -Returns: - None - ---*/ { while (*Str) { *Str = ToUpper (*Str); @@ -273,6 +247,18 @@ Returns: } } +/** + Performs a case-insensitive comparison of a Null-terminated Unicode + pattern string and a Null-terminated Unicode string. + + @param This Protocol instance pointer. + @param String A pointer to a Null-terminated Unicode string. + @param Pattern A pointer to a Null-terminated Unicode pattern string. + + @retval TRUE Pattern was found in String. + @retval FALSE Pattern was not found in String. + +**/ BOOLEAN EFIAPI EngMetaiMatch ( @@ -280,28 +266,6 @@ EngMetaiMatch ( IN CHAR16 *String, IN CHAR16 *Pattern ) -/*++ - -Routine Description: - - Performs a case-insensitive comparison between a Null-terminated - Unicode pattern string and a Null-terminated Unicode string. - - The pattern string can use the '?' wildcard to match any character, - and the '*' wildcard to match any sub-string. - -Arguments: - - This - A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance. - String - A pointer to a Null-terminated Unicode string. - Pattern - A pointer to a Null-terminated Unicode pattern string. - -Returns: - - TRUE - Pattern was found in String. - FALSE - Pattern was not found in String. - ---*/ { CHAR16 CharC; CHAR16 CharP; @@ -419,6 +383,19 @@ Returns: } } + +/** + Converts an 8.3 FAT file name in an OEM character set to a Null-terminated + Unicode string. + + @param This Protocol instance pointer. + @param FatSize The size of the string Fat in bytes. + @param Fat A pointer to a Null-terminated string that contains an 8.3 file + name using an OEM character set. + @param String A pointer to a Null-terminated Unicode string. The string must + be preallocated to hold FatSize Unicode characters. + +**/ VOID EFIAPI EngFatToStr ( @@ -427,24 +404,6 @@ EngFatToStr ( IN CHAR8 *Fat, OUT CHAR16 *String ) -/*++ - -Routine Description: - - Converts an 8.3 FAT file name using an OEM character set - to a Null-terminated Unicode string. - - BUGBUG: Function has to expand DBCS FAT chars, currently not. - -Arguments: - This - FatSize - Fat - String - -Returns: - ---*/ { // // No DBCS issues, just expand and add null terminate to end of string @@ -459,6 +418,22 @@ Returns: *String = 0; } + +/** + Converts a Null-terminated Unicode string to legal characters in a FAT + filename using an OEM character set. + + @param This Protocol instance pointer. + @param String A pointer to a Null-terminated Unicode string. The string must + be preallocated to hold FatSize Unicode characters. + @param FatSize The size of the string Fat in bytes. + @param Fat A pointer to a Null-terminated string that contains an 8.3 file + name using an OEM character set. + + @retval TRUE Fat is a Long File Name + @retval FALSE Fat is an 8.3 file name + +**/ BOOLEAN EFIAPI EngStrToFat ( @@ -467,26 +442,6 @@ EngStrToFat ( IN UINTN FatSize, OUT CHAR8 *Fat ) -/*++ - -Routine Description: - - Converts a Null-terminated Unicode string to legal characters - in a FAT filename using an OEM character set. - - Functions has to crunch string to a fat string. Replacing - any chars that can't be represented in the fat name. - -Arguments: - This - String - FatSize - Fat - -Returns: - TRUE - FALSE ---*/ { BOOLEAN SpecialCharExist; diff --git a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h index 74e243c424..7cab7088cf 100644 --- a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h +++ b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h @@ -38,15 +38,40 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. // // Prototypes // +/** + Performs a case-insensitive comparison of two Null-terminated Unicode + strings. + + @param This Protocol instance pointer. + @param Str1 A pointer to a Null-terminated Unicode string. + @param Str2 A pointer to a Null-terminated Unicode string. + + @retval 0 Str1 is equivalent to Str2 + @retval > 0 Str1 is lexically greater than Str2 + @retval < 0 Str1 is lexically less than Str2 + +**/ INTN EFIAPI EngStriColl ( IN EFI_UNICODE_COLLATION_PROTOCOL *This, - IN CHAR16 *s1, - IN CHAR16 *s2 + IN CHAR16 *Str1, + IN CHAR16 *Str2 ) ; +/** + Performs a case-insensitive comparison of a Null-terminated Unicode + pattern string and a Null-terminated Unicode string. + + @param This Protocol instance pointer. + @param String A pointer to a Null-terminated Unicode string. + @param Pattern A pointer to a Null-terminated Unicode pattern string. + + @retval TRUE Pattern was found in String. + @retval FALSE Pattern was not found in String. + +**/ BOOLEAN EFIAPI EngMetaiMatch ( @@ -56,6 +81,14 @@ EngMetaiMatch ( ) ; +/** + Converts all the Unicode characters in a Null-terminated Unicode string to + lower case Unicode characters. + + @param This Protocol instance pointer. + @param Str A pointer to a Null-terminated Unicode string. + +**/ VOID EFIAPI EngStrLwr ( @@ -64,6 +97,14 @@ EngStrLwr ( ) ; +/** + Converts all the Unicode characters in a Null-terminated Unicode string to upper + case Unicode characters. + + @param This Protocol instance pointer. + @param Str A pointer to a Null-terminated Unicode string. + +**/ VOID EFIAPI EngStrUpr ( @@ -72,6 +113,18 @@ EngStrUpr ( ) ; +/** + Converts an 8.3 FAT file name in an OEM character set to a Null-terminated + Unicode string. + + @param This Protocol instance pointer. + @param FatSize The size of the string Fat in bytes. + @param Fat A pointer to a Null-terminated string that contains an 8.3 file + name using an OEM character set. + @param String A pointer to a Null-terminated Unicode string. The string must + be preallocated to hold FatSize Unicode characters. + +**/ VOID EFIAPI EngFatToStr ( @@ -82,6 +135,21 @@ EngFatToStr ( ) ; +/** + Converts a Null-terminated Unicode string to legal characters in a FAT + filename using an OEM character set. + + @param This Protocol instance pointer. + @param String A pointer to a Null-terminated Unicode string. The string must + be preallocated to hold FatSize Unicode characters. + @param FatSize The size of the string Fat in bytes. + @param Fat A pointer to a Null-terminated string that contains an 8.3 file + name using an OEM character set. + + @retval TRUE Fat is a Long File Name + @retval FALSE Fat is an 8.3 file name + +**/ BOOLEAN EFIAPI EngStrToFat ( @@ -92,6 +160,19 @@ EngStrToFat ( ) ; +/** + The user Entry Point for English module. + + This function initializes unicode character mapping and then installs Unicode + Collation & Unicode Collation 2 Protocols based on the feature flags. + + @param ImageHandle The firmware allocated handle for the EFI image. + @param SystemTable A pointer to the EFI System Table. + + @retval EFI_SUCCESS The entry point is executed successfully. + @retval other Some error occurs when executing this entry point. + +**/ EFI_STATUS EFIAPI InitializeUnicodeCollationEng (