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 - 2010, Intel Corporation. All rights reserved.<BR>
   7 This program and the accompanying materials are licensed and made available under
   8 the terms and conditions of the BSD License that accompanies this distribution.
   9 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   { 0xf05976ef, 0x83f1, 0x4f3d, { 0x86, 0x19, 0xf7, 0x59, 0x5d, 0x41, 0xe5, 0x38 } }
  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 BASE_LIST argument list
  31
  32   Produces a Null-terminated Unicode string in the output buffer
  33   specified by StartOfBuffer 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.
  36   Marker is constructed based on the contents of the format string.
  37   This function returns the number of Unicode characters in the produced output buffer,
  38   not including 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 ASSERT().
  47   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  48   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  49   Null-terminator, then ASSERT().
  50
  51   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  52                           Unicode string.
  53   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  54   @param  FormatString    Null-terminated Unicode format string.
  55   @param  Marker          BASE_LIST marker for the variable argument list.
  56
  57   @return The number of Unicode characters in the produced output buffer, not including the
  58           Null-terminator.
  59
  60 **/
  61 typedef
  62 UINTN
  63 (EFIAPI *UNICODE_BS_PRINT)(
  64   OUT CHAR16        *StartOfBuffer,
  65   IN  UINTN         BufferSize,
  66   IN  CONST CHAR16  *FormatString,
  67   IN  BASE_LIST     Marker
  68   );
  69
  70 /**
  71   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
  72   Unicode format string and variable argument list.
  73
  74   Produces a Null-terminated Unicode string in the output buffer
  75   specified by StartOfBuffer and BufferSize.
  76   The Unicode string is produced by parsing the format string specified by FormatString.
  77   Arguments are pulled from the variable argument list based on the contents of the format string.
  78   This function returns the number of Unicode characters in the produced output buffer,
  79   not including the Null-terminator.
  80   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  81
  82   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  83   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  84   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  85   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
  86   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  87   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then ASSERT().
  88   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  89   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  90   Null-terminator, then ASSERT().
  91
  92   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  93                           Unicode string.
  94   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  95   @param  FormatString    Null-terminated Unicode format string.
  96   @param  ...             Variable argument list whose contents are accessed based on the
  97                           format string specified by FormatString.
  98
  99   @return The number of Unicode characters in the produced output buffer not including the
 100           Null-terminator.
 101
 102 **/
 103 typedef
 104 UINTN
 105 (EFIAPI *UNICODE_S_PRINT)(
 106   OUT CHAR16        *StartOfBuffer,
 107   IN  UINTN         BufferSize,
 108   IN  CONST CHAR16  *FormatString,
 109   ...
 110   );
 111
 112 /**
 113   Produces a Null-terminated Unicode string in an output buffer, based on a Null-terminated
 114   ASCII format string and a BASE_LIST argument list
 115
 116   Produces a Null-terminated Unicode string in the output buffer
 117   specified by StartOfBuffer and BufferSize.
 118   The Unicode string is produced by parsing the format string specified by FormatString.
 119   Arguments are pulled from the variable argument list specified by Marker based on the
 120   contents of the format string.
 121   This function returns the number of Unicode characters in the produced output buffer,
 122   not including the Null-terminator.
 123   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 124
 125   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 126   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 127   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 128   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 129   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then ASSERT().
 130   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 131   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 132   Null-terminator, then ASSERT().
 133
 134   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 135                           Unicode string.
 136   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 137   @param  FormatString    Null-terminated ASCII format string.
 138   @param  Marker          BASE_LIST marker for the variable argument list.
 139
 140   @return The number of Unicode characters in the produced output buffer not including the
 141           Null-terminator.
 142
 143 **/
 144 typedef
 145 UINTN
 146 (EFIAPI *UNICODE_BS_PRINT_ASCII_FORMAT)(
 147   OUT CHAR16       *StartOfBuffer,
 148   IN  UINTN        BufferSize,
 149   IN  CONST CHAR8  *FormatString,
 150   IN  BASE_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 a variable argument list.
 156
 157   Produces a Null-terminated Unicode string in the output buffer
 158   specified by StartOfBuffer 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 format string.
 161   This function returns the number of Unicode characters in the produced output buffer,
 162   not including the Null-terminator.
 163   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 164
 165   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 166   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 167   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 168   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 169   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then ASSERT().
 170   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 171   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 172   Null-terminator, then ASSERT().
 173
 174   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 175                           Unicode string.
 176   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 177   @param  FormatString    Null-terminated ASCII format string.
 178   @param  ...             Variable argument list whose contents are accessed based on the
 179                           format string specified by FormatString.
 180
 181   @return The number of Unicode characters in the produced output buffer not including the
 182           Null-terminator.
 183
 184 **/
 185 typedef
 186 UINTN
 187 (EFIAPI *UNICODE_S_PRINT_ASCII_FORMAT)(
 188   OUT CHAR16       *StartOfBuffer,
 189   IN  UINTN        BufferSize,
 190   IN  CONST CHAR8  *FormatString,
 191   ...
 192   );
 193
 194 /**
 195   Converts a decimal value to a Null-terminated Unicode string.
 196
 197   Converts the decimal number specified by Value to a Null-terminated Unicode
 198   string specified by Buffer containing at most Width characters. No padding of spaces
 199   is ever performed. If Width is 0, then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 200   This function returns the number of Unicode characters in Buffer, not including
 201   the Null-terminator.
 202   If the conversion contains more than Width characters, this function returns
 203   the first Width characters in the conversion, along with the total number of characters in the conversion.
 204   Additional conversion parameters are specified in Flags.
 205
 206   The Flags bit LEFT_JUSTIFY is always ignored.
 207   All conversions are left justified in Buffer.
 208   If Width is 0, PREFIX_ZERO is ignored in Flags.
 209   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 210   are inserted every 3rd digit starting from the right.
 211   If RADIX_HEX is set in Flags, then the output buffer will be
 212   formatted in hexadecimal format.
 213   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 214   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 215   then Buffer is padded with '0' characters so the combination of the optional '-'
 216   sign character, '0' characters, digit characters for Value, and the Null-terminator
 217   add up to Width characters.
 218   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 219   If Buffer is NULL, then ASSERT().
 220   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 221   If unsupported bits are set in Flags, then ASSERT().
 222   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 223   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 224
 225   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 226                   Unicode string.
 227   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 228   @param  Value   The 64-bit signed value to convert to a string.
 229   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 230                   the Null-terminator.
 231
 232   @return The number of Unicode characters in Buffer not including the Null-terminator.
 233
 234 **/
 235 typedef
 236 UINTN
 237 (EFIAPI *UNICODE_VALUE_TO_STRING)(
 238   IN OUT CHAR16  *Buffer,
 239   IN UINTN       Flags,
 240   IN INT64       Value,
 241   IN UINTN       Width
 242   );
 243
 244 /**
 245   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 246   ASCII format string and a BASE_LIST argument list.
 247
 248   Produces a Null-terminated ASCII string in the output buffer
 249   pecified by StartOfBuffer and BufferSize.
 250   The ASCII string is produced by parsing the format string specified by FormatString.
 251   Arguments are pulled from the variable argument list specified by Marker based on
 252   the contents of the format string.
 253   This function returns the number of ASCII characters in the output buffer,
 254   not including the Null-terminator.
 255   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 256
 257   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 258   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 259   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 260   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then ASSERT().
 261   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 262   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 263   Null-terminator, then ASSERT().
 264
 265   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 266                           ASCII string.
 267   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 268   @param  FormatString    Null-terminated ASCII format string.
 269   @param  Marker          BASE_LIST marker for the variable argument list.
 270
 271   @return The number of ASCII characters in the produced output buffer not including the
 272           Null-terminator.
 273
 274 **/
 275 typedef
 276 UINTN
 277 (EFIAPI *ASCII_BS_PRINT)(
 278   OUT CHAR8         *StartOfBuffer,
 279   IN  UINTN         BufferSize,
 280   IN  CONST CHAR8   *FormatString,
 281   IN  BASE_LIST     Marker
 282   );
 283
 284 /**
 285   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 286   ASCII format string and variable argument list.
 287
 288   Produces a Null-terminated ASCII string in the output buffer
 289   specified by StartOfBuffer and BufferSize.
 290   The ASCII string is produced by parsing the format string specified by FormatString.
 291   Arguments are pulled from the variable argument list based on the contents of the format string.
 292   This function returns the number of ASCII characters in the output buffer,
 293   not including the Null-terminator.
 294   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 295
 296   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 297   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 298   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 299   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then ASSERT().
 300   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 301   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 302   Null-terminator, then ASSERT().
 303
 304   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 305                           ASCII string.
 306   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 307   @param  FormatString    Null-terminated ASCII format string.
 308   @param  ...             Variable argument list whose contents are accessed based on the
 309                           format string specified by FormatString.
 310
 311   @return The number of ASCII characters in the produced output buffer not including the
 312           Null-terminator.
 313
 314 **/
 315 typedef
 316 UINTN
 317 (EFIAPI *ASCII_S_PRINT)(
 318   OUT CHAR8        *StartOfBuffer,
 319   IN  UINTN        BufferSize,
 320   IN  CONST CHAR8  *FormatString,
 321   ...
 322   );
 323
 324 /**
 325   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 326   Unicode format string and a BASE_LIST argument list.
 327
 328   Produces a Null-terminated ASCII string in the output buffer
 329   specified by StartOfBuffer and BufferSize.
 330   The ASCII string is produced by parsing the format string specified by FormatString.
 331   Arguments are pulled from the variable argument list specified by Marker based on
 332   the contents of the format string.
 333   This function returns the number of ASCII characters in the output buffer,
 334   not including the Null-terminator.
 335   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 336
 337   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 338   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 339   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 340   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 341   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then ASSERT().
 342   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 343   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 344   Null-terminator, then ASSERT().
 345
 346   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 347                           ASCII string.
 348   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 349   @param  FormatString    Null-terminated Unicode format string.
 350   @param  Marker          BASE_LIST marker for the variable argument list.
 351
 352   @return The number of ASCII characters in the produced output buffer not including the
 353           Null-terminator.
 354
 355 **/
 356 typedef
 357 UINTN
 358 (EFIAPI *ASCII_BS_PRINT_UNICODE_FORMAT)(
 359   OUT CHAR8         *StartOfBuffer,
 360   IN  UINTN         BufferSize,
 361   IN  CONST CHAR16  *FormatString,
 362   IN  BASE_LIST     Marker
 363   );
 364
 365 /**
 366   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 367   Unicode format string and  variable argument list.
 368
 369   Produces a Null-terminated ASCII string in the output buffer
 370   specified by StartOfBuffer and BufferSize.
 371   The ASCII string is produced by parsing the format string specified by FormatString.
 372   Arguments are pulled from the variable argument list based on the contents of the format string.
 373   This function returns the number of ASCII characters in the output buffer,
 374   not including the Null-terminator.
 375   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 376
 377   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 378   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 379   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 380   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 381   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then ASSERT().
 382   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 383   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 384   Null-terminator, then ASSERT().
 385
 386   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 387                           ASCII string.
 388   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 389   @param  FormatString    Null-terminated Unicode format string.
 390   @param  ...             Variable argument list whose contents are accessed based on the
 391                           format string specified by FormatString.
 392
 393   @return The number of ASCII characters in the produced output buffer not including the
 394           Null-terminator.
 395
 396 **/
 397 typedef
 398 UINTN
 399 (EFIAPI *ASCII_S_PRINT_UNICODE_FORMAT)(
 400   OUT CHAR8         *StartOfBuffer,
 401   IN  UINTN         BufferSize,
 402   IN  CONST CHAR16  *FormatString,
 403   ...
 404   );
 405
 406 /**
 407   Converts a decimal value to a Null-terminated ASCII string.
 408
 409   Converts the decimal number specified by Value to a Null-terminated ASCII string
 410   specified by Buffer containing at most Width characters. No padding of spaces is ever performed.
 411   If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 412   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 413   If the conversion contains more than Width characters, then only the first Width
 414   characters are returned, and the total number of characters required to perform
 415   the conversion is returned.
 416   Additional conversion parameters are specified in Flags.
 417   The Flags bit LEFT_JUSTIFY is always ignored.
 418   All conversions are left justified in Buffer.
 419   If Width is 0, PREFIX_ZERO is ignored in Flags.
 420   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 421   are inserted every 3rd digit starting from the right.
 422   If RADIX_HEX is set in Flags, then the output buffer will be
 423   formatted in hexadecimal format.
 424   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 425   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 426   then Buffer is padded with '0' characters so the combination of the optional '-'
 427   sign character, '0' characters, digit characters for Value, and the Null-terminator
 428   add up to Width characters.
 429
 430   If Buffer is NULL, then ASSERT().
 431   If unsupported bits are set in Flags, then ASSERT().
 432   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 433   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 434
 435   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 436                   ASCII string.
 437   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 438   @param  Value   The 64-bit signed value to convert to a string.
 439   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 440                   the Null-terminator.
 441
 442   @return The number of ASCII characters in Buffer not including the Null-terminator.
 443
 444 **/
 445 typedef
 446 UINTN
 447 (EFIAPI *ASCII_VALUE_TO_STRING)(
 448   OUT CHAR8      *Buffer,
 449   IN  UINTN      Flags,
 450   IN  INT64      Value,
 451   IN  UINTN      Width
 452   );
 453
 454 struct _EFI_PRINT2_PROTOCOL {
 455   UNICODE_BS_PRINT                     UnicodeBSPrint;
 456   UNICODE_S_PRINT                      UnicodeSPrint;
 457   UNICODE_BS_PRINT_ASCII_FORMAT        UnicodeBSPrintAsciiFormat;
 458   UNICODE_S_PRINT_ASCII_FORMAT         UnicodeSPrintAsciiFormat;
 459   UNICODE_VALUE_TO_STRING              UnicodeValueToString;
 460   ASCII_BS_PRINT                       AsciiBSPrint;
 461   ASCII_S_PRINT                        AsciiSPrint;
 462   ASCII_BS_PRINT_UNICODE_FORMAT        AsciiBSPrintUnicodeFormat;
 463   ASCII_S_PRINT_UNICODE_FORMAT         AsciiSPrintUnicodeFormat;
 464   ASCII_VALUE_TO_STRING                AsciiValueToString;
 465 };
 466
 467 extern EFI_GUID gEfiPrint2ProtocolGuid;
 468
 469 #endif