MdePkg/Include/Protocol/UnicodeCollation.h

   1 /** @file
   2   Unicode Collation protocol that follows the UEFI 2.0 specification.
   3   This protocol is used to allow code running in the boot services environment
   4   to perform lexical comparison functions on Unicode strings for given languages.
   5
   6   Copyright (c) 2006 - 2008, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __UNICODE_COLLATION_H__
  18 #define __UNICODE_COLLATION_H__
  19
  20 #define EFI_UNICODE_COLLATION_PROTOCOL_GUID \
  21   { \
  22     0x1d85cd7f, 0xf43d, 0x11d2, {0x9a, 0xc, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  23   }
  24
  25 #define EFI_UNICODE_COLLATION_PROTOCOL2_GUID \
  26   { \
  27     0xa4c751fc, 0x23ae, 0x4c3e, {0x92, 0xe9, 0x49, 0x64, 0xcf, 0x63, 0xf3, 0x49 } \
  28   }
  29
  30 typedef struct _EFI_UNICODE_COLLATION_PROTOCOL  EFI_UNICODE_COLLATION_PROTOCOL;
  31
  32
  33 ///
  34 /// Protocol GUID name defined in EFI1.1.
  35 ///
  36 #define UNICODE_COLLATION_PROTOCOL              EFI_UNICODE_COLLATION_PROTOCOL_GUID
  37
  38 ///
  39 /// Protocol defined in EFI1.1.
  40 ///
  41 typedef EFI_UNICODE_COLLATION_PROTOCOL          UNICODE_COLLATION_INTERFACE;
  42
  43 ///
  44 /// Protocol data structures and defines
  45 ///
  46 #define EFI_UNICODE_BYTE_ORDER_MARK (CHAR16) (0xfeff)
  47
  48 //
  49 // Protocol member functions
  50 //
  51 /**
  52   Performs a case-insensitive comparison of two Null-terminated Unicode
  53   strings.
  54
  55   @param  This Protocol instance pointer.
  56   @param  Str1 A pointer to a Null-terminated Unicode string.
  57   @param  Str2 A pointer to a Null-terminated Unicode string.
  58
  59   @retval 0   Str1 is equivalent to Str2
  60   @retval >_0 Str1 is lexically greater than Str2
  61   @retval <_0 Str1 is lexically less than Str2
  62
  63 **/
  64 typedef
  65 INTN
  66 (EFIAPI *EFI_UNICODE_COLLATION_STRICOLL)(
  67   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  68   IN CHAR16                                 *Str1,
  69   IN CHAR16                                 *Str2
  70   );
  71
  72 /**
  73   Performs a case-insensitive comparison of a Null-terminated Unicode
  74   pattern string and a Null-terminated Unicode string.
  75
  76   @param  This    Protocol instance pointer.
  77   @param  String  A pointer to a Null-terminated Unicode string.
  78   @param  Pattern A pointer to a Null-terminated Unicode pattern string.
  79
  80   @retval TRUE    Pattern was found in String.
  81   @retval FALSE   Pattern was not found in String.
  82
  83 **/
  84 typedef
  85 BOOLEAN
  86 (EFIAPI *EFI_UNICODE_COLLATION_METAIMATCH)(
  87   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  88   IN CHAR16                                 *String,
  89   IN CHAR16                                 *Pattern
  90   );
  91
  92 /**
  93   Converts all the Unicode characters in a Null-terminated Unicode string to
  94   lower case Unicode characters.
  95
  96   @param  This   Protocol instance pointer.
  97   @param  String A pointer to a Null-terminated Unicode string.
  98
  99 **/
 100 typedef
 101 VOID
 102 (EFIAPI *EFI_UNICODE_COLLATION_STRLWR)(
 103   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 104   IN OUT CHAR16                             *Str
 105   );
 106
 107 /**
 108   Converts all the Unicode characters in a Null-terminated Unicode string to upper
 109   case Unicode characters.
 110
 111   @param  This   Protocol instance pointer.
 112   @param  String A pointer to a Null-terminated Unicode string.
 113
 114 **/
 115 typedef
 116 VOID
 117 (EFIAPI *EFI_UNICODE_COLLATION_STRUPR)(
 118   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 119   IN OUT CHAR16                             *Str
 120   );
 121
 122 /**
 123   Converts an 8.3 FAT file name in an OEM character set to a Null-terminated
 124   Unicode string.
 125
 126   @param  This    Protocol instance pointer.
 127   @param  FatSize The size of the string Fat in bytes.
 128   @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file
 129                   name using an OEM character set.
 130   @param  String  A pointer to a Null-terminated Unicode string. The string must
 131                   be preallocated to hold FatSize Unicode characters.
 132
 133 **/
 134 typedef
 135 VOID
 136 (EFIAPI *EFI_UNICODE_COLLATION_FATTOSTR)(
 137   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 138   IN UINTN                                  FatSize,
 139   IN CHAR8                                  *Fat,
 140   OUT CHAR16                                *String
 141   );
 142
 143 /**
 144   Converts a Null-terminated Unicode string to legal characters in a FAT
 145   filename using an OEM character set.
 146
 147   @param  This    Protocol instance pointer.
 148   @param  String  A pointer to a Null-terminated Unicode string. The string must
 149                   be preallocated to hold FatSize Unicode characters.
 150   @param  FatSize The size of the string Fat in bytes.
 151   @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file
 152                   name using an OEM character set.
 153
 154   @retval TRUE    Fat is a Long File Name
 155   @retval FALSE   Fat is an 8.3 file name
 156
 157 **/
 158 typedef
 159 BOOLEAN
 160 (EFIAPI *EFI_UNICODE_COLLATION_STRTOFAT)(
 161   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 162   IN CHAR16                                 *String,
 163   IN UINTN                                  FatSize,
 164   OUT CHAR8                                 *Fat
 165   );
 166
 167 /**
 168   @par Protocol Description:
 169   The EFI_UNICODE_COLLATION_PROTOCOL is used to perform case-insensitive
 170   comparisons of Unicode strings.
 171
 172   @param StriColl
 173   Performs a case-insensitive comparison of two Null-terminated Unicode strings.
 174
 175   @param MetaiMatch
 176   Performs a case-insensitive comparison between a Null-terminated Unicode
 177   pattern string and a Null-terminated Unicode string. The pattern string
 178   can use the '?' wildcard to match any character, and the '*' wildcard to
 179   match any substring.
 180
 181   @param StrLwr
 182   Converts all the Unicode characters in a Null-terminated Unicode string to
 183   lowercase Unicode characters.
 184
 185   @param StrUpr
 186   Converts all the Unicode characters in a Null-terminated Unicode string to
 187   uppercase Unicode characters.
 188
 189   @param FatToStr
 190   Converts an 8.3 FAT file name using an OEM character set to a Null-terminated
 191   Unicode string.
 192
 193   @param StrToFat
 194   Converts a Null-terminated Unicode string to legal characters in a FAT
 195   filename using an OEM character set.
 196
 197   @param Supported
 198   LanguagesA Null-terminated ASCII string array that contains one or more
 199   language codes. This array is specified in RFC 4646 format.
 200 **/
 201 struct _EFI_UNICODE_COLLATION_PROTOCOL {
 202   //
 203   // general
 204   //
 205   EFI_UNICODE_COLLATION_STRICOLL    StriColl;
 206   EFI_UNICODE_COLLATION_METAIMATCH  MetaiMatch;
 207   EFI_UNICODE_COLLATION_STRLWR      StrLwr;
 208   EFI_UNICODE_COLLATION_STRUPR      StrUpr;
 209
 210   //
 211   // for supporting fat volumes
 212   //
 213   EFI_UNICODE_COLLATION_FATTOSTR    FatToStr;
 214   EFI_UNICODE_COLLATION_STRTOFAT    StrToFat;
 215
 216   CHAR8                             *SupportedLanguages;
 217 };
 218
 219 extern EFI_GUID gEfiUnicodeCollationProtocolGuid;
 220 extern EFI_GUID gEfiUnicodeCollation2ProtocolGuid;
 221
 222 #endif