xref: /illumos-gate/usr/src/boot/efi/include/Protocol/UnicodeCollation.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
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
187