MdePkg/Include/Library/PrintLib.h

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