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 - 2018, Intel Corporation. All rights reserved.<BR>
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef __UNICODE_COLLATION_H__
  12 #define __UNICODE_COLLATION_H__
  13
  14 #define EFI_UNICODE_COLLATION_PROTOCOL_GUID \
  15   { \
  16     0x1d85cd7f, 0xf43d, 0x11d2, {0x9a, 0xc, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  17   }
  18
  19 #define EFI_UNICODE_COLLATION_PROTOCOL2_GUID \
  20   { \
  21     0xa4c751fc, 0x23ae, 0x4c3e, {0x92, 0xe9, 0x49, 0x64, 0xcf, 0x63, 0xf3, 0x49 } \
  22   }
  23
  24 typedef struct _EFI_UNICODE_COLLATION_PROTOCOL EFI_UNICODE_COLLATION_PROTOCOL;
  25
  26 ///
  27 /// Protocol GUID name defined in EFI1.1.
  28 ///
  29 #define UNICODE_COLLATION_PROTOCOL  EFI_UNICODE_COLLATION_PROTOCOL_GUID
  30
  31 ///
  32 /// Protocol defined in EFI1.1.
  33 ///
  34 typedef EFI_UNICODE_COLLATION_PROTOCOL UNICODE_COLLATION_INTERFACE;
  35
  36 ///
  37 /// Protocol data structures and defines
  38 ///
  39 #define EFI_UNICODE_BYTE_ORDER_MARK  (CHAR16) (0xfeff)
  40
  41 //
  42 // Protocol member functions
  43 //
  44
  45 /**
  46   Performs a case-insensitive comparison of two Null-terminated strings.
  47
  48   @param  This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  49   @param  Str1 A pointer to a Null-terminated string.
  50   @param  Str2 A pointer to a Null-terminated string.
  51
  52   @retval 0   Str1 is equivalent to Str2.
  53   @retval >0  Str1 is lexically greater than Str2.
  54   @retval <0  Str1 is lexically less than Str2.
  55
  56 **/
  57 typedef
  58 INTN
  59 (EFIAPI *EFI_UNICODE_COLLATION_STRICOLL)(
  60   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  61   IN CHAR16                                 *Str1,
  62   IN CHAR16                                 *Str2
  63   );
  64
  65 /**
  66   Performs a case-insensitive comparison of a Null-terminated
  67   pattern string and a Null-terminated string.
  68
  69   @param  This    A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  70   @param  String  A pointer to a Null-terminated string.
  71   @param  Pattern A pointer to a Null-terminated pattern string.
  72
  73   @retval TRUE    Pattern was found in String.
  74   @retval FALSE   Pattern was not found in String.
  75
  76 **/
  77 typedef
  78 BOOLEAN
  79 (EFIAPI *EFI_UNICODE_COLLATION_METAIMATCH)(
  80   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  81   IN CHAR16                                 *String,
  82   IN CHAR16                                 *Pattern
  83   );
  84
  85 /**
  86   Converts all the characters in a Null-terminated string to
  87   lower case characters.
  88
  89   @param  This   A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
  90   @param  String A pointer to a Null-terminated string.
  91
  92 **/
  93 typedef
  94 VOID
  95 (EFIAPI *EFI_UNICODE_COLLATION_STRLWR)(
  96   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
  97   IN OUT CHAR16                             *Str
  98   );
  99
 100 /**
 101   Converts all the characters in a Null-terminated string to upper
 102   case characters.
 103
 104   @param  This   A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
 105   @param  String A pointer to a Null-terminated string.
 106
 107 **/
 108 typedef
 109 VOID
 110 (EFIAPI *EFI_UNICODE_COLLATION_STRUPR)(
 111   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 112   IN OUT CHAR16                             *Str
 113   );
 114
 115 /**
 116   Converts an 8.3 FAT file name in an OEM character set to a Null-terminated
 117   string.
 118
 119   @param  This    A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
 120   @param  FatSize The size of the string Fat in bytes.
 121   @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file
 122                   name using an 8-bit OEM character set.
 123   @param  String  A pointer to a Null-terminated string. The string must
 124                   be allocated in advance to hold FatSize characters.
 125
 126 **/
 127 typedef
 128 VOID
 129 (EFIAPI *EFI_UNICODE_COLLATION_FATTOSTR)(
 130   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 131   IN UINTN                                  FatSize,
 132   IN CHAR8                                  *Fat,
 133   OUT CHAR16                                *String
 134   );
 135
 136 /**
 137   Converts a Null-terminated string to legal characters in a FAT
 138   filename using an OEM character set.
 139
 140   @param  This    A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.
 141   @param  String  A pointer to a Null-terminated string.
 142   @param  FatSize The size of the string Fat in bytes.
 143   @param  Fat     A pointer to a string that contains the converted version of
 144                   String using legal FAT characters from an OEM character set.
 145
 146   @retval TRUE    One or more conversions failed and were substituted with '_'
 147   @retval FALSE   None of the conversions failed.
 148
 149 **/
 150 typedef
 151 BOOLEAN
 152 (EFIAPI *EFI_UNICODE_COLLATION_STRTOFAT)(
 153   IN EFI_UNICODE_COLLATION_PROTOCOL         *This,
 154   IN CHAR16                                 *String,
 155   IN UINTN                                  FatSize,
 156   OUT CHAR8                                 *Fat
 157   );
 158
 159 ///
 160 /// The EFI_UNICODE_COLLATION_PROTOCOL is used to perform case-insensitive
 161 /// comparisons of strings.
 162 ///
 163 struct _EFI_UNICODE_COLLATION_PROTOCOL {
 164   EFI_UNICODE_COLLATION_STRICOLL      StriColl;
 165   EFI_UNICODE_COLLATION_METAIMATCH    MetaiMatch;
 166   EFI_UNICODE_COLLATION_STRLWR        StrLwr;
 167   EFI_UNICODE_COLLATION_STRUPR        StrUpr;
 168
 169   //
 170   // for supporting fat volumes
 171   //
 172   EFI_UNICODE_COLLATION_FATTOSTR      FatToStr;
 173   EFI_UNICODE_COLLATION_STRTOFAT      StrToFat;
 174
 175   ///
 176   /// A Null-terminated ASCII string array that contains one or more language codes.
 177   /// When this field is used for UnicodeCollation2, it is specified in RFC 4646 format.
 178   /// When it is used for UnicodeCollation, it is specified in ISO 639-2 format.
 179   ///
 180   CHAR8                               *SupportedLanguages;
 181 };
 182
 183 extern EFI_GUID  gEfiUnicodeCollationProtocolGuid;
 184 extern EFI_GUID  gEfiUnicodeCollation2ProtocolGuid;
 185
 186 #endif