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