]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/PrintLib.h
Fix track EDKT104: If a module use PCD, MSA of this module should use PcdLib libraryC...
[mirror_edk2.git] / MdePkg / Include / Library / PrintLib.h
1 /** @file
2 Library that provides print services
3
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
9
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.
12
13 Module Name: PrintLib.h
14
15 **/
16
17 #ifndef __PRINT_LIB_H__
18 #define __PRINT_LIB_H__
19
20 ///
21 /// Define the maximum number of characters that are required to
22 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL
23 /// terminator.
24 ///
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"
33 ///
34 #define MAXIMUM_VALUE_CHARACTERS 38
35
36 ///
37 /// Flags bitmask values use in UnicodeValueToString() and
38 /// AcsiiValueToString()
39 ///
40 #define LEFT_JUSTIFY 0x01
41 #define COMMA_TYPE 0x08
42 #define PREFIX_ZERO 0x20
43
44 /**
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
47
48 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
49 and BufferSize.
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 number of Unicode characters in the produced output buffer is returned not including
54 the Null-terminator.
55 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
56
57 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
58 If BufferSize > 1 and FormatString is NULL, then ASSERT().
59 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
60 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
61 ASSERT().
62 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
63 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
64 Null-terminator, then ASSERT().
65
66 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
67 Unicode string.
68 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
69 @param FormatString Null-terminated Unicode format string.
70 @param Marker VA_LIST marker for the variable argument list.
71
72 @return The number of Unicode characters in the produced output buffer not including the
73 Null-terminator.
74
75 **/
76 UINTN
77 EFIAPI
78 UnicodeVSPrint (
79 OUT CHAR16 *StartOfBuffer,
80 IN UINTN BufferSize,
81 IN CONST CHAR16 *FormatString,
82 IN VA_LIST Marker
83 );
84
85 /**
86 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
87 Unicode format string and variable argument list.
88
89 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
90 and BufferSize.
91 The Unicode string is produced by parsing the format string specified by FormatString.
92 Arguments are pulled from the variable argument list based on the contents of the format string.
93 The number of Unicode characters in the produced output buffer is returned not including
94 the Null-terminator.
95 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
96
97 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
98 If BufferSize > 1 and FormatString is NULL, then ASSERT().
99 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
100 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
101 ASSERT().
102 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
103 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
104 Null-terminator, then ASSERT().
105
106 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
107 Unicode string.
108 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
109 @param FormatString Null-terminated Unicode format string.
110
111 @return The number of Unicode characters in the produced output buffer not including the
112 Null-terminator.
113
114 **/
115 UINTN
116 EFIAPI
117 UnicodeSPrint (
118 OUT CHAR16 *StartOfBuffer,
119 IN UINTN BufferSize,
120 IN CONST CHAR16 *FormatString,
121 ...
122 );
123
124 /**
125 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
126 ASCII format string and a VA_LIST argument list
127
128 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
129 and BufferSize.
130 The Unicode string is produced by parsing the format string specified by FormatString.
131 Arguments are pulled from the variable argument list specified by Marker based on the
132 contents of the format string.
133 The number of Unicode characters in the produced output buffer is returned not including
134 the Null-terminator.
135 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
136
137 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
138 If BufferSize > 1 and FormatString is NULL, then ASSERT().
139 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
140 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
141 ASSERT().
142 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
143 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
144 Null-terminator, then ASSERT().
145
146 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
147 Unicode string.
148 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
149 @param FormatString Null-terminated Unicode format string.
150 @param Marker VA_LIST marker for the variable argument list.
151
152 @return The number of Unicode characters in the produced output buffer not including the
153 Null-terminator.
154
155 **/
156 UINTN
157 EFIAPI
158 UnicodeVSPrintAsciiFormat (
159 OUT CHAR16 *StartOfBuffer,
160 IN UINTN BufferSize,
161 IN CONST CHAR8 *FormatString,
162 IN VA_LIST Marker
163 );
164
165 /**
166 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
167 ASCII format string and variable argument list.
168
169 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
170 and BufferSize.
171 The Unicode string is produced by parsing the format string specified by FormatString.
172 Arguments are pulled from the variable argument list based on the contents of the
173 format string.
174 The number of Unicode characters in the produced output buffer is returned not including
175 the Null-terminator.
176 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
177
178 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
179 If BufferSize > 1 and FormatString is NULL, then ASSERT().
180 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
181 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
182 ASSERT().
183 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
184 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
185 Null-terminator, then ASSERT().
186
187 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
188 Unicode string.
189 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
190 @param FormatString Null-terminated Unicode format string.
191
192 @return The number of Unicode characters in the produced output buffer not including the
193 Null-terminator.
194
195 **/
196 UINTN
197 EFIAPI
198 UnicodeSPrintAsciiFormat (
199 OUT CHAR16 *StartOfBuffer,
200 IN UINTN BufferSize,
201 IN CONST CHAR8 *FormatString,
202 ...
203 );
204
205 /**
206 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
207 ASCII format string and a VA_LIST argument list.
208
209 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
210 and BufferSize.
211 The ASCII string is produced by parsing the format string specified by FormatString.
212 Arguments are pulled from the variable argument list specified by Marker based on
213 the contents of the format string.
214 The number of ASCII characters in the produced output buffer is returned not including
215 the Null-terminator.
216 If BufferSize is 0, then no output buffer is produced and 0 is returned.
217
218 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
219 If BufferSize > 0 and FormatString is NULL, then ASSERT().
220 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
221 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
222 ASSERT().
223 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
224 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
225 Null-terminator, then ASSERT().
226
227 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
228 ASCII string.
229 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
230 @param FormatString Null-terminated Unicode format string.
231 @param Marker VA_LIST marker for the variable argument list.
232
233 @return The number of ASCII characters in the produced output buffer not including the
234 Null-terminator.
235
236 **/
237 UINTN
238 EFIAPI
239 AsciiVSPrint (
240 OUT CHAR8 *StartOfBuffer,
241 IN UINTN BufferSize,
242 IN CONST CHAR8 *FormatString,
243 IN VA_LIST Marker
244 );
245
246 /**
247 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
248 ASCII format string and variable argument list.
249
250 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
251 and BufferSize.
252 The ASCII string is produced by parsing the format string specified by FormatString.
253 Arguments are pulled from the variable argument list based on the contents of the
254 format string.
255 The number of ASCII characters in the produced output buffer is returned not including
256 the Null-terminator.
257 If BufferSize is 0, then no output buffer is produced and 0 is returned.
258
259 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
260 If BufferSize > 0 and FormatString is NULL, then ASSERT().
261 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
262 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
263 ASSERT().
264 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
265 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
266 Null-terminator, then ASSERT().
267
268 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
269 ASCII string.
270 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
271 @param FormatString Null-terminated Unicode format string.
272
273 @return The number of ASCII characters in the produced output buffer not including the
274 Null-terminator.
275
276 **/
277 UINTN
278 EFIAPI
279 AsciiSPrint (
280 OUT CHAR8 *StartOfBuffer,
281 IN UINTN BufferSize,
282 IN CONST CHAR8 *FormatString,
283 ...
284 );
285
286 /**
287 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
288 ASCII format string and a VA_LIST argument list.
289
290 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
291 and BufferSize.
292 The ASCII string is produced by parsing the format string specified by FormatString.
293 Arguments are pulled from the variable argument list specified by Marker based on
294 the contents of the format string.
295 The number of ASCII characters in the produced output buffer is returned not including
296 the Null-terminator.
297 If BufferSize is 0, then no output buffer is produced and 0 is returned.
298
299 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
300 If BufferSize > 0 and FormatString is NULL, then ASSERT().
301 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
302 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
303 ASSERT().
304 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
305 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
306 Null-terminator, then ASSERT().
307
308 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
309 ASCII string.
310 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
311 @param FormatString Null-terminated Unicode format string.
312 @param Marker VA_LIST marker for the variable argument list.
313
314 @return The number of ASCII characters in the produced output buffer not including the
315 Null-terminator.
316
317 **/
318 UINTN
319 EFIAPI
320 AsciiVSPrintUnicodeFormat (
321 OUT CHAR8 *StartOfBuffer,
322 IN UINTN BufferSize,
323 IN CONST CHAR16 *FormatString,
324 IN VA_LIST Marker
325 );
326
327 /**
328 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
329 ASCII format string and variable argument list.
330
331 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
332 and BufferSize.
333 The ASCII string is produced by parsing the format string specified by FormatString.
334 Arguments are pulled from the variable argument list based on the contents of the
335 format string.
336 The number of ASCII characters in the produced output buffer is returned not including
337 the Null-terminator.
338 If BufferSize is 0, then no output buffer is produced and 0 is returned.
339
340 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
341 If BufferSize > 0 and FormatString is NULL, then ASSERT().
342 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
343 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
344 ASSERT().
345 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
346 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
347 Null-terminator, then ASSERT().
348
349 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
350 ASCII string.
351 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
352 @param FormatString Null-terminated Unicode format string.
353
354 @return The number of ASCII characters in the produced output buffer not including the
355 Null-terminator.
356
357 **/
358 UINTN
359 EFIAPI
360 AsciiSPrintUnicodeFormat (
361 OUT CHAR8 *StartOfBuffer,
362 IN UINTN BufferSize,
363 IN CONST CHAR16 *FormatString,
364 ...
365 );
366
367 /**
368 Converts a decimal value to a Null-terminated Unicode string.
369
370 Converts the decimal number specified by Value to a Null-terminated Unicode
371 string specified by Buffer containing at most Width characters.
372 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
373 The number of Unicode characters in Buffer is returned not including the Null-terminator.
374 If the conversion contains more than Width characters, then only the first
375 Width characters are returned, and the total number of characters
376 required to perform the conversion is returned.
377 Additional conversion parameters are specified in Flags.
378 The Flags bit LEFT_JUSTIFY is always ignored.
379 All conversions are left justified in Buffer.
380 If Width is 0, PREFIX_ZERO is ignored in Flags.
381 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
382 are inserted every 3rd digit starting from the right.
383 If Value is < 0, then the fist character in Buffer is a '-'.
384 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
385 then Buffer is padded with '0' characters so the combination of the optional '-'
386 sign character, '0' characters, digit characters for Value, and the Null-terminator
387 add up to Width characters.
388
389 If Buffer is NULL, then ASSERT().
390 If unsupported bits are set in Flags, then ASSERT().
391 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
392
393 @param Buffer Pointer to the output buffer for the produced Null-terminated
394 Unicode string.
395 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
396 @param Value The 64-bit signed value to convert to a string.
397 @param Width The maximum number of Unicode characters to place in Buffer, not including
398 the Null-terminator.
399
400 @return The number of Unicode characters in Buffer not including the Null-terminator.
401
402 **/
403 UINTN
404 EFIAPI
405 UnicodeValueToString (
406 IN OUT CHAR16 *Buffer,
407 IN UINTN Flags,
408 IN INT64 Value,
409 IN UINTN Width
410 );
411
412 /**
413 Converts a decimal value to a Null-terminated ASCII string.
414
415 Converts the decimal number specified by Value to a Null-terminated ASCII string
416 specified by Buffer containing at most Width characters.
417 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
418 The number of ASCII characters in Buffer is returned not including the Null-terminator.
419 If the conversion contains more than Width characters, then only the first Width
420 characters are returned, and the total number of characters required to perform
421 the conversion is returned.
422 Additional conversion parameters are specified in Flags.
423 The Flags bit LEFT_JUSTIFY is always ignored.
424 All conversions are left justified in Buffer.
425 If Width is 0, PREFIX_ZERO is ignored in Flags.
426 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
427 are inserted every 3rd digit starting from the right.
428 If Value is < 0, then the fist character in Buffer is a '-'.
429 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then Buffer
430 is padded with '0' characters so the combination of the optional '-'
431 sign character, '0' characters, digit characters for Value, and the
432 Null-terminator add up to Width characters.
433
434 If Buffer is NULL, then ASSERT().
435 If unsupported bits are set in Flags, then ASSERT().
436 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
437
438 @param Buffer Pointer to the output buffer for the produced Null-terminated
439 ASCII string.
440 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
441 @param Value The 64-bit signed value to convert to a string.
442 @param Width The maximum number of ASCII characters to place in Buffer, not including
443 the Null-terminator.
444
445 @return The number of ASCII characters in Buffer not including the Null-terminator.
446
447 **/
448 UINTN
449 EFIAPI
450 AsciiValueToString (
451 IN OUT CHAR8 *Buffer,
452 IN UINTN Flags,
453 IN INT64 Value,
454 IN UINTN Width
455 );
456
457 #endif