1 /*++ 2 3 Copyright (c) 2004 - 2009, Intel Corporation. All rights reserved.<BR> 4 This program and the accompanying materials 5 are licensed and made available under the terms and conditions of the BSD License 6 which accompanies this distribution. The full text of the license may be found at 7 http://opensource.org/licenses/bsd-license.php 8 9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 11 12 13 Module Name: 14 15 EdkIIGluePrintLib.h 16 17 Abstract: 18 19 Public header file Print Lib 20 21 --*/ 22 23 #ifndef __EDKII_GLUE_PRINT_LIB_H__ 24 #define __EDKII_GLUE_PRINT_LIB_H__ 25 26 /// 27 /// Define the maximum number of characters that are required to 28 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL 29 /// terminator. 30 /// 31 /// Maximum Length Decimal String = 28 32 /// "-9,223,372,036,854,775,808" 33 /// Maximum Length Hexidecimal String = 17 34 /// "FFFFFFFFFFFFFFFF" 35 /// Maximum Length GUID = 37 36 /// "00000000-0000-0000-0000-000000000000" 37 /// Maximum Length TIME = 18 38 /// "12/12/2006 12:12" 39 /// 40 #define MAXIMUM_VALUE_CHARACTERS 38 41 42 /// 43 /// Flags bitmask values use in UnicodeValueToString() and 44 /// AsciiValueToString() 45 /// 46 #define LEFT_JUSTIFY 0x01 47 #define COMMA_TYPE 0x08 48 #define PREFIX_ZERO 0x20 49 #define RADIX_HEX 0x80 50 51 /** 52 Produces a Null-terminated Unicode string in an output buffer based on 53 a Null-terminated Unicode format string and a VA_LIST argument list 54 55 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 56 and BufferSize. 57 The Unicode string is produced by parsing the format string specified by FormatString. 58 Arguments are pulled from the variable argument list specified by Marker based on the 59 contents of the format string. 60 The number of Unicode characters in the produced output buffer is returned not including 61 the Null-terminator. 62 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 63 64 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 65 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 66 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 67 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 68 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 69 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 70 ASSERT(). 71 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 72 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the 73 Null-terminator, then ASSERT(). 74 75 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 76 Unicode string. 77 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 78 @param FormatString Null-terminated Unicode format string. 79 @param Marker VA_LIST marker for the variable argument list. 80 81 @return The number of Unicode characters in the produced output buffer not including the 82 Null-terminator. 83 84 **/ 85 UINTN 86 EFIAPI 87 UnicodeVSPrint ( 88 OUT CHAR16 *StartOfBuffer, 89 IN UINTN BufferSize, 90 IN CONST CHAR16 *FormatString, 91 IN VA_LIST Marker 92 ); 93 94 /** 95 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 96 Unicode format string and variable argument list. 97 98 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 99 and BufferSize. 100 The Unicode string is produced by parsing the format string specified by FormatString. 101 Arguments are pulled from the variable argument list based on the contents of the format string. 102 The number of Unicode characters in the produced output buffer is returned not including 103 the Null-terminator. 104 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 105 106 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 107 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 108 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 109 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 110 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 111 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 112 ASSERT(). 113 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 114 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the 115 Null-terminator, then ASSERT(). 116 117 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 118 Unicode string. 119 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 120 @param FormatString Null-terminated Unicode format string. 121 122 @return The number of Unicode characters in the produced output buffer not including the 123 Null-terminator. 124 125 **/ 126 UINTN 127 EFIAPI 128 UnicodeSPrint ( 129 OUT CHAR16 *StartOfBuffer, 130 IN UINTN BufferSize, 131 IN CONST CHAR16 *FormatString, 132 ... 133 ); 134 135 /** 136 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 137 ASCII format string and a VA_LIST argument list 138 139 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 140 and BufferSize. 141 The Unicode string is produced by parsing the format string specified by FormatString. 142 Arguments are pulled from the variable argument list specified by Marker based on the 143 contents of the format string. 144 The number of Unicode characters in the produced output buffer is returned not including 145 the Null-terminator. 146 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 147 148 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 149 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 150 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 151 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 152 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then 153 ASSERT(). 154 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 155 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the 156 Null-terminator, then ASSERT(). 157 158 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 159 Unicode string. 160 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 161 @param FormatString Null-terminated Unicode format string. 162 @param Marker VA_LIST marker for the variable argument list. 163 164 @return The number of Unicode characters in the produced output buffer not including the 165 Null-terminator. 166 167 **/ 168 UINTN 169 EFIAPI 170 UnicodeVSPrintAsciiFormat ( 171 OUT CHAR16 *StartOfBuffer, 172 IN UINTN BufferSize, 173 IN CONST CHAR8 *FormatString, 174 IN VA_LIST Marker 175 ); 176 177 /** 178 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 179 ASCII format string and variable argument list. 180 181 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 182 and BufferSize. 183 The Unicode string is produced by parsing the format string specified by FormatString. 184 Arguments are pulled from the variable argument list based on the contents of the 185 format string. 186 The number of Unicode characters in the produced output buffer is returned not including 187 the Null-terminator. 188 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 189 190 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 191 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 192 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 193 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 194 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then 195 ASSERT(). 196 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 197 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the 198 Null-terminator, then ASSERT(). 199 200 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 201 Unicode string. 202 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 203 @param FormatString Null-terminated Unicode format string. 204 205 @return The number of Unicode characters in the produced output buffer not including the 206 Null-terminator. 207 208 **/ 209 UINTN 210 EFIAPI 211 UnicodeSPrintAsciiFormat ( 212 OUT CHAR16 *StartOfBuffer, 213 IN UINTN BufferSize, 214 IN CONST CHAR8 *FormatString, 215 ... 216 ); 217 218 /** 219 Converts a decimal value to a Null-terminated Unicode string. 220 221 Converts the decimal number specified by Value to a Null-terminated Unicode 222 string specified by Buffer containing at most Width characters. No padding of spaces 223 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. 224 The number of Unicode characters in Buffer is returned not including the Null-terminator. 225 If the conversion contains more than Width characters, then only the first 226 Width characters are returned, and the total number of characters 227 required to perform the conversion is returned. 228 Additional conversion parameters are specified in Flags. 229 230 The Flags bit LEFT_JUSTIFY is always ignored. 231 All conversions are left justified in Buffer. 232 If Width is 0, PREFIX_ZERO is ignored in Flags. 233 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas 234 are inserted every 3rd digit starting from the right. 235 If RADIX_HEX is set in Flags, then the output buffer will be 236 formatted in hexadecimal format. 237 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. 238 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, 239 then Buffer is padded with '0' characters so the combination of the optional '-' 240 sign character, '0' characters, digit characters for Value, and the Null-terminator 241 add up to Width characters. 242 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 243 If Buffer is NULL, then ASSERT(). 244 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 245 If unsupported bits are set in Flags, then ASSERT(). 246 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 247 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() 248 249 @param Buffer Pointer to the output buffer for the produced Null-terminated 250 Unicode string. 251 @param Flags The bitmask of flags that specify left justification, zero pad, and commas. 252 @param Value The 64-bit signed value to convert to a string. 253 @param Width The maximum number of Unicode characters to place in Buffer, not including 254 the Null-terminator. 255 256 @return The number of Unicode characters in Buffer not including the Null-terminator. 257 258 **/ 259 UINTN 260 EFIAPI 261 UnicodeValueToString ( 262 IN OUT CHAR16 *Buffer, 263 IN UINTN Flags, 264 IN INT64 Value, 265 IN UINTN Width 266 ); 267 268 /** 269 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 270 ASCII format string and a VA_LIST argument list. 271 272 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 273 and BufferSize. 274 The ASCII string is produced by parsing the format string specified by FormatString. 275 Arguments are pulled from the variable argument list specified by Marker based on 276 the contents of the format string. 277 The number of ASCII characters in the produced output buffer is returned not including 278 the Null-terminator. 279 If BufferSize is 0, then no output buffer is produced and 0 is returned. 280 281 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 282 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 283 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 284 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then 285 ASSERT(). 286 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 287 contains more than PcdMaximumAsciiStringLength ASCII characters not including the 288 Null-terminator, then ASSERT(). 289 290 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 291 ASCII string. 292 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 293 @param FormatString Null-terminated Unicode format string. 294 @param Marker VA_LIST marker for the variable argument list. 295 296 @return The number of ASCII characters in the produced output buffer not including the 297 Null-terminator. 298 299 **/ 300 UINTN 301 EFIAPI 302 AsciiVSPrint ( 303 OUT CHAR8 *StartOfBuffer, 304 IN UINTN BufferSize, 305 IN CONST CHAR8 *FormatString, 306 IN VA_LIST Marker 307 ); 308 309 /** 310 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 311 ASCII format string and variable argument list. 312 313 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 314 and BufferSize. 315 The ASCII string is produced by parsing the format string specified by FormatString. 316 Arguments are pulled from the variable argument list based on the contents of the 317 format string. 318 The number of ASCII characters in the produced output buffer is returned not including 319 the Null-terminator. 320 If BufferSize is 0, then no output buffer is produced and 0 is returned. 321 322 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 323 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 324 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 325 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then 326 ASSERT(). 327 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 328 contains more than PcdMaximumAsciiStringLength ASCII characters not including the 329 Null-terminator, then ASSERT(). 330 331 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 332 ASCII string. 333 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 334 @param FormatString Null-terminated Unicode format string. 335 336 @return The number of ASCII characters in the produced output buffer not including the 337 Null-terminator. 338 339 **/ 340 UINTN 341 EFIAPI 342 AsciiSPrint ( 343 OUT CHAR8 *StartOfBuffer, 344 IN UINTN BufferSize, 345 IN CONST CHAR8 *FormatString, 346 ... 347 ); 348 349 /** 350 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 351 ASCII format string and a VA_LIST argument list. 352 353 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 354 and BufferSize. 355 The ASCII string is produced by parsing the format string specified by FormatString. 356 Arguments are pulled from the variable argument list specified by Marker based on 357 the contents of the format string. 358 The number of ASCII characters in the produced output buffer is returned not including 359 the Null-terminator. 360 If BufferSize is 0, then no output buffer is produced and 0 is returned. 361 362 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 363 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 364 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 365 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 366 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 367 ASSERT(). 368 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 369 contains more than PcdMaximumAsciiStringLength ASCII characters not including the 370 Null-terminator, then ASSERT(). 371 372 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 373 ASCII string. 374 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 375 @param FormatString Null-terminated Unicode format string. 376 @param Marker VA_LIST marker for the variable argument list. 377 378 @return The number of ASCII characters in the produced output buffer not including the 379 Null-terminator. 380 381 **/ 382 UINTN 383 EFIAPI 384 AsciiVSPrintUnicodeFormat ( 385 OUT CHAR8 *StartOfBuffer, 386 IN UINTN BufferSize, 387 IN CONST CHAR16 *FormatString, 388 IN VA_LIST Marker 389 ); 390 391 /** 392 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 393 ASCII format string and variable argument list. 394 395 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 396 and BufferSize. 397 The ASCII string is produced by parsing the format string specified by FormatString. 398 Arguments are pulled from the variable argument list based on the contents of the 399 format string. 400 The number of ASCII characters in the produced output buffer is returned not including 401 the Null-terminator. 402 If BufferSize is 0, then no output buffer is produced and 0 is returned. 403 404 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 405 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 406 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 407 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 408 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 409 ASSERT(). 410 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 411 contains more than PcdMaximumAsciiStringLength ASCII characters not including the 412 Null-terminator, then ASSERT(). 413 414 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 415 ASCII string. 416 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 417 @param FormatString Null-terminated Unicode format string. 418 419 @return The number of ASCII characters in the produced output buffer not including the 420 Null-terminator. 421 422 **/ 423 UINTN 424 EFIAPI 425 AsciiSPrintUnicodeFormat ( 426 OUT CHAR8 *StartOfBuffer, 427 IN UINTN BufferSize, 428 IN CONST CHAR16 *FormatString, 429 ... 430 ); 431 432 /** 433 Converts a decimal value to a Null-terminated ASCII string. 434 435 Converts the decimal number specified by Value to a Null-terminated ASCII string 436 specified by Buffer containing at most Width characters. No padding of spaces 437 is ever performed. 438 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. 439 The number of ASCII characters in Buffer is returned not including the Null-terminator. 440 If the conversion contains more than Width characters, then only the first Width 441 characters are returned, and the total number of characters required to perform 442 the conversion is returned. 443 Additional conversion parameters are specified in Flags. 444 The Flags bit LEFT_JUSTIFY is always ignored. 445 All conversions are left justified in Buffer. 446 If Width is 0, PREFIX_ZERO is ignored in Flags. 447 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas 448 are inserted every 3rd digit starting from the right. 449 If RADIX_HEX is set in Flags, then the output buffer will be 450 formatted in hexadecimal format. 451 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. 452 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, 453 then Buffer is padded with '0' characters so the combination of the optional '-' 454 sign character, '0' characters, digit characters for Value, and the Null-terminator 455 add up to Width characters. 456 457 If Buffer is NULL, then ASSERT(). 458 If unsupported bits are set in Flags, then ASSERT(). 459 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 460 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() 461 462 @param Buffer Pointer to the output buffer for the produced Null-terminated 463 ASCII string. 464 @param Flags The bitmask of flags that specify left justification, zero pad, and commas. 465 @param Value The 64-bit signed value to convert to a string. 466 @param Width The maximum number of ASCII characters to place in Buffer, not including 467 the Null-terminator. 468 469 @return The number of ASCII characters in Buffer not including the Null-terminator. 470 471 **/ 472 UINTN 473 EFIAPI 474 AsciiValueToString ( 475 IN OUT CHAR8 *Buffer, 476 IN UINTN Flags, 477 IN INT64 Value, 478 IN UINTN Width 479 ); 480 481 #endif 482