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 length of the produced output buffer is returned.
  54   If BufferSize is 0, then no output buffer is produced and 0 is returned.
  55
  56   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
  57   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
  58   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  59   PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
  60   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  61   contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
  62
  63   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
  64                           Unicode string.
  65   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  66   @param  FormatString    Null-terminated Unicode format string.
  67   @param  Marker          VA_LIST marker for the variable argument list.
  68
  69   @return return Length of the produced output buffer.
  70
  71 **/
  72 UINTN
  73 EFIAPI
  74 UnicodeVSPrint (
  75   OUT CHAR16        *StartOfBuffer,
  76   IN  UINTN         BufferSize,
  77   IN  CONST CHAR16  *FormatString,
  78   IN  VA_LIST       Marker
  79   );
  80
  81 /**
  82   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
  83   Unicode format string and variable argument list.
  84
  85   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  86   and BufferSize.
  87   The Unicode string is produced by parsing the format string specified by FormatString.
  88   Arguments are pulled from the variable argument list based on the contents of the format string.
  89   The length of the produced output buffer is returned.
  90   If BufferSize is 0, then no output buffer is produced and 0 is returned.
  91
  92   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
  93   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
  94   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  95   PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
  96   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  97   contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
  98
  99   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
 100                           Unicode string.
 101   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 102   @param  FormatString    Null-terminated Unicode format string.
 103
 104   @return Length of the produced output buffer.
 105
 106 **/
 107 UINTN
 108 EFIAPI
 109 UnicodeSPrint (
 110   OUT CHAR16        *StartOfBuffer,
 111   IN  UINTN         BufferSize,
 112   IN  CONST CHAR16  *FormatString,
 113   ...
 114   );
 115
 116 /**
 117   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 118   ASCII format string and a VA_LIST argument list
 119
 120   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 121   and BufferSize.
 122   The Unicode string is produced by parsing the format string specified by FormatString.
 123   Arguments are pulled from the variable argument list specified by Marker based on the
 124   contents of the format string.
 125   The length of the produced output buffer is returned.
 126   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 127
 128   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
 129   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
 130   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 131   PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
 132   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 133   contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
 134
 135   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
 136                           Unicode string.
 137   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 138   @param  FormatString    Null-terminated Unicode format string.
 139   @param  Marker          VA_LIST marker for the variable argument list.
 140
 141   @return Length of the produced output buffer.
 142
 143 **/
 144 UINTN
 145 EFIAPI
 146 UnicodeVSPrintAsciiFormat (
 147   OUT CHAR16       *StartOfBuffer,
 148   IN  UINTN        BufferSize,
 149   IN  CONST CHAR8  *FormatString,
 150   IN  VA_LIST      Marker
 151   );
 152
 153 /**
 154   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 155   ASCII format string and  variable argument list.
 156
 157   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 158   and BufferSize.
 159   The Unicode string is produced by parsing the format string specified by FormatString.
 160   Arguments are pulled from the variable argument list based on the contents of the
 161   format string.
 162   The length of the produced output buffer is returned.
 163   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 164
 165   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
 166   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
 167   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 168   PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
 169   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 170   contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
 171
 172   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
 173                           Unicode string.
 174   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 175   @param  FormatString    Null-terminated Unicode format string.
 176
 177   @return Length of the produced output buffer.
 178
 179 **/
 180 UINTN
 181 EFIAPI
 182 UnicodeSPrintAsciiFormat (
 183   OUT CHAR16       *StartOfBuffer,
 184   IN  UINTN        BufferSize,
 185   IN  CONST CHAR8  *FormatString,
 186   ...
 187   );
 188
 189 /**
 190   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 191   ASCII format string and a VA_LIST argument list.
 192
 193   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 194   and BufferSize.
 195   The ASCII string is produced by parsing the format string specified by FormatString.
 196   Arguments are pulled from the variable argument list specified by Marker based on
 197   the contents of the format string.
 198   The length of the produced output buffer is returned.
 199   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 200
 201   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
 202   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
 203   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 204   PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 205   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 206   contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 207
 208   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
 209                           ASCII string.
 210   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 211   @param  FormatString    Null-terminated Unicode format string.
 212   @param  Marker          VA_LIST marker for the variable argument list.
 213
 214   @return Length of the produced output buffer.
 215
 216 **/
 217 UINTN
 218 EFIAPI
 219 AsciiVSPrint (
 220   OUT CHAR8         *StartOfBuffer,
 221   IN  UINTN         BufferSize,
 222   IN  CONST CHAR8   *FormatString,
 223   IN  VA_LIST       Marker
 224   );
 225
 226 /**
 227   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 228   ASCII format string and  variable argument list.
 229
 230   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 231   and BufferSize.
 232   The ASCII string is produced by parsing the format string specified by FormatString.
 233   Arguments are pulled from the variable argument list based on the contents of the
 234   format string.
 235   The length of the produced output buffer is returned.
 236   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 237
 238   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
 239   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
 240   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 241   PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 242   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 243   contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 244
 245   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
 246                           ASCII string.
 247   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 248   @param  FormatString    Null-terminated Unicode format string.
 249
 250   @return Length of the produced output buffer.
 251
 252 **/
 253 UINTN
 254 EFIAPI
 255 AsciiSPrint (
 256   OUT CHAR8        *StartOfBuffer,
 257   IN  UINTN        BufferSize,
 258   IN  CONST CHAR8  *FormatString,
 259   ...
 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 length of the produced output buffer is returned.
 272   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 273
 274   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
 275   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
 276   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 277   PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 278   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 279   contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 280
 281   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
 282                           ASCII string.
 283   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 284   @param  FormatString    Null-terminated Unicode format string.
 285   @param  Marker          VA_LIST marker for the variable argument list.
 286
 287   @return Length of the produced output buffer.
 288
 289 **/
 290 UINTN
 291 EFIAPI
 292 AsciiVSPrintUnicodeFormat (
 293   OUT CHAR8         *StartOfBuffer,
 294   IN  UINTN         BufferSize,
 295   IN  CONST CHAR16  *FormatString,
 296   IN  VA_LIST       Marker
 297   );
 298
 299 /**
 300   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 301   ASCII format string and  variable argument list.
 302
 303   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 304   and BufferSize.
 305   The ASCII string is produced by parsing the format string specified by FormatString.
 306   Arguments are pulled from the variable argument list based on the contents of the
 307   format string.
 308   The length of the produced output buffer is returned.
 309   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 310
 311   If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().
 312   If BufferSize is not 0 and FormatString is NULL, then ASSERT().
 313   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 314   PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 315   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 316   contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().
 317
 318   @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated
 319                           ASCII string.
 320   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 321   @param  FormatString    Null-terminated Unicode format string.
 322
 323   @return Length of the produced output buffer.
 324
 325 **/
 326 UINTN
 327 EFIAPI
 328 AsciiSPrintUnicodeFormat (
 329   OUT CHAR8         *StartOfBuffer,
 330   IN  UINTN         BufferSize,
 331   IN  CONST CHAR16  *FormatString,
 332   ...
 333   );
 334
 335 /**
 336   Converts a decimal value to a Null-terminated Unicode string.
 337
 338   Converts the decimal number specified by Value to a Null-terminated Unicode
 339   string specified by Buffer containing at most Width characters.
 340   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 341   The total number of characters placed in Buffer is returned.
 342   If the conversion contains more than Width characters, then only the first
 343   Width characters are returned, and the total number of characters
 344   required to perform the conversion is returned.
 345   Additional conversion parameters are specified in Flags.
 346   The Flags bit LEFT_JUSTIFY is always ignored.
 347   All conversions are left justified in Buffer.
 348   If Width is 0, PREFIX_ZERO is ignored in Flags.
 349   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 350   are inserted every 3rd digit starting from the right.
 351   If Value is < 0, then the fist character in Buffer is a '-'.
 352   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 353   then Buffer is padded with '0' characters so the combination of the optional '-'
 354   sign character, '0' characters, digit characters for Value, and the Null-terminator
 355   add up to Width characters.
 356
 357   If Buffer is NULL, then ASSERT().
 358   If unsupported bits are set in Flags, then ASSERT().
 359   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 360
 361   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 362                   Unicode string.
 363   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 364   @param  Value   The 64-bit signed value to convert to a string.
 365   @param  Width   The maximum number of Unicode characters to place in Buffer.
 366
 367   @return Total number of characters required to perform the conversion.
 368
 369 **/
 370 UINTN
 371 EFIAPI
 372 UnicodeValueToString (
 373   IN OUT CHAR16  *Buffer,
 374   IN UINTN       Flags,
 375   IN INT64       Value,
 376   IN UINTN       Width
 377   );
 378
 379 /**
 380   Converts a decimal value to a Null-terminated ASCII string.
 381
 382   Converts the decimal number specified by Value to a Null-terminated ASCII string
 383   specified by Buffer containing at most Width characters.
 384   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 385   The total number of characters placed in Buffer is returned.
 386   If the conversion contains more than Width characters, then only the first Width
 387   characters are returned, and the total number of characters required to perform
 388   the conversion is returned.
 389   Additional conversion parameters are specified in Flags.
 390   The Flags bit LEFT_JUSTIFY is always ignored.
 391   All conversions are left justified in Buffer.
 392   If Width is 0, PREFIX_ZERO is ignored in Flags.
 393   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 394   are inserted every 3rd digit starting from the right.
 395   If Value is < 0, then the fist character in Buffer is a '-'.
 396   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then Buffer
 397   is padded with '0' characters so the combination of the optional '-'
 398   sign character, '0' characters, digit characters for Value, and the
 399   Null-terminator add up to Width characters.
 400
 401   If Buffer is NULL, then ASSERT().
 402   If unsupported bits are set in Flags, then ASSERT().
 403   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 404
 405   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 406                   ASCII string.
 407   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 408   @param  Value   The 64-bit signed value to convert to a string.
 409   @param  Width   The maximum number of ASCII characters to place in Buffer.
 410
 411   @return Total number of characters required to perform the conversion.
 412
 413 **/
 414 UINTN
 415 EFIAPI
 416 AsciiValueToString (
 417   IN OUT CHAR8  *Buffer,
 418   IN UINTN      Flags,
 419   IN INT64      Value,
 420   IN UINTN      Width
 421   );
 422
 423 #endif