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