]>
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.
15 #ifndef __PRINT_LIB_H__
16 #define __PRINT_LIB_H__
19 /// Define the maximum number of characters that are required to
20 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL
23 /// Maximum Length Decimal String = 28
24 /// "-9,223,372,036,854,775,808"
25 /// Maximum Length Hexidecimal String = 17
26 /// "FFFFFFFFFFFFFFFF"
27 /// Maximum Length GUID = 37
28 /// "00000000-0000-0000-0000-000000000000"
29 /// Maximum Length TIME = 18
30 /// "12/12/2006 12:12"
32 #define MAXIMUM_VALUE_CHARACTERS 38
35 /// Flags bitmask values use in UnicodeValueToString() and
36 /// AsciiValueToString()
38 #define LEFT_JUSTIFY 0x01
39 #define COMMA_TYPE 0x08
40 #define PREFIX_ZERO 0x20
41 #define RADIX_HEX 0x80
44 Produces a Null-terminated Unicode string in an output buffer based on
45 a Null-terminated Unicode format string and a VA_LIST argument list
47 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
49 The Unicode string is produced by parsing the format string specified by FormatString.
50 Arguments are pulled from the variable argument list specified by Marker based on the
51 contents of the format string.
52 The number of Unicode characters in the produced output buffer is returned not including
54 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
56 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
57 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
58 If BufferSize > 1 and FormatString is NULL, then ASSERT().
59 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
60 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
61 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
63 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
64 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
65 Null-terminator, then ASSERT().
67 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
69 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
70 @param FormatString Null-terminated Unicode format string.
71 @param Marker VA_LIST marker for the variable argument list.
73 @return The number of Unicode characters in the produced output buffer not including the
80 OUT CHAR16
*StartOfBuffer
,
82 IN CONST CHAR16
*FormatString
,
87 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
88 Unicode format string and variable argument list.
90 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
92 The Unicode string is produced by parsing the format string specified by FormatString.
93 Arguments are pulled from the variable argument list based on the contents of the format string.
94 The number of Unicode characters in the produced output buffer is returned not including
96 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
98 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
99 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
100 If BufferSize > 1 and FormatString is NULL, then ASSERT().
101 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
102 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
103 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
105 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
106 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
107 Null-terminator, then ASSERT().
109 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
111 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
112 @param FormatString Null-terminated Unicode format string.
114 @return The number of Unicode characters in the produced output buffer not including the
121 OUT CHAR16
*StartOfBuffer
,
123 IN CONST CHAR16
*FormatString
,
128 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
129 ASCII format string and a VA_LIST argument list
131 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
133 The Unicode string is produced by parsing the format string specified by FormatString.
134 Arguments are pulled from the variable argument list specified by Marker based on the
135 contents of the format string.
136 The number of Unicode characters in the produced output buffer is returned not including
138 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
140 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
141 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
142 If BufferSize > 1 and FormatString is NULL, then ASSERT().
143 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
144 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
146 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
147 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
148 Null-terminator, then ASSERT().
150 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
152 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
153 @param FormatString Null-terminated Unicode format string.
154 @param Marker VA_LIST marker for the variable argument list.
156 @return The number of Unicode characters in the produced output buffer not including the
162 UnicodeVSPrintAsciiFormat (
163 OUT CHAR16
*StartOfBuffer
,
165 IN CONST CHAR8
*FormatString
,
170 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
171 ASCII format string and variable argument list.
173 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
175 The Unicode string is produced by parsing the format string specified by FormatString.
176 Arguments are pulled from the variable argument list based on the contents of the
178 The number of Unicode characters in the produced output buffer is returned not including
180 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
182 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
183 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
184 If BufferSize > 1 and FormatString is NULL, then ASSERT().
185 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
186 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
188 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
189 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
190 Null-terminator, then ASSERT().
192 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
194 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
195 @param FormatString Null-terminated Unicode format string.
197 @return The number of Unicode characters in the produced output buffer not including the
203 UnicodeSPrintAsciiFormat (
204 OUT CHAR16
*StartOfBuffer
,
206 IN CONST CHAR8
*FormatString
,
211 Converts a decimal value to a Null-terminated Unicode string.
213 Converts the decimal number specified by Value to a Null-terminated Unicode
214 string specified by Buffer containing at most Width characters. No padding of spaces
215 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
216 The number of Unicode characters in Buffer is returned not including the Null-terminator.
217 If the conversion contains more than Width characters, then only the first
218 Width characters are returned, and the total number of characters
219 required to perform the conversion is returned.
220 Additional conversion parameters are specified in Flags.
222 The Flags bit LEFT_JUSTIFY is always ignored.
223 All conversions are left justified in Buffer.
224 If Width is 0, PREFIX_ZERO is ignored in Flags.
225 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
226 are inserted every 3rd digit starting from the right.
227 If HEX_RADIX is set in Flags, then the output buffer will be
228 formatted in hexadecimal format.
229 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
230 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
231 then Buffer is padded with '0' characters so the combination of the optional '-'
232 sign character, '0' characters, digit characters for Value, and the Null-terminator
233 add up to Width characters.
234 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
235 If Buffer is NULL, then ASSERT().
236 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
237 If unsupported bits are set in Flags, then ASSERT().
238 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
239 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
241 @param Buffer Pointer to the output buffer for the produced Null-terminated
243 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
244 @param Value The 64-bit signed value to convert to a string.
245 @param Width The maximum number of Unicode characters to place in Buffer, not including
248 @return The number of Unicode characters in Buffer not including the Null-terminator.
253 UnicodeValueToString (
254 IN OUT CHAR16
*Buffer
,
261 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
262 ASCII format string and a VA_LIST argument list.
264 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
266 The ASCII string is produced by parsing the format string specified by FormatString.
267 Arguments are pulled from the variable argument list specified by Marker based on
268 the contents of the format string.
269 The number of ASCII characters in the produced output buffer is returned not including
271 If BufferSize is 0, then no output buffer is produced and 0 is returned.
273 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
274 If BufferSize > 0 and FormatString is NULL, then ASSERT().
275 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
276 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
278 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
279 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
280 Null-terminator, then ASSERT().
282 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
284 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
285 @param FormatString Null-terminated Unicode format string.
286 @param Marker VA_LIST marker for the variable argument list.
288 @return The number of ASCII characters in the produced output buffer not including the
295 OUT CHAR8
*StartOfBuffer
,
297 IN CONST CHAR8
*FormatString
,
302 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
303 ASCII format string and variable argument list.
305 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
307 The ASCII string is produced by parsing the format string specified by FormatString.
308 Arguments are pulled from the variable argument list based on the contents of the
310 The number of ASCII characters in the produced output buffer is returned not including
312 If BufferSize is 0, then no output buffer is produced and 0 is returned.
314 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
315 If BufferSize > 0 and FormatString is NULL, then ASSERT().
316 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
317 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
319 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
320 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
321 Null-terminator, then ASSERT().
323 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
325 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
326 @param FormatString Null-terminated Unicode format string.
328 @return The number of ASCII characters in the produced output buffer not including the
335 OUT CHAR8
*StartOfBuffer
,
337 IN CONST CHAR8
*FormatString
,
342 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
343 ASCII format string and a VA_LIST argument list.
345 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
347 The ASCII string is produced by parsing the format string specified by FormatString.
348 Arguments are pulled from the variable argument list specified by Marker based on
349 the contents of the format string.
350 The number of ASCII characters in the produced output buffer is returned not including
352 If BufferSize is 0, then no output buffer is produced and 0 is returned.
354 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
355 If BufferSize > 0 and FormatString is NULL, then ASSERT().
356 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
357 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
358 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
360 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
361 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
362 Null-terminator, then ASSERT().
364 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
366 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
367 @param FormatString Null-terminated Unicode format string.
368 @param Marker VA_LIST marker for the variable argument list.
370 @return The number of ASCII characters in the produced output buffer not including the
376 AsciiVSPrintUnicodeFormat (
377 OUT CHAR8
*StartOfBuffer
,
379 IN CONST CHAR16
*FormatString
,
384 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
385 ASCII format string and variable argument list.
387 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
389 The ASCII string is produced by parsing the format string specified by FormatString.
390 Arguments are pulled from the variable argument list based on the contents of the
392 The number of ASCII characters in the produced output buffer is returned not including
394 If BufferSize is 0, then no output buffer is produced and 0 is returned.
396 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
397 If BufferSize > 0 and FormatString is NULL, then ASSERT().
398 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
399 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
400 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
402 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
403 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
404 Null-terminator, then ASSERT().
406 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
408 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
409 @param FormatString Null-terminated Unicode format string.
411 @return The number of ASCII characters in the produced output buffer not including the
417 AsciiSPrintUnicodeFormat (
418 OUT CHAR8
*StartOfBuffer
,
420 IN CONST CHAR16
*FormatString
,
425 Converts a decimal value to a Null-terminated ASCII string.
427 Converts the decimal number specified by Value to a Null-terminated ASCII string
428 specified by Buffer containing at most Width characters. No padding of spaces
430 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
431 The number of ASCII characters in Buffer is returned not including the Null-terminator.
432 If the conversion contains more than Width characters, then only the first Width
433 characters are returned, and the total number of characters required to perform
434 the conversion is returned.
435 Additional conversion parameters are specified in Flags.
436 The Flags bit LEFT_JUSTIFY is always ignored.
437 All conversions are left justified in Buffer.
438 If Width is 0, PREFIX_ZERO is ignored in Flags.
439 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
440 are inserted every 3rd digit starting from the right.
441 If HEX_RADIX is set in Flags, then the output buffer will be
442 formatted in hexadecimal format.
443 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
444 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
445 then Buffer is padded with '0' characters so the combination of the optional '-'
446 sign character, '0' characters, digit characters for Value, and the Null-terminator
447 add up to Width characters.
449 If Buffer is NULL, then ASSERT().
450 If unsupported bits are set in Flags, then ASSERT().
451 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
452 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
454 @param Buffer Pointer to the output buffer for the produced Null-terminated
456 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
457 @param Value The 64-bit signed value to convert to a string.
458 @param Width The maximum number of ASCII characters to place in Buffer, not including
461 @return The number of ASCII characters in Buffer not including the Null-terminator.
467 IN OUT CHAR8
*Buffer
,