EdkCompatibilityPkg/Foundation/Library/EdkIIGlueLib/Include/Library/EdkIIGluePrintLib.h

   1 /*++
   2
   3 Copyright (c) 2004 - 2006, Intel Corporation
   4 All rights reserved. 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 HEX_RADIX is set in Flags, then the output buffer will be
 236   formatted in hexadecimal format.
 237   If Value is < 0 and HEX_RADIX 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 HEX_RADIX 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 HEX_RADIX 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 HEX_RADIX is set in Flags, then the output buffer will be
 450   formatted in hexadecimal format.
 451   If Value is < 0 and HEX_RADIX 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 HEX_RADIX 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