OldMdePkg/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   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 /// AsciiValueToString()
  39 ///
  40 #define LEFT_JUSTIFY      0x01
  41 #define COMMA_TYPE        0x08
  42 #define PREFIX_ZERO       0x20
  43 #define RADIX_HEX         0x80
  44
  45 /**
  46   Produces a Null-terminated Unicode string in an output buffer based on
  47   a Null-terminated Unicode format string and a VA_LIST argument list
  48
  49   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  50   and BufferSize.
  51   The Unicode string is produced by parsing the format string specified by FormatString.
  52   Arguments are pulled from the variable argument list specified by Marker based on the
  53   contents of the format string.
  54   The number of Unicode characters in the produced output buffer is returned not including
  55   the Null-terminator.
  56   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  57
  58   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  59   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  60   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  61   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
  62   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  63   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
  64   ASSERT().
  65   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  66   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  67   Null-terminator, then ASSERT().
  68
  69   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  70                           Unicode string.
  71   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  72   @param  FormatString    Null-terminated Unicode format string.
  73   @param  Marker          VA_LIST marker for the variable argument list.
  74
  75   @return The number of Unicode characters in the produced output buffer not including the
  76           Null-terminator.
  77
  78 **/
  79 UINTN
  80 EFIAPI
  81 UnicodeVSPrint (
  82   OUT CHAR16        *StartOfBuffer,
  83   IN  UINTN         BufferSize,
  84   IN  CONST CHAR16  *FormatString,
  85   IN  VA_LIST       Marker
  86   );
  87
  88 /**
  89   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
  90   Unicode format string and variable argument list.
  91
  92   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  93   and BufferSize.
  94   The Unicode string is produced by parsing the format string specified by FormatString.
  95   Arguments are pulled from the variable argument list based on the contents of the format string.
  96   The number of Unicode characters in the produced output buffer is returned not including
  97   the Null-terminator.
  98   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  99
 100   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 101   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 102   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 103   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 104   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 105   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 106   ASSERT().
 107   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 108   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 109   Null-terminator, then ASSERT().
 110
 111   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 112                           Unicode string.
 113   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 114   @param  FormatString    Null-terminated Unicode format string.
 115
 116   @return The number of Unicode characters in the produced output buffer not including the
 117           Null-terminator.
 118
 119 **/
 120 UINTN
 121 EFIAPI
 122 UnicodeSPrint (
 123   OUT CHAR16        *StartOfBuffer,
 124   IN  UINTN         BufferSize,
 125   IN  CONST CHAR16  *FormatString,
 126   ...
 127   );
 128
 129 /**
 130   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 131   ASCII format string and a VA_LIST argument list
 132
 133   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 134   and BufferSize.
 135   The Unicode string is produced by parsing the format string specified by FormatString.
 136   Arguments are pulled from the variable argument list specified by Marker based on the
 137   contents of the format string.
 138   The number of Unicode characters in the produced output buffer is returned not including
 139   the Null-terminator.
 140   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 141
 142   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 143   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 144   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 145   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 146   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 147   ASSERT().
 148   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 149   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 150   Null-terminator, then ASSERT().
 151
 152   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 153                           Unicode string.
 154   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 155   @param  FormatString    Null-terminated Unicode format string.
 156   @param  Marker          VA_LIST marker for the variable argument list.
 157
 158   @return The number of Unicode characters in the produced output buffer not including the
 159           Null-terminator.
 160
 161 **/
 162 UINTN
 163 EFIAPI
 164 UnicodeVSPrintAsciiFormat (
 165   OUT CHAR16       *StartOfBuffer,
 166   IN  UINTN        BufferSize,
 167   IN  CONST CHAR8  *FormatString,
 168   IN  VA_LIST      Marker
 169   );
 170
 171 /**
 172   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 173   ASCII format string and  variable argument list.
 174
 175   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 176   and BufferSize.
 177   The Unicode string is produced by parsing the format string specified by FormatString.
 178   Arguments are pulled from the variable argument list based on the contents of the
 179   format string.
 180   The number of Unicode characters in the produced output buffer is returned not including
 181   the Null-terminator.
 182   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 183
 184   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 185   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 186   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 187   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 188   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 189   ASSERT().
 190   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 191   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 192   Null-terminator, then ASSERT().
 193
 194   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 195                           Unicode string.
 196   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 197   @param  FormatString    Null-terminated Unicode format string.
 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 Unicode 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 Unicode format string.
 329
 330   @return The number of ASCII characters in the produced output buffer not including the
 331           Null-terminator.
 332
 333 **/
 334 UINTN
 335 EFIAPI
 336 AsciiSPrint (
 337   OUT CHAR8        *StartOfBuffer,
 338   IN  UINTN        BufferSize,
 339   IN  CONST CHAR8  *FormatString,
 340   ...
 341   );
 342
 343 /**
 344   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 345   ASCII format string and a VA_LIST argument list.
 346
 347   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 348   and BufferSize.
 349   The ASCII string is produced by parsing the format string specified by FormatString.
 350   Arguments are pulled from the variable argument list specified by Marker based on
 351   the contents of the format string.
 352   The number of ASCII characters in the produced output buffer is returned not including
 353   the Null-terminator.
 354   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 355
 356   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 357   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 358   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 359   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 360   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 361   ASSERT().
 362   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 363   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 364   Null-terminator, then ASSERT().
 365
 366   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 367                           ASCII string.
 368   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 369   @param  FormatString    Null-terminated Unicode format string.
 370   @param  Marker          VA_LIST marker for the variable argument list.
 371
 372   @return The number of ASCII characters in the produced output buffer not including the
 373           Null-terminator.
 374
 375 **/
 376 UINTN
 377 EFIAPI
 378 AsciiVSPrintUnicodeFormat (
 379   OUT CHAR8         *StartOfBuffer,
 380   IN  UINTN         BufferSize,
 381   IN  CONST CHAR16  *FormatString,
 382   IN  VA_LIST       Marker
 383   );
 384
 385 /**
 386   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 387   ASCII format string and  variable argument list.
 388
 389   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 390   and BufferSize.
 391   The ASCII string is produced by parsing the format string specified by FormatString.
 392   Arguments are pulled from the variable argument list based on the contents of the
 393   format string.
 394   The number of ASCII characters in the produced output buffer is returned not including
 395   the Null-terminator.
 396   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 397
 398   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 399   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 400   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 401   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 402   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 403   ASSERT().
 404   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 405   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 406   Null-terminator, then ASSERT().
 407
 408   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 409                           ASCII string.
 410   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 411   @param  FormatString    Null-terminated Unicode format string.
 412
 413   @return The number of ASCII characters in the produced output buffer not including the
 414           Null-terminator.
 415
 416 **/
 417 UINTN
 418 EFIAPI
 419 AsciiSPrintUnicodeFormat (
 420   OUT CHAR8         *StartOfBuffer,
 421   IN  UINTN         BufferSize,
 422   IN  CONST CHAR16  *FormatString,
 423   ...
 424   );
 425
 426 /**
 427   Converts a decimal value to a Null-terminated ASCII string.
 428
 429   Converts the decimal number specified by Value to a Null-terminated ASCII string
 430   specified by Buffer containing at most Width characters. No padding of spaces
 431   is ever performed.
 432   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 433   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 434   If the conversion contains more than Width characters, then only the first Width
 435   characters are returned, and the total number of characters required to perform
 436   the conversion is returned.
 437   Additional conversion parameters are specified in Flags.
 438   The Flags bit LEFT_JUSTIFY is always ignored.
 439   All conversions are left justified in Buffer.
 440   If Width is 0, PREFIX_ZERO is ignored in Flags.
 441   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 442   are inserted every 3rd digit starting from the right.
 443   If HEX_RADIX is set in Flags, then the output buffer will be
 444   formatted in hexadecimal format.
 445   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 446   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 447   then Buffer is padded with '0' characters so the combination of the optional '-'
 448   sign character, '0' characters, digit characters for Value, and the Null-terminator
 449   add up to Width characters.
 450
 451   If Buffer is NULL, then ASSERT().
 452   If unsupported bits are set in Flags, then ASSERT().
 453   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 454   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 455
 456   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 457                   ASCII string.
 458   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 459   @param  Value   The 64-bit signed value to convert to a string.
 460   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 461                   the Null-terminator.
 462
 463   @return The number of ASCII characters in Buffer not including the Null-terminator.
 464
 465 **/
 466 UINTN
 467 EFIAPI
 468 AsciiValueToString (
 469   IN OUT CHAR8  *Buffer,
 470   IN UINTN      Flags,
 471   IN INT64      Value,
 472   IN UINTN      Width
 473   );
 474
 475 #endif