MdePkg/Include/Library/PrintLib.h

   1 /** @file
   2   Library header file that defines print services
   3
   4   Copyright (c) 2006 - 2008, 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   @param  ...             The variable argument list.
 114
 115   @return The number of Unicode characters in the produced output buffer not including the
 116           Null-terminator.
 117
 118 **/
 119 UINTN
 120 EFIAPI
 121 UnicodeSPrint (
 122   OUT CHAR16        *StartOfBuffer,
 123   IN  UINTN         BufferSize,
 124   IN  CONST CHAR16  *FormatString,
 125   ...
 126   );
 127
 128 /**
 129   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 130   ASCII format string and a VA_LIST argument list
 131
 132   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 133   and BufferSize.
 134   The Unicode string is produced by parsing the format string specified by FormatString.
 135   Arguments are pulled from the variable argument list specified by Marker based on the
 136   contents of the format string.
 137   The number of Unicode characters in the produced output buffer is returned not including
 138   the Null-terminator.
 139   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 140
 141   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 142   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 143   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 144   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 145   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 146   ASSERT().
 147   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 148   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 149   Null-terminator, then ASSERT().
 150
 151   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 152                           Unicode string.
 153   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 154   @param  FormatString    Null-terminated ASCII format string.
 155   @param  Marker          VA_LIST marker for the variable argument list.
 156
 157   @return The number of Unicode characters in the produced output buffer not including the
 158           Null-terminator.
 159
 160 **/
 161 UINTN
 162 EFIAPI
 163 UnicodeVSPrintAsciiFormat (
 164   OUT CHAR16       *StartOfBuffer,
 165   IN  UINTN        BufferSize,
 166   IN  CONST CHAR8  *FormatString,
 167   IN  VA_LIST      Marker
 168   );
 169
 170 /**
 171   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 172   ASCII format string and  variable argument list.
 173
 174   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 175   and BufferSize.
 176   The Unicode string is produced by parsing the format string specified by FormatString.
 177   Arguments are pulled from the variable argument list based on the contents of the
 178   format string.
 179   The number of Unicode characters in the produced output buffer is returned not including
 180   the Null-terminator.
 181   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 182
 183   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 184   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 185   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 186   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 187   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 188   ASSERT().
 189   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 190   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 191   Null-terminator, then ASSERT().
 192
 193   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 194                           Unicode string.
 195   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 196   @param  FormatString    Null-terminated ASCII format string.
 197   @param  ...             The variable argument list.
 198
 199   @return The number of Unicode characters in the produced output buffer not including the
 200           Null-terminator.
 201
 202 **/
 203 UINTN
 204 EFIAPI
 205 UnicodeSPrintAsciiFormat (
 206   OUT CHAR16       *StartOfBuffer,
 207   IN  UINTN        BufferSize,
 208   IN  CONST CHAR8  *FormatString,
 209   ...
 210   );
 211
 212 /**
 213   Converts a decimal value to a Null-terminated Unicode string.
 214
 215   Converts the decimal number specified by Value to a Null-terminated Unicode
 216   string specified by Buffer containing at most Width characters. No padding of spaces
 217   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 218   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 219   If the conversion contains more than Width characters, then only the first
 220   Width characters are returned, and the total number of characters
 221   required to perform the conversion is returned.
 222   Additional conversion parameters are specified in Flags.
 223
 224   The Flags bit LEFT_JUSTIFY is always ignored.
 225   All conversions are left justified in Buffer.
 226   If Width is 0, PREFIX_ZERO is ignored in Flags.
 227   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 228   are inserted every 3rd digit starting from the right.
 229   If HEX_RADIX is set in Flags, then the output buffer will be
 230   formatted in hexadecimal format.
 231   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 232   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 233   then Buffer is padded with '0' characters so the combination of the optional '-'
 234   sign character, '0' characters, digit characters for Value, and the Null-terminator
 235   add up to Width characters.
 236   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 237   If Buffer is NULL, then ASSERT().
 238   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 239   If unsupported bits are set in Flags, then ASSERT().
 240   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 241   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 242
 243   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 244                   Unicode string.
 245   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 246   @param  Value   The 64-bit signed value to convert to a string.
 247   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 248                   the Null-terminator.
 249
 250   @return The number of Unicode characters in Buffer not including the Null-terminator.
 251
 252 **/
 253 UINTN
 254 EFIAPI
 255 UnicodeValueToString (
 256   IN OUT CHAR16  *Buffer,
 257   IN UINTN       Flags,
 258   IN INT64       Value,
 259   IN UINTN       Width
 260   );
 261
 262 /**
 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.
 265
 266   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 267   and BufferSize.
 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 number of ASCII characters in the produced output buffer is returned not including
 272   the Null-terminator.
 273   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 274
 275   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 276   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 277   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 278   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 279   ASSERT().
 280   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 281   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 282   Null-terminator, then ASSERT().
 283
 284   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 285                           ASCII string.
 286   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 287   @param  FormatString    Null-terminated ASCII format string.
 288   @param  Marker          VA_LIST marker for the variable argument list.
 289
 290   @return The number of ASCII characters in the produced output buffer not including the
 291           Null-terminator.
 292
 293 **/
 294 UINTN
 295 EFIAPI
 296 AsciiVSPrint (
 297   OUT CHAR8         *StartOfBuffer,
 298   IN  UINTN         BufferSize,
 299   IN  CONST CHAR8   *FormatString,
 300   IN  VA_LIST       Marker
 301   );
 302
 303 /**
 304   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 305   ASCII format string and  variable argument list.
 306
 307   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 308   and BufferSize.
 309   The ASCII string is produced by parsing the format string specified by FormatString.
 310   Arguments are pulled from the variable argument list based on the contents of the
 311   format string.
 312   The number of ASCII characters in the produced output buffer is returned not including
 313   the Null-terminator.
 314   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 315
 316   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 317   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 318   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 319   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 320   ASSERT().
 321   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 322   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 323   Null-terminator, then ASSERT().
 324
 325   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 326                           ASCII string.
 327   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 328   @param  FormatString    Null-terminated ASCII format string.
 329   @param  ...             The variable argument list.
 330
 331   @return The number of ASCII characters in the produced output buffer not including the
 332           Null-terminator.
 333
 334 **/
 335 UINTN
 336 EFIAPI
 337 AsciiSPrint (
 338   OUT CHAR8        *StartOfBuffer,
 339   IN  UINTN        BufferSize,
 340   IN  CONST CHAR8  *FormatString,
 341   ...
 342   );
 343
 344 /**
 345   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 346   Unicode format string and a VA_LIST argument list.
 347
 348   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 349   and BufferSize.
 350   The ASCII string is produced by parsing the format string specified by FormatString.
 351   Arguments are pulled from the variable argument list specified by Marker based on
 352   the contents of the format string.
 353   The number of ASCII characters in the produced output buffer is returned not including
 354   the Null-terminator.
 355   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 356
 357   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 358   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 359   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 360   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 361   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 362   ASSERT().
 363   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 364   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 365   Null-terminator, then ASSERT().
 366
 367   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 368                           ASCII string.
 369   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 370   @param  FormatString    Null-terminated Unicode format string.
 371   @param  Marker          VA_LIST marker for the variable argument list.
 372
 373   @return The number of ASCII characters in the produced output buffer not including the
 374           Null-terminator.
 375
 376 **/
 377 UINTN
 378 EFIAPI
 379 AsciiVSPrintUnicodeFormat (
 380   OUT CHAR8         *StartOfBuffer,
 381   IN  UINTN         BufferSize,
 382   IN  CONST CHAR16  *FormatString,
 383   IN  VA_LIST       Marker
 384   );
 385
 386 /**
 387   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 388   Unicode format string and  variable argument list.
 389
 390   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 391   and BufferSize.
 392   The ASCII string is produced by parsing the format string specified by FormatString.
 393   Arguments are pulled from the variable argument list based on the contents of the
 394   format string.
 395   The number of ASCII characters in the produced output buffer is returned not including
 396   the Null-terminator.
 397   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 398
 399   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 400   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 401   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 402   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 403   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 404   ASSERT().
 405   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 406   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 407   Null-terminator, then ASSERT().
 408
 409   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 410                           ASCII string.
 411   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 412   @param  FormatString    Null-terminated Unicode format string.
 413   @param  ...             The variable argument list.
 414
 415   @return The number of ASCII characters in the produced output buffer not including the
 416           Null-terminator.
 417
 418 **/
 419 UINTN
 420 EFIAPI
 421 AsciiSPrintUnicodeFormat (
 422   OUT CHAR8         *StartOfBuffer,
 423   IN  UINTN         BufferSize,
 424   IN  CONST CHAR16  *FormatString,
 425   ...
 426   );
 427
 428 /**
 429   Converts a decimal value to a Null-terminated ASCII string.
 430
 431   Converts the decimal number specified by Value to a Null-terminated ASCII string
 432   specified by Buffer containing at most Width characters. No padding of spaces
 433   is ever performed.
 434   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 435   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 436   If the conversion contains more than Width characters, then only the first Width
 437   characters are returned, and the total number of characters required to perform
 438   the conversion is returned.
 439   Additional conversion parameters are specified in Flags.
 440   The Flags bit LEFT_JUSTIFY is always ignored.
 441   All conversions are left justified in Buffer.
 442   If Width is 0, PREFIX_ZERO is ignored in Flags.
 443   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 444   are inserted every 3rd digit starting from the right.
 445   If HEX_RADIX is set in Flags, then the output buffer will be
 446   formatted in hexadecimal format.
 447   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 448   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 449   then Buffer is padded with '0' characters so the combination of the optional '-'
 450   sign character, '0' characters, digit characters for Value, and the Null-terminator
 451   add up to Width characters.
 452
 453   If Buffer is NULL, then ASSERT().
 454   If unsupported bits are set in Flags, then ASSERT().
 455   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 456   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 457
 458   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 459                   ASCII string.
 460   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 461   @param  Value   The 64-bit signed value to convert to a string.
 462   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 463                   the Null-terminator.
 464
 465   @return The number of ASCII characters in Buffer not including the Null-terminator.
 466
 467 **/
 468 UINTN
 469 EFIAPI
 470 AsciiValueToString (
 471   IN OUT CHAR8  *Buffer,
 472   IN UINTN      Flags,
 473   IN INT64      Value,
 474   IN UINTN      Width
 475   );
 476
 477 #endif