EFI UNICODE COLLATION2 PROTOCOL

From PhoenixWiki

Jump to: navigation, search

This protocol is used to allow code running in the boot services environment to perform lexical comparison functions on Unicode strings for given languages.

Contents

GUID

#define EFI_UNICODE_COLLATION2_PROTOCOL_GUID \
  {0xa4c751fc, 0x23ae, 0x4c3e, \
  {0x92, 0xe9, 0x49, 0x64, 0xcf, 0x63,0xf3, 0x49}

Protocol Interface Structure

typedef struct {
  EFI_UNICODE_COLLATION_STRICOLL   StriColl;
  EFI_UNICODE_COLLATION_METAIMATCH MetaiMatch;
  EFI_UNICODE_COLLATION_STRLWR     StrLwr;
  EFI_UNICODE_COLLATION_STRUPR     StrUpr;
  EFI_UNICODE_COLLATION_FATTOSTR   FatToStr;
  EFI_UNICODE_COLLATION_STRTOFAT   StrToFat;
  CHAR8                             *SupportedLanguages;
} EFI_UNICODE_COLLATION_PROTOCOL;

Parameters

Parameter Description
StriColl Performs a case-insensitive comparison of two Null-terminated Unicode strings. See the StriColl() function description.
MetaiMatch 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 substring. See the MetaiMatch() function description.
StrLwr Converts all the Unicode characters in a Null-terminated Unicode string to lowercase Unicode characters. See the StrLwr() function description.
StrUpr Converts all the Unicode characters in a Null-terminated Unicode string to uppercase Unicode characters. See the StrUpr() function description.
FatToStr Converts an 8.3 FAT file name using an OEM character set to a Null-terminated Unicode string. See the FatToStr() function description.
StrToFat Converts a Null-terminated Unicode string to legal characters in a FAT filename using an OEM character set. See the StrToFat() function description.
SupportedLanguages A Null-terminated ASCII string array that contains one or more language codes. This array is specified in RFC 3066 format. See Appendix M of the UEFI 2.1 specification for the format of language codes and language code arrays.

Description

The EFI_UNICODE_COLLATION2_PROTOCOL is used to perform case-insensitive comparisons of Unicode strings.

One or more of the EFI_UNICODE_COLLATION2_PROTOCOL instances may be present at one time. Each protocol instance can support one or more language codes. The language codes that are supported in the EFI_UNICODE_COLLATION2_PROTOCOL is declared in SupportedLanguages.

The SupportedLanguages is a Null-terminated ASCII string array that contains one or more supported language codes. This is the list of language codes that this protocol supports. See Appendix M for the format of language codes and language code arrays. The main motivation for this protocol is to help support file names in a file system driver. When a file is opened, a file name needs to be compared to the file names on the disk. In some cases, this comparison needs to be performed in a case-insensitive manner. In addition, this protocol can be used to sort files from a directory or to perform a case-insensitive file search.

Members

StriColl()

Performs a case-insensitive comparison of two Null-terminated Unicode strings.

Prototype

typedef
INTN
(EFIAPI *EFI_UNICODE_COLLATION_STRICOLL) (
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN CHAR16                          *s1,
  IN CHAR16                          *s2
  );

Parameters

Parameter Description
This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
s1 A pointer to a Null-terminated Unicode string.
s2 A pointer to a Null-terminated Unicode string.

Description
The StriColl() function performs a case-insensitive comparison of two Null-terminated Unicode strings.

This function performs a case-insensitive comparison between the Unicode string s1 and the Unicode string s2 using the rules for the language codes that this protocol instance supports. If s1 is equivalent to s2, then 0 is returned. If s1 is lexically less than s2, then a negative number will be returned. If s1 is lexically greater than s2, then a positive number will be returned. This function allows Unicode strings to be compared and sorted.

Status Codes Returned

Result Description
0 s1 is equivalent to s2.
> 0 s1 is lexically greater than s2.
< 0 s1 is lexically less than s2.

MetaiMatch()

Performs a case-insensitive comparison of a Null-terminated Unicode pattern string and a Null-terminated Unicode string.

Prototype

typedef
BOOLEAN
(EFIAPI *EFI_UNICODE_COLLATION_METAIMATCH) (
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN CHAR16                          *String,
  IN CHAR16                          *Pattern
  );
  

Parameters

Parameter Description
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.

Description
The MetaiMatch() function performs a case-insensitive comparison of a Null-terminated Unicode pattern string and a Null-terminated Unicode string.

This function checks to see if the pattern of characters described by Pattern are found in String. The pattern check is a case-insensitive comparison using the rules for the language codes that this protocol instance supports. If the pattern match succeeds, then TRUE is returned. Otherwise FALSE is returned. The following syntax can be used to build the string Pattern:

Pattern Description
* Match 0 or more characters.
? Match any one character.
[<char1><char2>…<charN>] Match any character in the set.
[<char1>-<char2>] Match any character between <char1> and <char2>.
<char> Match the character <char>.

The following are example patterns for English:


Pattern Description
*.FW Matches all strings that end in “.FW” or “.fw” or “.Fw” or “.fW.”
[a-z] Match any letter in the alphabet.
[!@#$%^&*()] Match any one of these symbols.
z Match the character “z” or “Z”
D?.* Match the character “D” or “d” followed by any character followed by a “.” followed by any string.

Status Codes Returned

Status Code Description
TRUE Pattern was found in String.
FALSE Pattern was not found in String.

StrLwr()

Converts all the Unicode characters in a Null-terminated Unicode string to lowercase Unicode characters.

Prototype

typedef
VOID
(EFIAPI *EFI_UNICODE_COLLATION_STRLWR) (
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN OUT CHAR16                      *String
  );
  

Parameters

Parameter Description
This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
String A pointer to a Null-terminated Unicode string.

Description
This functions walks through all the Unicode characters in String, and converts each one to its lowercase equivalent if it has one. The converted string is returned in String.

StrUpr()

Converts all the Unicode characters in a Null-terminated Unicode string to uppercase Unicode characters.

Prototype

typedef
VOID
(EFIAPI *EFI_UNICODE_COLLATION_STRUPR) (
  IN EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN OUT CHAR16                      *String
  );

Parameters

Parameter Description
This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
String A pointer to a Null-terminated string.

Description
This functions walks through all the characters in String, and converts each one to its uppercase equivalent if it has one. The converted string is returned in String.

FatToStr()

Converts an 8.3 FAT file name in an OEM character set to a Null-terminated Unicode string.

Prototype

typedef
VOID
(EFIAPI *EFI_UNICODE_COLLATION_FATTOSTR) (
  IN  EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN  UINTN                           FatSize,
  IN  CHAR8                           *Fat,
  OUT CHAR16                          *String
  );
  

Parameters

Parameter Description
This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
FatSize The size of the string Fat in bytes.
Fat A pointer to a Null-terminated string that contains an 8.3 file name using an OEM character set.
String A pointer to a Null-terminated Unicode string. The string must be allocated in advance to hold FatSize Unicode characters.

Description
This function converts the string specified by Fat with length FatSize to the Null-terminated Unicode string specified by String. The characters in Fat are from an OEM character set.

StrToFat()

Converts a Null-terminated Unicode string to legal characters in a FAT filename using an OEM character set.

Prototype

typedef
BOOLEAN
(EFIAPI *EFI_UNICODE_COLLATION_STRTOFAT) (
  IN  EFI_UNICODE_COLLATION_PROTOCOL *This,
  IN  CHAR16                          *String,
  IN  UINTN                           FatSize,
  OUT CHAR8                           *Fat
  );

Parameters

Parameter Descriptin
This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
String A pointer to a Null-terminated string.
FatSize The size of the string Fat in bytes.
Fat A pointer to a string that contains the converted version of String using legal FAT characters from an OEM character set.

Description
This function converts the characters from String into legal FAT characters in an OEM character set and stores then in the string Fat. This conversion continues until either FatSize bytes are stored in Fat, or the end of String is reached. The Unicode characters ‘.’ (period) and ‘ ’ (space) are ignored for this conversion. Unicode characters that map to an illegal FAT character are substituted with an ‘_’. If no valid mapping from a Unicode character to an OEM character is available, then it is also substituted with an ‘_’. If any of the Unicode characters conversions are substituted with a ‘_’, then TRUE is returned. Otherwise FALSE is returned.

Status Codes Returned

Status Code Description
TRUE One or more conversions failed and were substituted with ‘_’.
FALSE None of the conversions failed.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools