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