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 - 2010, Intel Corporation.  All rights reserved<BR>
   7 This program and the accompanying materials are licensed and made available under
   8 the terms and conditions of the BSD License that accompanies this distribution.
   9 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 strings.
  53
  54   @param  This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  55   @param  Str1 A pointer to a Null-terminated string.
  56   @param  Str2 A pointer to a Null-terminated string.
  57
  58   @retval 0   Str1 is equivalent to Str2.
  59   @retval >0  Str1 is lexically greater than Str2.
  60   @retval <0  Str1 is lexically less than Str2.
  61
  62 **/
  63 typedef
  64 INTN
  65 (EFIAPI *EFI_UNICODE_COLLATION_STRICOLL)(
  66   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  67   IN CHAR16                                 *Str1,
  68   IN CHAR16                                 *Str2
  69   );
  70
  71 /**
  72   Performs a case-insensitive comparison of a Null-terminated
  73   pattern string and a Null-terminated string.
  74
  75   @param  This    A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  76   @param  String  A pointer to a Null-terminated string.
  77   @param  Pattern A pointer to a Null-terminated pattern string.
  78
  79   @retval TRUE    Pattern was found in String.
  80   @retval FALSE   Pattern was not found in String.
  81
  82 **/
  83 typedef
  84 BOOLEAN
  85 (EFIAPI *EFI_UNICODE_COLLATION_METAIMATCH)(
  86   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  87   IN CHAR16                                 *String,
  88   IN CHAR16                                 *Pattern
  89   );
  90
  91 /**
  92   Converts all the characters in a Null-terminated string to
  93   lower case characters.
  94
  95   @param  This   A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  96   @param  String A pointer to a Null-terminated string.
  97
  98 **/
  99 typedef
 100 VOID
 101 (EFIAPI *EFI_UNICODE_COLLATION_STRLWR)(
 102   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 103   IN OUT CHAR16                             *Str
 104   );
 105
 106 /**
 107   Converts all the characters in a Null-terminated string to upper
 108   case characters.
 109
 110   @param  This   A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
 111   @param  String A pointer to a Null-terminated string.
 112
 113 **/
 114 typedef
 115 VOID
 116 (EFIAPI *EFI_UNICODE_COLLATION_STRUPR)(
 117   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 118   IN OUT CHAR16                             *Str
 119   );
 120
 121 /**
 122   Converts an 8.3 FAT file name in an OEM character set to a Null-terminated
 123   string.
 124
 125   @param  This    A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
 126   @param  FatSize The size of the string Fat in bytes.
 127   @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file
 128                   name using an OEM character set.
 129   @param  String  A pointer to a Null-terminated string. The string must
 130                   be allocated in advance to hold FatSize characters.
 131
 132 **/
 133 typedef
 134 VOID
 135 (EFIAPI *EFI_UNICODE_COLLATION_FATTOSTR)(
 136   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 137   IN UINTN                                  FatSize,
 138   IN CHAR8                                  *Fat,
 139   OUT CHAR16                                *String
 140   );
 141
 142 /**
 143   Converts a Null-terminated string to legal characters in a FAT
 144   filename using an OEM character set.
 145
 146   @param  This    A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
 147   @param  String  A pointer to a Null-terminated string.
 148   @param  FatSize The size of the string Fat in bytes.
 149   @param  Fat     A pointer to a string that contains the converted version of
 150                   String using legal FAT characters from an OEM character set.
 151
 152   @retval TRUE    One or more conversions failed and were substituted with '_'
 153   @retval FALSE   None of the conversions failed.
 154
 155 **/
 156 typedef
 157 BOOLEAN
 158 (EFIAPI *EFI_UNICODE_COLLATION_STRTOFAT)(
 159   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 160   IN CHAR16                                 *String,
 161   IN UINTN                                  FatSize,
 162   OUT CHAR8                                 *Fat
 163   );
 164
 165 ///
 166 /// The EFI_UNICODE_COLLATION_PROTOCOL is used to perform case-insensitive
 167 /// comparisons of strings.
 168 ///
 169 struct _EFI_UNICODE_COLLATION_PROTOCOL {
 170   EFI_UNICODE_COLLATION_STRICOLL    StriColl;
 171   EFI_UNICODE_COLLATION_METAIMATCH  MetaiMatch;
 172   EFI_UNICODE_COLLATION_STRLWR      StrLwr;
 173   EFI_UNICODE_COLLATION_STRUPR      StrUpr;
 174
 175   //
 176   // for supporting fat volumes
 177   //
 178   EFI_UNICODE_COLLATION_FATTOSTR    FatToStr;
 179   EFI_UNICODE_COLLATION_STRTOFAT    StrToFat;
 180
 181   ///
 182   /// A Null-terminated ASCII string array that contains one or more
 183   /// language codes. This array is specified in RFC 4646 format.
 184   ///
 185   CHAR8                             *SupportedLanguages;
 186 };
 187
 188 extern EFI_GUID gEfiUnicodeCollationProtocolGuid;
 189 extern EFI_GUID gEfiUnicodeCollation2ProtocolGuid;
 190
 191 #endif