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 /**
  74   Performs a case-insensitive comparison of a Null-terminated Unicode
  75   pattern string and a Null-terminated Unicode string.
  76
  77   @param  This    Protocol instance pointer.
  78   @param  String  A pointer to a Null-terminated Unicode string.
  79   @param  Pattern A pointer to a Null-terminated Unicode pattern string.
  80
  81   @retval TRUE    Pattern was found in String.
  82   @retval FALSE   Pattern was not found in String.
  83
  84 **/
  85 typedef
  86 BOOLEAN
  87 (EFIAPI *EFI_UNICODE_COLLATION_METAIMATCH)(
  88   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  89   IN CHAR16                                 *String,
  90   IN CHAR16                                 *Pattern
  91   )
  92 ;
  93
  94 /**
  95   Converts all the Unicode characters in a Null-terminated Unicode string to
  96   lower case Unicode characters.
  97
  98   @param  This   Protocol instance pointer.
  99   @param  String A pointer to a Null-terminated Unicode string.
 100
 101 **/
 102 typedef
 103 VOID
 104 (EFIAPI *EFI_UNICODE_COLLATION_STRLWR)(
 105   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 106   IN OUT CHAR16                             *Str
 107   )
 108 ;
 109
 110 /**
 111   Converts all the Unicode characters in a Null-terminated Unicode string to upper
 112   case Unicode characters.
 113
 114   @param  This   Protocol instance pointer.
 115   @param  String A pointer to a Null-terminated Unicode string.
 116
 117 **/
 118 typedef
 119 VOID
 120 (EFIAPI *EFI_UNICODE_COLLATION_STRUPR)(
 121   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 122   IN OUT CHAR16                             *Str
 123   )
 124 ;
 125
 126 /**
 127   Converts an 8.3 FAT file name in an OEM character set to a Null-terminated
 128   Unicode string.
 129
 130   @param  This    Protocol instance pointer.
 131   @param  FatSize The size of the string Fat in bytes.
 132   @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file
 133                   name using an OEM character set.
 134   @param  String  A pointer to a Null-terminated Unicode string. The string must
 135                   be preallocated to hold FatSize Unicode characters.
 136
 137 **/
 138 typedef
 139 VOID
 140 (EFIAPI *EFI_UNICODE_COLLATION_FATTOSTR)(
 141   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 142   IN UINTN                                  FatSize,
 143   IN CHAR8                                  *Fat,
 144   OUT CHAR16                                *String
 145   )
 146 ;
 147
 148 /**
 149   Converts a Null-terminated Unicode string to legal characters in a FAT
 150   filename using an OEM character set.
 151
 152   @param  This    Protocol instance pointer.
 153   @param  String  A pointer to a Null-terminated Unicode string. The string must
 154                   be preallocated to hold FatSize Unicode characters.
 155   @param  FatSize The size of the string Fat in bytes.
 156   @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file
 157                   name using an OEM character set.
 158
 159   @retval TRUE    Fat is a Long File Name
 160   @retval FALSE   Fat is an 8.3 file name
 161
 162 **/
 163 typedef
 164 BOOLEAN
 165 (EFIAPI *EFI_UNICODE_COLLATION_STRTOFAT)(
 166   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 167   IN CHAR16                                 *String,
 168   IN UINTN                                  FatSize,
 169   OUT CHAR8                                 *Fat
 170   )
 171 ;
 172
 173 /**
 174   @par Protocol Description:
 175   The EFI_UNICODE_COLLATION_PROTOCOL is used to perform case-insensitive
 176   comparisons of Unicode strings.
 177
 178   @param StriColl
 179   Performs a case-insensitive comparison of two Null-terminated Unicode strings.
 180
 181   @param MetaiMatch
 182   Performs a case-insensitive comparison between a Null-terminated Unicode
 183   pattern string and a Null-terminated Unicode string. The pattern string
 184   can use the '?' wildcard to match any character, and the '*' wildcard to
 185   match any substring.
 186
 187   @param StrLwr
 188   Converts all the Unicode characters in a Null-terminated Unicode string to
 189   lowercase Unicode characters.
 190
 191   @param StrUpr
 192   Converts all the Unicode characters in a Null-terminated Unicode string to
 193   uppercase Unicode characters.
 194
 195   @param FatToStr
 196   Converts an 8.3 FAT file name using an OEM character set to a Null-terminated
 197   Unicode string.
 198
 199   @param StrToFat
 200   Converts a Null-terminated Unicode string to legal characters in a FAT
 201   filename using an OEM character set.
 202
 203   @param Supported
 204   LanguagesA Null-terminated ASCII string array that contains one or more
 205   language codes. This array is specified in RFC 4646 format.
 206 **/
 207 struct _EFI_UNICODE_COLLATION_PROTOCOL {
 208   //
 209   // general
 210   //
 211   EFI_UNICODE_COLLATION_STRICOLL    StriColl;
 212   EFI_UNICODE_COLLATION_METAIMATCH  MetaiMatch;
 213   EFI_UNICODE_COLLATION_STRLWR      StrLwr;
 214   EFI_UNICODE_COLLATION_STRUPR      StrUpr;
 215
 216   //
 217   // for supporting fat volumes
 218   //
 219   EFI_UNICODE_COLLATION_FATTOSTR    FatToStr;
 220   EFI_UNICODE_COLLATION_STRTOFAT    StrToFat;
 221
 222   CHAR8                             *SupportedLanguages;
 223 };
 224
 225 extern EFI_GUID gEfiUnicodeCollationProtocolGuid;
 226 extern EFI_GUID gEfiUnicodeCollation2ProtocolGuid;
 227
 228 #endif