]>
git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/PrintLib.h
2 Library that provides print services
4 Copyright (c) 2006 - 2007, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 Module Name: PrintLib.h
17 #ifndef __PRINT_LIB_H__
18 #define __PRINT_LIB_H__
21 /// Define the maximum number of characters that are required to
22 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL
25 /// Maximum Length Decimal String = 28
26 /// "-9,223,372,036,854,775,808"
27 /// Maximum Length Hexidecimal String = 17
28 /// "FFFFFFFFFFFFFFFF"
29 /// Maximum Length GUID = 37
30 /// "00000000-0000-0000-0000-000000000000"
31 /// Maximum Length TIME = 18
32 /// "12/12/2006 12:12"
34 #define MAXIMUM_VALUE_CHARACTERS 38
37 /// Flags bitmask values use in UnicodeValueToString() and
38 /// AsciiValueToString()
40 #define LEFT_JUSTIFY 0x01
41 #define COMMA_TYPE 0x08
42 #define PREFIX_ZERO 0x20
43 #define RADIX_HEX 0x80
46 Produces a Null-terminated Unicode string in an output buffer based on
47 a Null-terminated Unicode format string and a VA_LIST argument list
49 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
51 The Unicode string is produced by parsing the format string specified by FormatString.
52 Arguments are pulled from the variable argument list specified by Marker based on the
53 contents of the format string.
54 The number of Unicode characters in the produced output buffer is returned not including
56 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
58 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
59 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
60 If BufferSize > 1 and FormatString is NULL, then ASSERT().
61 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
62 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
63 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
65 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
66 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
67 Null-terminator, then ASSERT().
69 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
71 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
72 @param FormatString Null-terminated Unicode format string.
73 @param Marker VA_LIST marker for the variable argument list.
75 @return The number of Unicode characters in the produced output buffer not including the
82 OUT CHAR16
*StartOfBuffer
,
84 IN CONST CHAR16
*FormatString
,
89 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
90 Unicode format string and variable argument list.
92 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
94 The Unicode string is produced by parsing the format string specified by FormatString.
95 Arguments are pulled from the variable argument list based on the contents of the format string.
96 The number of Unicode characters in the produced output buffer is returned not including
98 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
100 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
101 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
102 If BufferSize > 1 and FormatString is NULL, then ASSERT().
103 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
104 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
105 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
107 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
108 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
109 Null-terminator, then ASSERT().
111 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
113 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
114 @param FormatString Null-terminated Unicode format string.
116 @return The number of Unicode characters in the produced output buffer not including the
123 OUT CHAR16
*StartOfBuffer
,
125 IN CONST CHAR16
*FormatString
,
130 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
131 ASCII format string and a VA_LIST argument list
133 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
135 The Unicode string is produced by parsing the format string specified by FormatString.
136 Arguments are pulled from the variable argument list specified by Marker based on the
137 contents of the format string.
138 The number of Unicode characters in the produced output buffer is returned not including
140 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
142 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
143 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
144 If BufferSize > 1 and FormatString is NULL, then ASSERT().
145 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
146 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
148 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
149 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
150 Null-terminator, then ASSERT().
152 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
154 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
155 @param FormatString Null-terminated Unicode format string.
156 @param Marker VA_LIST marker for the variable argument list.
158 @return The number of Unicode characters in the produced output buffer not including the
164 UnicodeVSPrintAsciiFormat (
165 OUT CHAR16
*StartOfBuffer
,
167 IN CONST CHAR8
*FormatString
,
172 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
173 ASCII format string and variable argument list.
175 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
177 The Unicode string is produced by parsing the format string specified by FormatString.
178 Arguments are pulled from the variable argument list based on the contents of the
180 The number of Unicode characters in the produced output buffer is returned not including
182 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
184 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
185 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
186 If BufferSize > 1 and FormatString is NULL, then ASSERT().
187 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
188 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
190 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
191 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
192 Null-terminator, then ASSERT().
194 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
196 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
197 @param FormatString Null-terminated Unicode format string.
199 @return The number of Unicode characters in the produced output buffer not including the
205 UnicodeSPrintAsciiFormat (
206 OUT CHAR16
*StartOfBuffer
,
208 IN CONST CHAR8
*FormatString
,
213 Converts a decimal value to a Null-terminated Unicode string.
215 Converts the decimal number specified by Value to a Null-terminated Unicode
216 string specified by Buffer containing at most Width characters. No padding of spaces
217 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
218 The number of Unicode characters in Buffer is returned not including the Null-terminator.
219 If the conversion contains more than Width characters, then only the first
220 Width characters are returned, and the total number of characters
221 required to perform the conversion is returned.
222 Additional conversion parameters are specified in Flags.
224 The Flags bit LEFT_JUSTIFY is always ignored.
225 All conversions are left justified in Buffer.
226 If Width is 0, PREFIX_ZERO is ignored in Flags.
227 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
228 are inserted every 3rd digit starting from the right.
229 If HEX_RADIX is set in Flags, then the output buffer will be
230 formatted in hexadecimal format.
231 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
232 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
233 then Buffer is padded with '0' characters so the combination of the optional '-'
234 sign character, '0' characters, digit characters for Value, and the Null-terminator
235 add up to Width characters.
236 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
237 If Buffer is NULL, then ASSERT().
238 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
239 If unsupported bits are set in Flags, then ASSERT().
240 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
241 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
243 @param Buffer Pointer to the output buffer for the produced Null-terminated
245 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
246 @param Value The 64-bit signed value to convert to a string.
247 @param Width The maximum number of Unicode characters to place in Buffer, not including
250 @return The number of Unicode characters in Buffer not including the Null-terminator.
255 UnicodeValueToString (
256 IN OUT CHAR16
*Buffer
,
263 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
264 ASCII format string and a VA_LIST argument list.
266 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
268 The ASCII string is produced by parsing the format string specified by FormatString.
269 Arguments are pulled from the variable argument list specified by Marker based on
270 the contents of the format string.
271 The number of ASCII characters in the produced output buffer is returned not including
273 If BufferSize is 0, then no output buffer is produced and 0 is returned.
275 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
276 If BufferSize > 0 and FormatString is NULL, then ASSERT().
277 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
278 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
280 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
281 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
282 Null-terminator, then ASSERT().
284 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
286 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
287 @param FormatString Null-terminated Unicode format string.
288 @param Marker VA_LIST marker for the variable argument list.
290 @return The number of ASCII characters in the produced output buffer not including the
297 OUT CHAR8
*StartOfBuffer
,
299 IN CONST CHAR8
*FormatString
,
304 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
305 ASCII format string and variable argument list.
307 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
309 The ASCII string is produced by parsing the format string specified by FormatString.
310 Arguments are pulled from the variable argument list based on the contents of the
312 The number of ASCII characters in the produced output buffer is returned not including
314 If BufferSize is 0, then no output buffer is produced and 0 is returned.
316 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
317 If BufferSize > 0 and FormatString is NULL, then ASSERT().
318 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
319 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
321 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
322 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
323 Null-terminator, then ASSERT().
325 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
327 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
328 @param FormatString Null-terminated Unicode format string.
330 @return The number of ASCII characters in the produced output buffer not including the
337 OUT CHAR8
*StartOfBuffer
,
339 IN CONST CHAR8
*FormatString
,
344 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
345 ASCII format string and a VA_LIST argument list.
347 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
349 The ASCII string is produced by parsing the format string specified by FormatString.
350 Arguments are pulled from the variable argument list specified by Marker based on
351 the contents of the format string.
352 The number of ASCII characters in the produced output buffer is returned not including
354 If BufferSize is 0, then no output buffer is produced and 0 is returned.
356 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
357 If BufferSize > 0 and FormatString is NULL, then ASSERT().
358 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
359 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
360 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
362 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
363 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
364 Null-terminator, then ASSERT().
366 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
368 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
369 @param FormatString Null-terminated Unicode format string.
370 @param Marker VA_LIST marker for the variable argument list.
372 @return The number of ASCII characters in the produced output buffer not including the
378 AsciiVSPrintUnicodeFormat (
379 OUT CHAR8
*StartOfBuffer
,
381 IN CONST CHAR16
*FormatString
,
386 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
387 ASCII format string and variable argument list.
389 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
391 The ASCII string is produced by parsing the format string specified by FormatString.
392 Arguments are pulled from the variable argument list based on the contents of the
394 The number of ASCII characters in the produced output buffer is returned not including
396 If BufferSize is 0, then no output buffer is produced and 0 is returned.
398 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
399 If BufferSize > 0 and FormatString is NULL, then ASSERT().
400 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
401 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
402 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
404 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
405 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
406 Null-terminator, then ASSERT().
408 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
410 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
411 @param FormatString Null-terminated Unicode format string.
413 @return The number of ASCII characters in the produced output buffer not including the
419 AsciiSPrintUnicodeFormat (
420 OUT CHAR8
*StartOfBuffer
,
422 IN CONST CHAR16
*FormatString
,
427 Converts a decimal value to a Null-terminated ASCII string.
429 Converts the decimal number specified by Value to a Null-terminated ASCII string
430 specified by Buffer containing at most Width characters. No padding of spaces
432 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
433 The number of ASCII characters in Buffer is returned not including the Null-terminator.
434 If the conversion contains more than Width characters, then only the first Width
435 characters are returned, and the total number of characters required to perform
436 the conversion is returned.
437 Additional conversion parameters are specified in Flags.
438 The Flags bit LEFT_JUSTIFY is always ignored.
439 All conversions are left justified in Buffer.
440 If Width is 0, PREFIX_ZERO is ignored in Flags.
441 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
442 are inserted every 3rd digit starting from the right.
443 If HEX_RADIX is set in Flags, then the output buffer will be
444 formatted in hexadecimal format.
445 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
446 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
447 then Buffer is padded with '0' characters so the combination of the optional '-'
448 sign character, '0' characters, digit characters for Value, and the Null-terminator
449 add up to Width characters.
451 If Buffer is NULL, then ASSERT().
452 If unsupported bits are set in Flags, then ASSERT().
453 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
454 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
456 @param Buffer Pointer to the output buffer for the produced Null-terminated
458 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
459 @param Value The 64-bit signed value to convert to a string.
460 @param Width The maximum number of ASCII characters to place in Buffer, not including
463 @return The number of ASCII characters in Buffer not including the Null-terminator.
469 IN OUT CHAR8
*Buffer
,