]>
git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/PrintLib.h
2 Library that provides print services
4 Copyright (c) 2006, 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
45 Produces a Null-terminated Unicode string in an output buffer based on
46 a Null-terminated Unicode format string and a VA_LIST argument list
48 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
50 The Unicode string is produced by parsing the format string specified by FormatString.
51 Arguments are pulled from the variable argument list specified by Marker based on the
52 contents of the format string.
53 The length of the produced output buffer is returned.
54 If BufferSize is 0, then no output buffer is produced and 0 is returned.
56 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
57 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
58 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
59 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
60 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
61 contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
63 @param StartOfBuffer APointer to the output buffer for the produced Null-terminated
65 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
66 @param FormatString Null-terminated Unicode format string.
67 @param Marker VA_LIST marker for the variable argument list.
69 @return return Length of the produced output buffer.
75 OUT CHAR16
*StartOfBuffer
,
77 IN CONST CHAR16
*FormatString
,
82 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
83 Unicode format string and variable argument list.
85 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
87 The Unicode string is produced by parsing the format string specified by FormatString.
88 Arguments are pulled from the variable argument list based on the contents of the format string.
89 The length of the produced output buffer is returned.
90 If BufferSize is 0, then no output buffer is produced and 0 is returned.
92 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
93 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
94 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
95 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
96 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
97 contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
99 @param StartOfBuffer APointer to the output buffer for the produced Null-terminated
101 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
102 @param FormatString Null-terminated Unicode format string.
104 @return Length of the produced output buffer.
110 OUT CHAR16
*StartOfBuffer
,
112 IN CONST CHAR16
*FormatString
,
117 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
118 ASCII format string and a VA_LIST argument list
120 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
122 The Unicode string is produced by parsing the format string specified by FormatString.
123 Arguments are pulled from the variable argument list specified by Marker based on the
124 contents of the format string.
125 The length of the produced output buffer is returned.
126 If BufferSize is 0, then no output buffer is produced and 0 is returned.
128 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
129 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
130 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
131 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
132 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
133 contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
135 @param StartOfBuffer APointer to the output buffer for the produced Null-terminated
137 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
138 @param FormatString Null-terminated Unicode format string.
139 @param Marker VA_LIST marker for the variable argument list.
141 @return Length of the produced output buffer.
146 UnicodeVSPrintAsciiFormat (
147 OUT CHAR16
*StartOfBuffer
,
149 IN CONST CHAR8
*FormatString
,
154 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
155 ASCII format string and variable argument list.
157 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
159 The Unicode string is produced by parsing the format string specified by FormatString.
160 Arguments are pulled from the variable argument list based on the contents of the
162 The length of the produced output buffer is returned.
163 If BufferSize is 0, then no output buffer is produced and 0 is returned.
165 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
166 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
167 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
168 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
169 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
170 contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
172 @param StartOfBuffer APointer to the output buffer for the produced Null-terminated
174 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
175 @param FormatString Null-terminated Unicode format string.
177 @return Length of the produced output buffer.
182 UnicodeSPrintAsciiFormat (
183 OUT CHAR16
*StartOfBuffer
,
185 IN CONST CHAR8
*FormatString
,
190 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
191 ASCII format string and a VA_LIST argument list.
193 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
195 The ASCII string is produced by parsing the format string specified by FormatString.
196 Arguments are pulled from the variable argument list specified by Marker based on
197 the contents of the format string.
198 The length of the produced output buffer is returned.
199 If BufferSize is 0, then no output buffer is produced and 0 is returned.
201 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
202 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
203 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
204 PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
205 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
206 contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
208 @param StartOfBuffer APointer to the output buffer for the produced Null-terminated
210 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
211 @param FormatString Null-terminated Unicode format string.
212 @param Marker VA_LIST marker for the variable argument list.
214 @return Length of the produced output buffer.
220 OUT CHAR8
*StartOfBuffer
,
222 IN CONST CHAR8
*FormatString
,
227 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
228 ASCII format string and variable argument list.
230 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
232 The ASCII string is produced by parsing the format string specified by FormatString.
233 Arguments are pulled from the variable argument list based on the contents of the
235 The length of the produced output buffer is returned.
236 If BufferSize is 0, then no output buffer is produced and 0 is returned.
238 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
239 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
240 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
241 PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
242 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
243 contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
245 @param StartOfBuffer APointer to the output buffer for the produced Null-terminated
247 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
248 @param FormatString Null-terminated Unicode format string.
250 @return Length of the produced output buffer.
256 OUT CHAR8
*StartOfBuffer
,
258 IN CONST CHAR8
*FormatString
,
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 length of the produced output buffer is returned.
272 If BufferSize is 0, then no output buffer is produced and 0 is returned.
274 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
275 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
276 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
277 PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
278 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
279 contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
281 @param StartOfBuffer APointer to the output buffer for the produced Null-terminated
283 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
284 @param FormatString Null-terminated Unicode format string.
285 @param Marker VA_LIST marker for the variable argument list.
287 @return Length of the produced output buffer.
292 AsciiVSPrintUnicodeFormat (
293 OUT CHAR8
*StartOfBuffer
,
295 IN CONST CHAR16
*FormatString
,
300 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
301 ASCII format string and variable argument list.
303 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
305 The ASCII string is produced by parsing the format string specified by FormatString.
306 Arguments are pulled from the variable argument list based on the contents of the
308 The length of the produced output buffer is returned.
309 If BufferSize is 0, then no output buffer is produced and 0 is returned.
311 If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
312 If BufferSize is not 0 and FormatString is NULL, then ASSERT().
313 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
314 PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
315 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
316 contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
318 @param StartOfBuffer APointer 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 Length of the produced output buffer.
328 AsciiSPrintUnicodeFormat (
329 OUT CHAR8
*StartOfBuffer
,
331 IN CONST CHAR16
*FormatString
,
336 Converts a decimal value to a Null-terminated Unicode string.
338 Converts the decimal number specified by Value to a Null-terminated Unicode
339 string specified by Buffer containing at most Width characters.
340 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
341 The total number of characters placed in Buffer is returned.
342 If the conversion contains more than Width characters, then only the first
343 Width characters are returned, and the total number of characters
344 required to perform the conversion is returned.
345 Additional conversion parameters are specified in Flags.
346 The Flags bit LEFT_JUSTIFY is always ignored.
347 All conversions are left justified in Buffer.
348 If Width is 0, PREFIX_ZERO is ignored in Flags.
349 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
350 are inserted every 3rd digit starting from the right.
351 If Value is < 0, then the fist character in Buffer is a '-'.
352 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
353 then Buffer is padded with '0' characters so the combination of the optional '-'
354 sign character, '0' characters, digit characters for Value, and the Null-terminator
355 add up to Width characters.
357 If Buffer is NULL, then ASSERT().
358 If unsupported bits are set in Flags, then ASSERT().
359 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
361 @param Buffer Pointer to the output buffer for the produced Null-terminated
363 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
364 @param Value The 64-bit signed value to convert to a string.
365 @param Width The maximum number of Unicode characters to place in Buffer.
367 @return Total number of characters required to perform the conversion.
372 UnicodeValueToString (
373 IN OUT CHAR16
*Buffer
,
380 Converts a decimal value to a Null-terminated ASCII string.
382 Converts the decimal number specified by Value to a Null-terminated ASCII string
383 specified by Buffer containing at most Width characters.
384 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
385 The total number of characters placed in Buffer is returned.
386 If the conversion contains more than Width characters, then only the first Width
387 characters are returned, and the total number of characters required to perform
388 the conversion is returned.
389 Additional conversion parameters are specified in Flags.
390 The Flags bit LEFT_JUSTIFY is always ignored.
391 All conversions are left justified in Buffer.
392 If Width is 0, PREFIX_ZERO is ignored in Flags.
393 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
394 are inserted every 3rd digit starting from the right.
395 If Value is < 0, then the fist character in Buffer is a '-'.
396 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then Buffer
397 is padded with '0' characters so the combination of the optional '-'
398 sign character, '0' characters, digit characters for Value, and the
399 Null-terminator add up to Width characters.
401 If Buffer is NULL, then ASSERT().
402 If unsupported bits are set in Flags, then ASSERT().
403 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
405 @param Buffer Pointer to the output buffer for the produced Null-terminated
407 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
408 @param Value The 64-bit signed value to convert to a string.
409 @param Width The maximum number of ASCII characters to place in Buffer.
411 @return Total number of characters required to perform the conversion.
417 IN OUT CHAR8
*Buffer
,