]>
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 /// AcsiiValueToString()
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 FormatString is NULL, 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 FormatString is NULL, then ASSERT().
100 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
101 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
103 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
104 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
105 Null-terminator, then ASSERT().
107 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
109 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
110 @param FormatString Null-terminated Unicode format string.
112 @return The number of Unicode characters in the produced output buffer not including the
119 OUT CHAR16
*StartOfBuffer
,
121 IN CONST CHAR16
*FormatString
,
126 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
127 ASCII format string and a VA_LIST argument list
129 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
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
136 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
138 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
139 If BufferSize > 1 and FormatString is NULL, then ASSERT().
140 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
141 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
143 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
144 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
145 Null-terminator, then ASSERT().
147 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
149 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
150 @param FormatString Null-terminated Unicode format string.
151 @param Marker VA_LIST marker for the variable argument list.
153 @return The number of Unicode characters in the produced output buffer not including the
159 UnicodeVSPrintAsciiFormat (
160 OUT CHAR16
*StartOfBuffer
,
162 IN CONST CHAR8
*FormatString
,
167 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
168 ASCII format string and variable argument list.
170 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
172 The Unicode string is produced by parsing the format string specified by FormatString.
173 Arguments are pulled from the variable argument list based on the contents of the
175 The number of Unicode characters in the produced output buffer is returned not including
177 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
179 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
180 If BufferSize > 1 and FormatString is NULL, then ASSERT().
181 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
182 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
184 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
185 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
186 Null-terminator, then ASSERT().
188 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
190 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
191 @param FormatString Null-terminated Unicode format string.
193 @return The number of Unicode characters in the produced output buffer not including the
199 UnicodeSPrintAsciiFormat (
200 OUT CHAR16
*StartOfBuffer
,
202 IN CONST CHAR8
*FormatString
,
207 Converts a decimal value to a Null-terminated Unicode string.
209 Converts the decimal number specified by Value to a Null-terminated Unicode
210 string specified by Buffer containing at most Width characters. No padding of spaces
211 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
212 The number of Unicode characters in Buffer is returned not including the Null-terminator.
213 If the conversion contains more than Width characters, then only the first
214 Width characters are returned, and the total number of characters
215 required to perform the conversion is returned.
216 Additional conversion parameters are specified in Flags.
218 The Flags bit LEFT_JUSTIFY is always ignored.
219 All conversions are left justified in Buffer.
220 If Width is 0, PREFIX_ZERO is ignored in Flags.
221 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
222 are inserted every 3rd digit starting from the right.
223 If HEX_RADIX is set in Flags, then the output buffer will be
224 formatted in hexadecimal format.
225 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
226 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
227 then Buffer is padded with '0' characters so the combination of the optional '-'
228 sign character, '0' characters, digit characters for Value, and the Null-terminator
229 add up to Width characters.
230 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
231 If Buffer is NULL, then ASSERT().
232 If unsupported bits are set in Flags, then ASSERT().
233 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
234 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
236 @param Buffer Pointer to the output buffer for the produced Null-terminated
238 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
239 @param Value The 64-bit signed value to convert to a string.
240 @param Width The maximum number of Unicode characters to place in Buffer, not including
243 @return The number of Unicode characters in Buffer not including the Null-terminator.
248 UnicodeValueToString (
249 IN OUT CHAR16
*Buffer
,
256 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
257 ASCII format string and a VA_LIST argument list.
259 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
261 The ASCII string is produced by parsing the format string specified by FormatString.
262 Arguments are pulled from the variable argument list specified by Marker based on
263 the contents of the format string.
264 The number of ASCII characters in the produced output buffer is returned not including
266 If BufferSize is 0, then no output buffer is produced and 0 is returned.
268 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
269 If BufferSize > 0 and FormatString is NULL, then ASSERT().
270 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
271 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
273 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
274 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
275 Null-terminator, then ASSERT().
277 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
279 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
280 @param FormatString Null-terminated Unicode format string.
281 @param Marker VA_LIST marker for the variable argument list.
283 @return The number of ASCII characters in the produced output buffer not including the
290 OUT CHAR8
*StartOfBuffer
,
292 IN CONST CHAR8
*FormatString
,
297 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
298 ASCII format string and variable argument list.
300 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
302 The ASCII string is produced by parsing the format string specified by FormatString.
303 Arguments are pulled from the variable argument list based on the contents of the
305 The number of ASCII characters in the produced output buffer is returned not including
307 If BufferSize is 0, then no output buffer is produced and 0 is returned.
309 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
310 If BufferSize > 0 and FormatString is NULL, then ASSERT().
311 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
312 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
314 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
315 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
316 Null-terminator, then ASSERT().
318 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
320 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
321 @param FormatString Null-terminated Unicode format string.
323 @return The number of ASCII characters in the produced output buffer not including the
330 OUT CHAR8
*StartOfBuffer
,
332 IN CONST CHAR8
*FormatString
,
337 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
338 ASCII format string and a VA_LIST argument list.
340 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
342 The ASCII string is produced by parsing the format string specified by FormatString.
343 Arguments are pulled from the variable argument list specified by Marker based on
344 the contents of the format string.
345 The number of ASCII characters in the produced output buffer is returned not including
347 If BufferSize is 0, then no output buffer is produced and 0 is returned.
349 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
350 If BufferSize > 0 and FormatString is NULL, then ASSERT().
351 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
352 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
354 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
355 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
356 Null-terminator, then ASSERT().
358 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
360 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
361 @param FormatString Null-terminated Unicode format string.
362 @param Marker VA_LIST marker for the variable argument list.
364 @return The number of ASCII characters in the produced output buffer not including the
370 AsciiVSPrintUnicodeFormat (
371 OUT CHAR8
*StartOfBuffer
,
373 IN CONST CHAR16
*FormatString
,
378 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
379 ASCII format string and variable argument list.
381 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
383 The ASCII string is produced by parsing the format string specified by FormatString.
384 Arguments are pulled from the variable argument list based on the contents of the
386 The number of ASCII characters in the produced output buffer is returned not including
388 If BufferSize is 0, then no output buffer is produced and 0 is returned.
390 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
391 If BufferSize > 0 and FormatString is NULL, then ASSERT().
392 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
393 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
395 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
396 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
397 Null-terminator, then ASSERT().
399 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
401 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
402 @param FormatString Null-terminated Unicode format string.
404 @return The number of ASCII characters in the produced output buffer not including the
410 AsciiSPrintUnicodeFormat (
411 OUT CHAR8
*StartOfBuffer
,
413 IN CONST CHAR16
*FormatString
,
418 Converts a decimal value to a Null-terminated ASCII string.
420 Converts the decimal number specified by Value to a Null-terminated ASCII string
421 specified by Buffer containing at most Width characters. No padding of spaces
423 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
424 The number of ASCII characters in Buffer is returned not including the Null-terminator.
425 If the conversion contains more than Width characters, then only the first Width
426 characters are returned, and the total number of characters required to perform
427 the conversion is returned.
428 Additional conversion parameters are specified in Flags.
429 The Flags bit LEFT_JUSTIFY is always ignored.
430 All conversions are left justified in Buffer.
431 If Width is 0, PREFIX_ZERO is ignored in Flags.
432 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
433 are inserted every 3rd digit starting from the right.
434 If HEX_RADIX is set in Flags, then the output buffer will be
435 formatted in hexadecimal format.
436 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
437 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
438 then Buffer is padded with '0' characters so the combination of the optional '-'
439 sign character, '0' characters, digit characters for Value, and the Null-terminator
440 add up to Width characters.
442 If Buffer is NULL, then ASSERT().
443 If unsupported bits are set in Flags, then ASSERT().
444 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
445 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
447 @param Buffer Pointer to the output buffer for the produced Null-terminated
449 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
450 @param Value The 64-bit signed value to convert to a string.
451 @param Width The maximum number of ASCII characters to place in Buffer, not including
454 @return The number of ASCII characters in Buffer not including the Null-terminator.
460 IN OUT CHAR8
*Buffer
,