MdeModulePkg/Include/Protocol/Print2.h

   1 /** @file
   2
   3   This print protocol defines six basic print functions to
   4   print the format unicode and ascii string.
   5
   6 Copyright (c) 2006 - 2009, Intel Corporation
   7 All rights reserved. This program and the accompanying materials
   8 are licensed and made available under the terms and conditions of the BSD License
   9 which accompanies this distribution.  The full text of the license may be found at
  10 http://opensource.org/licenses/bsd-license.php
  11
  12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __PPRINT2_H__
  18 #define __PPRINT2_H__
  19
  20 #define EFI_PRINT2_PROTOCOL_GUID  \
  21    { 0x5bcc3dbc, 0x8c57, 0x450a, { 0xbb, 0xc, 0xa1, 0xc0, 0xbd, 0xde, 0x48, 0xc } }
  22
  23 //
  24 // Forward reference for pure ANSI compatability
  25 //
  26 typedef struct _EFI_PRINT2_PROTOCOL  EFI_PRINT2_PROTOCOL;
  27
  28 /**
  29   Produces a Null-terminated Unicode string in an output buffer based on
  30   a Null-terminated Unicode format string and a VA_LIST argument list
  31
  32   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  33   and BufferSize.
  34   The Unicode string is produced by parsing the format string specified by FormatString.
  35   Arguments are pulled from the variable argument list specified by Marker based on the
  36   contents of the format string.
  37   The number of Unicode characters in the produced output buffer is returned not including
  38   the Null-terminator.
  39   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  40
  41   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  42   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  43   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  44   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
  45   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  46   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
  47   ASSERT().
  48   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  49   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  50   Null-terminator, then ASSERT().
  51
  52   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  53                           Unicode string.
  54   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  55   @param  FormatString    Null-terminated Unicode format string.
  56   @param  Marker          VA_LIST marker for the variable argument list.
  57
  58   @return The number of Unicode characters in the produced output buffer not including the
  59           Null-terminator.
  60
  61 **/
  62 typedef
  63 UINTN
  64 (EFIAPI *UNICODE_VS_PRINT) (
  65   OUT CHAR16        *StartOfBuffer,
  66   IN  UINTN         BufferSize,
  67   IN  CONST CHAR16  *FormatString,
  68   IN  VA_LIST       Marker
  69   );
  70
  71 /**
  72   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
  73   Unicode format string and variable argument list.
  74
  75   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  76   and BufferSize.
  77   The Unicode string is produced by parsing the format string specified by FormatString.
  78   Arguments are pulled from the variable argument list based on the contents of the format string.
  79   The number of Unicode characters in the produced output buffer is returned not including
  80   the Null-terminator.
  81   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  82
  83   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  84   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  85   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  86   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
  87   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  88   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
  89   ASSERT().
  90   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  91   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  92   Null-terminator, then ASSERT().
  93
  94   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  95                           Unicode string.
  96   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  97   @param  FormatString    Null-terminated Unicode format string.
  98   @param  ...             Variable argument list whose contents are accessed based on the
  99                           format string specified by FormatString.
 100
 101   @return The number of Unicode characters in the produced output buffer not including the
 102           Null-terminator.
 103
 104 **/
 105 typedef
 106 UINTN
 107 (EFIAPI *UNICODE_S_PRINT) (
 108   OUT CHAR16        *StartOfBuffer,
 109   IN  UINTN         BufferSize,
 110   IN  CONST CHAR16  *FormatString,
 111   ...
 112   );
 113
 114 /**
 115   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 116   ASCII format string and a VA_LIST argument list
 117
 118   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 119   and BufferSize.
 120   The Unicode string is produced by parsing the format string specified by FormatString.
 121   Arguments are pulled from the variable argument list specified by Marker based on the
 122   contents of the format string.
 123   The number of Unicode characters in the produced output buffer is returned not including
 124   the Null-terminator.
 125   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 126
 127   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 128   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 129   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 130   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 131   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 132   ASSERT().
 133   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 134   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 135   Null-terminator, then ASSERT().
 136
 137   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 138                           Unicode string.
 139   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 140   @param  FormatString    Null-terminated ASCII format string.
 141   @param  Marker          VA_LIST marker for the variable argument list.
 142
 143   @return The number of Unicode characters in the produced output buffer not including the
 144           Null-terminator.
 145
 146 **/
 147 typedef
 148 UINTN
 149 (EFIAPI *UNICODE_VS_PRINT_ASCII_FORMAT) (
 150   OUT CHAR16       *StartOfBuffer,
 151   IN  UINTN        BufferSize,
 152   IN  CONST CHAR8  *FormatString,
 153   IN  VA_LIST      Marker
 154   );
 155
 156 /**
 157   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 158   ASCII format string and  variable argument list.
 159
 160   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 161   and BufferSize.
 162   The Unicode string is produced by parsing the format string specified by FormatString.
 163   Arguments are pulled from the variable argument list based on the contents of the
 164   format string.
 165   The number of Unicode characters in the produced output buffer is returned not including
 166   the Null-terminator.
 167   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 168
 169   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 170   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 171   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 172   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 173   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 174   ASSERT().
 175   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 176   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 177   Null-terminator, then ASSERT().
 178
 179   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 180                           Unicode string.
 181   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 182   @param  FormatString    Null-terminated ASCII format string.
 183   @param  ...             Variable argument list whose contents are accessed based on the
 184                           format string specified by FormatString.
 185
 186   @return The number of Unicode characters in the produced output buffer not including the
 187           Null-terminator.
 188
 189 **/
 190 typedef
 191 UINTN
 192 (EFIAPI *UNICODE_S_PRINT_ASCII_FORMAT) (
 193   OUT CHAR16       *StartOfBuffer,
 194   IN  UINTN        BufferSize,
 195   IN  CONST CHAR8  *FormatString,
 196   ...
 197   );
 198
 199 /**
 200   Converts a decimal value to a Null-terminated Unicode string.
 201
 202   Converts the decimal number specified by Value to a Null-terminated Unicode
 203   string specified by Buffer containing at most Width characters. No padding of spaces
 204   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 205   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 206   If the conversion contains more than Width characters, then only the first
 207   Width characters are returned, and the total number of characters
 208   required to perform the conversion is returned.
 209   Additional conversion parameters are specified in Flags.
 210
 211   The Flags bit LEFT_JUSTIFY is always ignored.
 212   All conversions are left justified in Buffer.
 213   If Width is 0, PREFIX_ZERO is ignored in Flags.
 214   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 215   are inserted every 3rd digit starting from the right.
 216   If HEX_RADIX is set in Flags, then the output buffer will be
 217   formatted in hexadecimal format.
 218   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 219   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 220   then Buffer is padded with '0' characters so the combination of the optional '-'
 221   sign character, '0' characters, digit characters for Value, and the Null-terminator
 222   add up to Width characters.
 223   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 224   If Buffer is NULL, then ASSERT().
 225   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 226   If unsupported bits are set in Flags, then ASSERT().
 227   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 228   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 229
 230   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 231                   Unicode string.
 232   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 233   @param  Value   The 64-bit signed value to convert to a string.
 234   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 235                   the Null-terminator.
 236
 237   @return The number of Unicode characters in Buffer not including the Null-terminator.
 238
 239 **/
 240 typedef
 241 UINTN
 242 (EFIAPI *UNICODE_VALUE_TO_STRING) (
 243   IN OUT CHAR16  *Buffer,
 244   IN UINTN       Flags,
 245   IN INT64       Value,
 246   IN UINTN       Width
 247   );
 248
 249 /**
 250   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 251   ASCII format string and a VA_LIST argument list.
 252
 253   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 254   and BufferSize.
 255   The ASCII string is produced by parsing the format string specified by FormatString.
 256   Arguments are pulled from the variable argument list specified by Marker based on
 257   the contents of the format string.
 258   The number of ASCII characters in the produced output buffer is returned not including
 259   the Null-terminator.
 260   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 261
 262   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 263   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 264   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 265   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 266   ASSERT().
 267   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 268   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 269   Null-terminator, then ASSERT().
 270
 271   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 272                           ASCII string.
 273   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 274   @param  FormatString    Null-terminated ASCII format string.
 275   @param  Marker          VA_LIST marker for the variable argument list.
 276
 277   @return The number of ASCII characters in the produced output buffer not including the
 278           Null-terminator.
 279
 280 **/
 281 typedef
 282 UINTN
 283 (EFIAPI *ASCII_VS_PRINT) (
 284   OUT CHAR8         *StartOfBuffer,
 285   IN  UINTN         BufferSize,
 286   IN  CONST CHAR8   *FormatString,
 287   IN  VA_LIST       Marker
 288   );
 289
 290 /**
 291   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 292   ASCII format string and  variable argument list.
 293
 294   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 295   and BufferSize.
 296   The ASCII string is produced by parsing the format string specified by FormatString.
 297   Arguments are pulled from the variable argument list based on the contents of the
 298   format string.
 299   The number of ASCII characters in the produced output buffer is returned not including
 300   the Null-terminator.
 301   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 302
 303   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 304   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 305   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 306   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 307   ASSERT().
 308   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 309   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 310   Null-terminator, then ASSERT().
 311
 312   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 313                           ASCII string.
 314   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 315   @param  FormatString    Null-terminated ASCII format string.
 316   @param  ...             Variable argument list whose contents are accessed based on the
 317                           format string specified by FormatString.
 318
 319   @return The number of ASCII characters in the produced output buffer not including the
 320           Null-terminator.
 321
 322 **/
 323 typedef
 324 UINTN
 325 (EFIAPI *ASCII_S_PRINT) (
 326   OUT CHAR8        *StartOfBuffer,
 327   IN  UINTN        BufferSize,
 328   IN  CONST CHAR8  *FormatString,
 329   ...
 330   );
 331
 332 /**
 333   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 334   Unicode format string and a VA_LIST argument list.
 335
 336   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 337   and BufferSize.
 338   The ASCII string is produced by parsing the format string specified by FormatString.
 339   Arguments are pulled from the variable argument list specified by Marker based on
 340   the contents of the format string.
 341   The number of ASCII characters in the produced output buffer is returned not including
 342   the Null-terminator.
 343   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 344
 345   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 346   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 347   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 348   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 349   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 350   ASSERT().
 351   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 352   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 353   Null-terminator, then ASSERT().
 354
 355   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 356                           ASCII string.
 357   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 358   @param  FormatString    Null-terminated Unicode format string.
 359   @param  Marker          VA_LIST marker for the variable argument list.
 360
 361   @return The number of ASCII characters in the produced output buffer not including the
 362           Null-terminator.
 363
 364 **/
 365 typedef
 366 UINTN
 367 (EFIAPI *ASCII_VS_PRINT_UNICODE_FORMAT) (
 368   OUT CHAR8         *StartOfBuffer,
 369   IN  UINTN         BufferSize,
 370   IN  CONST CHAR16  *FormatString,
 371   IN  VA_LIST       Marker
 372   );
 373
 374 /**
 375   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 376   Unicode format string and  variable argument list.
 377
 378   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 379   and BufferSize.
 380   The ASCII string is produced by parsing the format string specified by FormatString.
 381   Arguments are pulled from the variable argument list based on the contents of the
 382   format string.
 383   The number of ASCII characters in the produced output buffer is returned not including
 384   the Null-terminator.
 385   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 386
 387   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 388   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 389   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 390   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 391   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 392   ASSERT().
 393   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 394   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 395   Null-terminator, then ASSERT().
 396
 397   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 398                           ASCII string.
 399   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 400   @param  FormatString    Null-terminated Unicode format string.
 401   @param  ...             Variable argument list whose contents are accessed based on the
 402                           format string specified by FormatString.
 403
 404   @return The number of ASCII characters in the produced output buffer not including the
 405           Null-terminator.
 406
 407 **/
 408 typedef
 409 UINTN
 410 (EFIAPI *ASCII_S_PRINT_UNICODE_FORMAT) (
 411   OUT CHAR8         *StartOfBuffer,
 412   IN  UINTN         BufferSize,
 413   IN  CONST CHAR16  *FormatString,
 414   ...
 415   );
 416
 417 /**
 418   Converts a decimal value to a Null-terminated ASCII string.
 419
 420   Converts the decimal number specified by Value to a Null-terminated ASCII string
 421   specified by Buffer containing at most Width characters. No padding of spaces
 422   is ever performed.
 423   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 424   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 425   If the conversion contains more than Width characters, then only the first Width
 426   characters are returned, and the total number of characters required to perform
 427   the conversion is returned.
 428   Additional conversion parameters are specified in Flags.
 429   The Flags bit LEFT_JUSTIFY is always ignored.
 430   All conversions are left justified in Buffer.
 431   If Width is 0, PREFIX_ZERO is ignored in Flags.
 432   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 433   are inserted every 3rd digit starting from the right.
 434   If HEX_RADIX is set in Flags, then the output buffer will be
 435   formatted in hexadecimal format.
 436   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 437   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 438   then Buffer is padded with '0' characters so the combination of the optional '-'
 439   sign character, '0' characters, digit characters for Value, and the Null-terminator
 440   add up to Width characters.
 441
 442   If Buffer is NULL, then ASSERT().
 443   If unsupported bits are set in Flags, then ASSERT().
 444   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 445   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 446
 447   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 448                   ASCII string.
 449   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 450   @param  Value   The 64-bit signed value to convert to a string.
 451   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 452                   the Null-terminator.
 453
 454   @return The number of ASCII characters in Buffer not including the Null-terminator.
 455
 456 **/
 457 typedef
 458 UINTN
 459 (EFIAPI *ASCII_VALUE_TO_STRING) (
 460   OUT CHAR8      *Buffer,
 461   IN  UINTN      Flags,
 462   IN  INT64      Value,
 463   IN  UINTN      Width
 464   );
 465
 466 struct _EFI_PRINT2_PROTOCOL {
 467   UNICODE_VS_PRINT                 UnicodeVSPrint;
 468   UNICODE_S_PRINT                  UnicodeSPrint;
 469   UNICODE_VS_PRINT_ASCII_FORMAT    UnicodeVSPrintAsciiFormat;
 470   UNICODE_S_PRINT_ASCII_FORMAT     UnicodeSPrintAsciiFormat;
 471   UNICODE_VALUE_TO_STRING          UnicodeValueToString;
 472   ASCII_VS_PRINT                   AsciiVSPrint;
 473   ASCII_S_PRINT                    AsciiSPrint;
 474   ASCII_VS_PRINT_UNICODE_FORMAT    AsciiVSPrintUnicodeFormat;
 475   ASCII_S_PRINT_UNICODE_FORMAT     AsciiSPrintUnicodeFormat;
 476   ASCII_VALUE_TO_STRING            AsciiValueToString;
 477 };
 478
 479 extern EFI_GUID gEfiPrint2ProtocolGuid;
 480
 481 #endif