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