MdeModulePkg/Print2: Refine the comment for ASCII_VALUE_TO_STRING_S
[mirror_edk2.git] / MdeModulePkg / Include / Protocol / Print2.h
CommitLineData
217697af 1/** @file\r
2\r
e43adbaf
HW
3 Produces EFI_PRINT2_PROTOCOL and EFI_PRINT2S_PROTOCOL.\r
4 These protocols define basic print functions to print the format unicode and\r
5 ascii string.\r
217697af 6\r
0b6642e6 7Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>\r
64a80549 8This program and the accompanying materials are licensed and made available under \r
9the terms and conditions of the BSD License that accompanies this distribution. \r
10The full text of the license may be found at\r
11http://opensource.org/licenses/bsd-license.php. \r
217697af 12\r
64a80549 13THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
217697af 14WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
15\r
16**/\r
17\r
18#ifndef __PPRINT2_H__\r
19#define __PPRINT2_H__\r
20\r
2b4d6ac8 21#define EFI_PRINT2_PROTOCOL_GUID \\r
504dcb0a 22 { 0xf05976ef, 0x83f1, 0x4f3d, { 0x86, 0x19, 0xf7, 0x59, 0x5d, 0x41, 0xe5, 0x38 } }\r
217697af 23\r
24//\r
25// Forward reference for pure ANSI compatability\r
26//\r
27typedef struct _EFI_PRINT2_PROTOCOL EFI_PRINT2_PROTOCOL;\r
28\r
29/**\r
0b6642e6
HW
30 Produces a Null-terminated Unicode string in an output buffer based on\r
31 a Null-terminated Unicode format string and a BASE_LIST argument list.\r
32\r
33 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
34 and BufferSize.\r
35 The Unicode string is produced by parsing the format string specified by FormatString.\r
36 Arguments are pulled from the variable argument list specified by Marker based on the\r
37 contents of the format string.\r
38 The number of Unicode characters in the produced output buffer is returned not including\r
39 the Null-terminator.\r
217697af 40\r
0b6642e6
HW
41 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().\r
42 If FormatString is not aligned on a 16-bit boundary, then ASSERT().\r
43\r
44 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
45 unmodified and 0 is returned.\r
46 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
47 unmodified and 0 is returned.\r
48 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >\r
49 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output\r
50 buffer is unmodified and 0 is returned.\r
51 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than\r
52 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then\r
53 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
54\r
55 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.\r
56\r
57 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
217697af 58 Unicode string.\r
59 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6 60 @param FormatString A Null-terminated Unicode format string.\r
504dcb0a 61 @param Marker BASE_LIST marker for the variable argument list.\r
0b6642e6
HW
62\r
63 @return The number of Unicode characters in the produced output buffer not including the\r
217697af 64 Null-terminator.\r
65\r
66**/\r
67typedef\r
68UINTN\r
0c1a4aa6 69(EFIAPI *UNICODE_BS_PRINT)(\r
217697af 70 OUT CHAR16 *StartOfBuffer,\r
71 IN UINTN BufferSize,\r
72 IN CONST CHAR16 *FormatString,\r
504dcb0a 73 IN BASE_LIST Marker\r
217697af 74 );\r
75\r
e996a8c9 76/**\r
0b6642e6 77 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated\r
e996a8c9 78 Unicode format string and variable argument list.\r
0b6642e6
HW
79\r
80 This function is similar as snprintf_s defined in C11.\r
81\r
82 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
83 and BufferSize.\r
e996a8c9 84 The Unicode string is produced by parsing the format string specified by FormatString.\r
85 Arguments are pulled from the variable argument list based on the contents of the format string.\r
0b6642e6
HW
86 The number of Unicode characters in the produced output buffer is returned not including\r
87 the Null-terminator.\r
88\r
89 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().\r
90 If FormatString is not aligned on a 16-bit boundary, then ASSERT().\r
91\r
92 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
93 unmodified and 0 is returned.\r
94 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
95 unmodified and 0 is returned.\r
96 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >\r
97 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output\r
98 buffer is unmodified and 0 is returned.\r
99 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than\r
100 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then\r
101 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
e996a8c9 102\r
0b6642e6
HW
103 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.\r
104\r
105 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
e996a8c9 106 Unicode string.\r
107 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6
HW
108 @param FormatString A Null-terminated Unicode format string.\r
109 @param ... Variable argument list whose contents are accessed based on the\r
e996a8c9 110 format string specified by FormatString.\r
0b6642e6 111\r
e996a8c9 112 @return The number of Unicode characters in the produced output buffer not including the\r
113 Null-terminator.\r
114\r
115**/\r
116typedef\r
117UINTN\r
0c1a4aa6 118(EFIAPI *UNICODE_S_PRINT)(\r
e996a8c9 119 OUT CHAR16 *StartOfBuffer,\r
120 IN UINTN BufferSize,\r
121 IN CONST CHAR16 *FormatString,\r
122 ...\r
123 );\r
124\r
217697af 125/**\r
0b6642e6
HW
126 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated\r
127 ASCII format string and a BASE_LIST argument list.\r
128\r
129 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
130 and BufferSize.\r
217697af 131 The Unicode string is produced by parsing the format string specified by FormatString.\r
0b6642e6 132 Arguments are pulled from the variable argument list specified by Marker based on the\r
217697af 133 contents of the format string.\r
0b6642e6
HW
134 The number of Unicode characters in the produced output buffer is returned not including\r
135 the Null-terminator.\r
136\r
137 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().\r
217697af 138\r
0b6642e6
HW
139 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
140 unmodified and 0 is returned.\r
141 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
142 unmodified and 0 is returned.\r
143 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >\r
144 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output\r
145 buffer is unmodified and 0 is returned.\r
217697af 146 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than\r
0b6642e6
HW
147 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then\r
148 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
149\r
150 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.\r
217697af 151\r
0b6642e6 152 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
217697af 153 Unicode string.\r
154 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6 155 @param FormatString A Null-terminated ASCII format string.\r
504dcb0a 156 @param Marker BASE_LIST marker for the variable argument list.\r
0b6642e6 157\r
217697af 158 @return The number of Unicode characters in the produced output buffer not including the\r
159 Null-terminator.\r
160\r
161**/\r
162typedef\r
163UINTN\r
0c1a4aa6 164(EFIAPI *UNICODE_BS_PRINT_ASCII_FORMAT)(\r
217697af 165 OUT CHAR16 *StartOfBuffer,\r
166 IN UINTN BufferSize,\r
167 IN CONST CHAR8 *FormatString,\r
504dcb0a 168 IN BASE_LIST Marker\r
217697af 169 );\r
170\r
e996a8c9 171/**\r
0b6642e6
HW
172 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated\r
173 ASCII format string and variable argument list.\r
174\r
175 This function is similar as snprintf_s defined in C11.\r
176\r
177 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
178 and BufferSize.\r
e996a8c9 179 The Unicode string is produced by parsing the format string specified by FormatString.\r
0b6642e6
HW
180 Arguments are pulled from the variable argument list based on the contents of the\r
181 format string.\r
182 The number of Unicode characters in the produced output buffer is returned not including\r
183 the Null-terminator.\r
e996a8c9 184\r
0b6642e6
HW
185 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().\r
186\r
187 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
188 unmodified and 0 is returned.\r
189 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
190 unmodified and 0 is returned.\r
191 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >\r
192 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output\r
193 buffer is unmodified and 0 is returned.\r
e996a8c9 194 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than\r
0b6642e6
HW
195 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then\r
196 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
e996a8c9 197\r
0b6642e6
HW
198 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.\r
199\r
200 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
e996a8c9 201 Unicode string.\r
202 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6
HW
203 @param FormatString A Null-terminated ASCII format string.\r
204 @param ... Variable argument list whose contents are accessed based on the\r
e996a8c9 205 format string specified by FormatString.\r
0b6642e6 206\r
e996a8c9 207 @return The number of Unicode characters in the produced output buffer not including the\r
208 Null-terminator.\r
209\r
210**/\r
211typedef\r
212UINTN\r
0c1a4aa6 213(EFIAPI *UNICODE_S_PRINT_ASCII_FORMAT)(\r
e996a8c9 214 OUT CHAR16 *StartOfBuffer,\r
215 IN UINTN BufferSize,\r
216 IN CONST CHAR8 *FormatString,\r
217 ...\r
218 );\r
219\r
217697af 220/**\r
221 Converts a decimal value to a Null-terminated Unicode string.\r
222 \r
223 Converts the decimal number specified by Value to a Null-terminated Unicode \r
224 string specified by Buffer containing at most Width characters. No padding of spaces \r
e9b67286 225 is ever performed. If Width is 0, then a width of MAXIMUM_VALUE_CHARACTERS is assumed.\r
226 This function returns the number of Unicode characters in Buffer, not including\r
227 the Null-terminator.\r
228 If the conversion contains more than Width characters, this function returns \r
229 the first Width characters in the conversion, along with the total number of characters in the conversion.\r
217697af 230 Additional conversion parameters are specified in Flags. \r
231 \r
232 The Flags bit LEFT_JUSTIFY is always ignored.\r
233 All conversions are left justified in Buffer.\r
234 If Width is 0, PREFIX_ZERO is ignored in Flags.\r
235 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas\r
236 are inserted every 3rd digit starting from the right.\r
df8d0595 237 If RADIX_HEX is set in Flags, then the output buffer will be \r
217697af 238 formatted in hexadecimal format.\r
df8d0595 239 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.\r
217697af 240 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, \r
241 then Buffer is padded with '0' characters so the combination of the optional '-' \r
242 sign character, '0' characters, digit characters for Value, and the Null-terminator\r
243 add up to Width characters.\r
df8d0595 244 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().\r
217697af 245 If Buffer is NULL, then ASSERT().\r
246 If Buffer is not aligned on a 16-bit boundary, then ASSERT().\r
247 If unsupported bits are set in Flags, then ASSERT().\r
df8d0595 248 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().\r
217697af 249 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()\r
250\r
64a80549 251 @param Buffer The pointer to the output buffer for the produced Null-terminated\r
217697af 252 Unicode string.\r
253 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.\r
254 @param Value The 64-bit signed value to convert to a string.\r
255 @param Width The maximum number of Unicode characters to place in Buffer, not including\r
256 the Null-terminator.\r
257 \r
258 @return The number of Unicode characters in Buffer not including the Null-terminator.\r
259\r
260**/\r
261typedef\r
262UINTN\r
0c1a4aa6 263(EFIAPI *UNICODE_VALUE_TO_STRING)(\r
217697af 264 IN OUT CHAR16 *Buffer,\r
265 IN UINTN Flags,\r
266 IN INT64 Value,\r
267 IN UINTN Width\r
268 );\r
269\r
270/**\r
271 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
504dcb0a 272 ASCII format string and a BASE_LIST argument list.\r
0b6642e6
HW
273\r
274 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
275 and BufferSize.\r
217697af 276 The ASCII string is produced by parsing the format string specified by FormatString.\r
0b6642e6 277 Arguments are pulled from the variable argument list specified by Marker based on\r
217697af 278 the contents of the format string.\r
0b6642e6
HW
279 The number of ASCII characters in the produced output buffer is returned not including\r
280 the Null-terminator.\r
217697af 281\r
0b6642e6
HW
282 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
283 unmodified and 0 is returned.\r
284 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
285 unmodified and 0 is returned.\r
286 If PcdMaximumAsciiStringLength is not zero, and BufferSize >\r
287 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer\r
288 is unmodified and 0 is returned.\r
217697af 289 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than\r
0b6642e6
HW
290 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then\r
291 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
292\r
293 If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
217697af 294\r
0b6642e6 295 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
217697af 296 ASCII string.\r
297 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6 298 @param FormatString A Null-terminated ASCII format string.\r
504dcb0a 299 @param Marker BASE_LIST marker for the variable argument list.\r
0b6642e6 300\r
217697af 301 @return The number of ASCII characters in the produced output buffer not including the\r
302 Null-terminator.\r
303\r
304**/\r
305typedef\r
306UINTN\r
0c1a4aa6 307(EFIAPI *ASCII_BS_PRINT)(\r
217697af 308 OUT CHAR8 *StartOfBuffer,\r
309 IN UINTN BufferSize,\r
310 IN CONST CHAR8 *FormatString,\r
504dcb0a 311 IN BASE_LIST Marker\r
217697af 312 );\r
313\r
e996a8c9 314/**\r
315 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
0b6642e6
HW
316 ASCII format string and variable argument list.\r
317\r
318 This function is similar as snprintf_s defined in C11.\r
319\r
320 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
321 and BufferSize.\r
e996a8c9 322 The ASCII string is produced by parsing the format string specified by FormatString.\r
0b6642e6
HW
323 Arguments are pulled from the variable argument list based on the contents of the\r
324 format string.\r
325 The number of ASCII characters in the produced output buffer is returned not including\r
326 the Null-terminator.\r
e996a8c9 327\r
0b6642e6
HW
328 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
329 unmodified and 0 is returned.\r
330 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
331 unmodified and 0 is returned.\r
332 If PcdMaximumAsciiStringLength is not zero, and BufferSize >\r
333 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer\r
334 is unmodified and 0 is returned.\r
e996a8c9 335 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than\r
0b6642e6
HW
336 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then\r
337 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
338\r
339 If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
e996a8c9 340\r
0b6642e6 341 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
e996a8c9 342 ASCII string.\r
343 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6
HW
344 @param FormatString A Null-terminated ASCII format string.\r
345 @param ... Variable argument list whose contents are accessed based on the\r
e996a8c9 346 format string specified by FormatString.\r
0b6642e6 347\r
e996a8c9 348 @return The number of ASCII characters in the produced output buffer not including the\r
349 Null-terminator.\r
350\r
351**/\r
352typedef\r
353UINTN\r
0c1a4aa6 354(EFIAPI *ASCII_S_PRINT)(\r
e996a8c9 355 OUT CHAR8 *StartOfBuffer,\r
356 IN UINTN BufferSize,\r
357 IN CONST CHAR8 *FormatString,\r
358 ...\r
359 );\r
360\r
217697af 361/**\r
362 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
504dcb0a 363 Unicode format string and a BASE_LIST argument list.\r
0b6642e6
HW
364\r
365 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
366 and BufferSize.\r
217697af 367 The ASCII string is produced by parsing the format string specified by FormatString.\r
0b6642e6 368 Arguments are pulled from the variable argument list specified by Marker based on\r
217697af 369 the contents of the format string.\r
0b6642e6
HW
370 The number of ASCII characters in the produced output buffer is returned not including\r
371 the Null-terminator.\r
217697af 372\r
0b6642e6
HW
373 If FormatString is not aligned on a 16-bit boundary, then ASSERT().\r
374\r
375 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
376 unmodified and 0 is returned.\r
377 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
378 unmodified and 0 is returned.\r
379 If PcdMaximumAsciiStringLength is not zero, and BufferSize >\r
380 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer\r
381 is unmodified and 0 is returned.\r
217697af 382 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than\r
0b6642e6
HW
383 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then\r
384 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
385\r
386 If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
217697af 387\r
0b6642e6 388 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
217697af 389 ASCII string.\r
390 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6 391 @param FormatString A Null-terminated Unicode format string.\r
504dcb0a 392 @param Marker BASE_LIST marker for the variable argument list.\r
0b6642e6 393\r
217697af 394 @return The number of ASCII characters in the produced output buffer not including the\r
395 Null-terminator.\r
396\r
397**/\r
398typedef\r
399UINTN\r
0c1a4aa6 400(EFIAPI *ASCII_BS_PRINT_UNICODE_FORMAT)(\r
217697af 401 OUT CHAR8 *StartOfBuffer,\r
402 IN UINTN BufferSize,\r
403 IN CONST CHAR16 *FormatString,\r
504dcb0a 404 IN BASE_LIST Marker\r
217697af 405 );\r
406\r
e996a8c9 407/**\r
408 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
409 Unicode format string and variable argument list.\r
0b6642e6
HW
410\r
411 This function is similar as snprintf_s defined in C11.\r
412\r
413 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
414 and BufferSize.\r
e996a8c9 415 The ASCII string is produced by parsing the format string specified by FormatString.\r
0b6642e6
HW
416 Arguments are pulled from the variable argument list based on the contents of the\r
417 format string.\r
418 The number of ASCII characters in the produced output buffer is returned not including\r
419 the Null-terminator.\r
420\r
421 If FormatString is not aligned on a 16-bit boundary, then ASSERT().\r
e996a8c9 422\r
0b6642e6
HW
423 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is\r
424 unmodified and 0 is returned.\r
425 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is\r
426 unmodified and 0 is returned.\r
427 If PcdMaximumAsciiStringLength is not zero, and BufferSize >\r
428 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer\r
429 is unmodified and 0 is returned.\r
430 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than\r
431 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then\r
432 ASSERT(). Also, the output buffer is unmodified and 0 is returned.\r
433\r
434 If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
e996a8c9 435\r
0b6642e6 436 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated\r
e996a8c9 437 ASCII string.\r
438 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.\r
0b6642e6
HW
439 @param FormatString A Null-terminated Unicode format string.\r
440 @param ... Variable argument list whose contents are accessed based on the\r
e996a8c9 441 format string specified by FormatString.\r
0b6642e6 442\r
e996a8c9 443 @return The number of ASCII characters in the produced output buffer not including the\r
444 Null-terminator.\r
445\r
446**/\r
447typedef\r
448UINTN\r
0c1a4aa6 449(EFIAPI *ASCII_S_PRINT_UNICODE_FORMAT)(\r
e996a8c9 450 OUT CHAR8 *StartOfBuffer,\r
451 IN UINTN BufferSize,\r
452 IN CONST CHAR16 *FormatString,\r
453 ...\r
454 );\r
455\r
217697af 456/**\r
457 Converts a decimal value to a Null-terminated ASCII string.\r
458 \r
459 Converts the decimal number specified by Value to a Null-terminated ASCII string \r
e40b7d5d 460 specified by Buffer containing at most Width characters. No padding of spaces is ever performed.\r
e9b67286 461 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.\r
217697af 462 The number of ASCII characters in Buffer is returned not including the Null-terminator.\r
463 If the conversion contains more than Width characters, then only the first Width\r
464 characters are returned, and the total number of characters required to perform\r
465 the conversion is returned.\r
466 Additional conversion parameters are specified in Flags. \r
467 The Flags bit LEFT_JUSTIFY is always ignored.\r
468 All conversions are left justified in Buffer.\r
469 If Width is 0, PREFIX_ZERO is ignored in Flags.\r
470 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas\r
471 are inserted every 3rd digit starting from the right.\r
df8d0595 472 If RADIX_HEX is set in Flags, then the output buffer will be \r
217697af 473 formatted in hexadecimal format.\r
df8d0595 474 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.\r
217697af 475 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, \r
476 then Buffer is padded with '0' characters so the combination of the optional '-' \r
477 sign character, '0' characters, digit characters for Value, and the Null-terminator\r
478 add up to Width characters.\r
479 \r
480 If Buffer is NULL, then ASSERT().\r
481 If unsupported bits are set in Flags, then ASSERT().\r
df8d0595 482 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().\r
217697af 483 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()\r
484\r
64a80549 485 @param Buffer The pointer to the output buffer for the produced Null-terminated\r
217697af 486 ASCII string.\r
487 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.\r
488 @param Value The 64-bit signed value to convert to a string.\r
489 @param Width The maximum number of ASCII characters to place in Buffer, not including\r
490 the Null-terminator.\r
491 \r
492 @return The number of ASCII characters in Buffer not including the Null-terminator.\r
493\r
494**/\r
495typedef\r
496UINTN\r
0c1a4aa6 497(EFIAPI *ASCII_VALUE_TO_STRING)(\r
e996a8c9 498 OUT CHAR8 *Buffer,\r
499 IN UINTN Flags,\r
500 IN INT64 Value,\r
501 IN UINTN Width\r
217697af 502 );\r
503\r
504struct _EFI_PRINT2_PROTOCOL {\r
504dcb0a 505 UNICODE_BS_PRINT UnicodeBSPrint;\r
506 UNICODE_S_PRINT UnicodeSPrint;\r
507 UNICODE_BS_PRINT_ASCII_FORMAT UnicodeBSPrintAsciiFormat;\r
508 UNICODE_S_PRINT_ASCII_FORMAT UnicodeSPrintAsciiFormat;\r
509 UNICODE_VALUE_TO_STRING UnicodeValueToString;\r
510 ASCII_BS_PRINT AsciiBSPrint;\r
511 ASCII_S_PRINT AsciiSPrint;\r
512 ASCII_BS_PRINT_UNICODE_FORMAT AsciiBSPrintUnicodeFormat;\r
513 ASCII_S_PRINT_UNICODE_FORMAT AsciiSPrintUnicodeFormat;\r
514 ASCII_VALUE_TO_STRING AsciiValueToString;\r
217697af 515};\r
516\r
517extern EFI_GUID gEfiPrint2ProtocolGuid;\r
518\r
e43adbaf
HW
519\r
520#define EFI_PRINT2S_PROTOCOL_GUID \\r
521 { 0xcc252d2, 0xc106, 0x4661, { 0xb5, 0xbd, 0x31, 0x47, 0xa4, 0xf8, 0x1f, 0x92 } }\r
522\r
523//\r
524// Forward reference for pure ANSI compatability\r
525//\r
526typedef struct _EFI_PRINT2S_PROTOCOL EFI_PRINT2S_PROTOCOL;\r
527\r
528/**\r
529 Converts a decimal value to a Null-terminated Unicode string.\r
530\r
531 Converts the decimal number specified by Value to a Null-terminated Unicode\r
532 string specified by Buffer containing at most Width characters. No padding of\r
533 spaces is ever performed. If Width is 0 then a width of\r
534 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than\r
535 Width characters, then only the first Width characters are placed in Buffer.\r
536 Additional conversion parameters are specified in Flags.\r
537\r
538 The Flags bit LEFT_JUSTIFY is always ignored.\r
539 All conversions are left justified in Buffer.\r
540 If Width is 0, PREFIX_ZERO is ignored in Flags.\r
541 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and\r
542 commas are inserted every 3rd digit starting from the right.\r
543 If RADIX_HEX is set in Flags, then the output buffer will be formatted in\r
544 hexadecimal format.\r
545 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in\r
546 Buffer is a '-'.\r
547 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then\r
548 Buffer is padded with '0' characters so the combination of the optional '-'\r
549 sign character, '0' characters, digit characters for Value, and the\r
550 Null-terminator add up to Width characters.\r
551\r
552 If Buffer is not aligned on a 16-bit boundary, then ASSERT().\r
553 If an error would be returned, then the function will also ASSERT().\r
554\r
555 @param Buffer The pointer to the output buffer for the produced\r
556 Null-terminated Unicode string.\r
557 @param BufferSize The size of Buffer in bytes, including the\r
558 Null-terminator.\r
559 @param Flags The bitmask of flags that specify left justification,\r
560 zero pad, and commas.\r
561 @param Value The 64-bit signed value to convert to a string.\r
562 @param Width The maximum number of Unicode characters to place in\r
563 Buffer, not including the Null-terminator.\r
564\r
565 @retval RETURN_SUCCESS The decimal value is converted.\r
566 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted\r
567 value.\r
568 @retval RETURN_INVALID_PARAMETER If Buffer is NULL.\r
569 If PcdMaximumUnicodeStringLength is not\r
570 zero, and BufferSize is greater than\r
571 (PcdMaximumUnicodeStringLength *\r
572 sizeof (CHAR16) + 1).\r
573 If unsupported bits are set in Flags.\r
574 If both COMMA_TYPE and RADIX_HEX are set in\r
575 Flags.\r
576 If Width >= MAXIMUM_VALUE_CHARACTERS.\r
577\r
578**/\r
579typedef\r
580RETURN_STATUS\r
581(EFIAPI *UNICODE_VALUE_TO_STRING_S)(\r
582 IN OUT CHAR16 *Buffer,\r
583 IN UINTN BufferSize,\r
584 IN UINTN Flags,\r
585 IN INT64 Value,\r
586 IN UINTN Width\r
587 );\r
588\r
589/**\r
590 Converts a decimal value to a Null-terminated Ascii string.\r
591\r
592 Converts the decimal number specified by Value to a Null-terminated Ascii\r
593 string specified by Buffer containing at most Width characters. No padding of\r
594 spaces is ever performed. If Width is 0 then a width of\r
595 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than\r
596 Width characters, then only the first Width characters are placed in Buffer.\r
597 Additional conversion parameters are specified in Flags.\r
598\r
599 The Flags bit LEFT_JUSTIFY is always ignored.\r
600 All conversions are left justified in Buffer.\r
601 If Width is 0, PREFIX_ZERO is ignored in Flags.\r
602 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and\r
603 commas are inserted every 3rd digit starting from the right.\r
604 If RADIX_HEX is set in Flags, then the output buffer will be formatted in\r
605 hexadecimal format.\r
606 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in\r
607 Buffer is a '-'.\r
608 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then\r
609 Buffer is padded with '0' characters so the combination of the optional '-'\r
610 sign character, '0' characters, digit characters for Value, and the\r
611 Null-terminator add up to Width characters.\r
612\r
e5735b98 613 If an error would be returned, then the function will ASSERT().\r
e43adbaf
HW
614\r
615 @param Buffer The pointer to the output buffer for the produced\r
616 Null-terminated Ascii string.\r
617 @param BufferSize The size of Buffer in bytes, including the\r
618 Null-terminator.\r
619 @param Flags The bitmask of flags that specify left justification,\r
620 zero pad, and commas.\r
621 @param Value The 64-bit signed value to convert to a string.\r
622 @param Width The maximum number of Ascii characters to place in\r
623 Buffer, not including the Null-terminator.\r
624\r
625 @retval RETURN_SUCCESS The decimal value is converted.\r
626 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted\r
627 value.\r
628 @retval RETURN_INVALID_PARAMETER If Buffer is NULL.\r
629 If PcdMaximumAsciiStringLength is not\r
630 zero, and BufferSize is greater than\r
631 PcdMaximumAsciiStringLength.\r
632 If unsupported bits are set in Flags.\r
633 If both COMMA_TYPE and RADIX_HEX are set in\r
634 Flags.\r
635 If Width >= MAXIMUM_VALUE_CHARACTERS.\r
636\r
637**/\r
638typedef\r
639RETURN_STATUS\r
640(EFIAPI *ASCII_VALUE_TO_STRING_S)(\r
641 IN OUT CHAR8 *Buffer,\r
642 IN UINTN BufferSize,\r
643 IN UINTN Flags,\r
644 IN INT64 Value,\r
645 IN UINTN Width\r
646 );\r
647\r
648struct _EFI_PRINT2S_PROTOCOL {\r
649 UNICODE_BS_PRINT UnicodeBSPrint;\r
650 UNICODE_S_PRINT UnicodeSPrint;\r
651 UNICODE_BS_PRINT_ASCII_FORMAT UnicodeBSPrintAsciiFormat;\r
652 UNICODE_S_PRINT_ASCII_FORMAT UnicodeSPrintAsciiFormat;\r
653 UNICODE_VALUE_TO_STRING_S UnicodeValueToStringS;\r
654 ASCII_BS_PRINT AsciiBSPrint;\r
655 ASCII_S_PRINT AsciiSPrint;\r
656 ASCII_BS_PRINT_UNICODE_FORMAT AsciiBSPrintUnicodeFormat;\r
657 ASCII_S_PRINT_UNICODE_FORMAT AsciiSPrintUnicodeFormat;\r
658 ASCII_VALUE_TO_STRING_S AsciiValueToStringS;\r
659};\r
660\r
661extern EFI_GUID gEfiPrint2SProtocolGuid;\r
662\r
217697af 663#endif\r