Home | History | Annotate | Download | only in Protocol 
      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
    470