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 - 2008, 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 *UNI_VSPRINT2)(
  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   ASCII format string and a VA_LIST 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 specified by Marker based on the
  79   contents of the format string.
  80   The number of Unicode characters in the produced output buffer is returned not including
  81   the Null-terminator.
  82   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  83
  84   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  85   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  86   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  87   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
  88   PcdMaximumAsciiStringLength ASCII 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 ASCII format string.
  98   @param  Marker          VA_LIST marker for the variable argument list.
  99
 100   @return The number of Unicode characters in the produced output buffer not including the
 101           Null-terminator.
 102
 103 **/
 104 typedef
 105 UINTN
 106 (EFIAPI *UNI_VSPRINT_ASCII)(
 107   OUT CHAR16       *StartOfBuffer,
 108   IN  UINTN        BufferSize,
 109   IN  CONST CHAR8  *FormatString,
 110   IN  VA_LIST      Marker
 111   );
 112
 113 /**
 114   Converts a decimal value to a Null-terminated Unicode string.
 115
 116   Converts the decimal number specified by Value to a Null-terminated Unicode
 117   string specified by Buffer containing at most Width characters. No padding of spaces
 118   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 119   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 120   If the conversion contains more than Width characters, then only the first
 121   Width characters are returned, and the total number of characters
 122   required to perform the conversion is returned.
 123   Additional conversion parameters are specified in Flags.
 124
 125   The Flags bit LEFT_JUSTIFY is always ignored.
 126   All conversions are left justified in Buffer.
 127   If Width is 0, PREFIX_ZERO is ignored in Flags.
 128   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 129   are inserted every 3rd digit starting from the right.
 130   If HEX_RADIX is set in Flags, then the output buffer will be
 131   formatted in hexadecimal format.
 132   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 133   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 134   then Buffer is padded with '0' characters so the combination of the optional '-'
 135   sign character, '0' characters, digit characters for Value, and the Null-terminator
 136   add up to Width characters.
 137   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 138   If Buffer is NULL, then ASSERT().
 139   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 140   If unsupported bits are set in Flags, then ASSERT().
 141   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 142   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 143
 144   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 145                   Unicode string.
 146   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 147   @param  Value   The 64-bit signed value to convert to a string.
 148   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 149                   the Null-terminator.
 150
 151   @return The number of Unicode characters in Buffer not including the Null-terminator.
 152
 153 **/
 154 typedef
 155 UINTN
 156 (EFIAPI *VALUE_TO_UNISTRING)(
 157   IN OUT CHAR16  *Buffer,
 158   IN UINTN       Flags,
 159   IN INT64       Value,
 160   IN UINTN       Width
 161   );
 162
 163 /**
 164   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 165   ASCII format string and a VA_LIST argument list.
 166
 167   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 168   and BufferSize.
 169   The ASCII string is produced by parsing the format string specified by FormatString.
 170   Arguments are pulled from the variable argument list specified by Marker based on
 171   the contents of the format string.
 172   The number of ASCII characters in the produced output buffer is returned not including
 173   the Null-terminator.
 174   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 175
 176   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 177   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 178   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 179   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 180   ASSERT().
 181   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 182   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 183   Null-terminator, then ASSERT().
 184
 185   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 186                           ASCII string.
 187   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 188   @param  FormatString    Null-terminated ASCII format string.
 189   @param  Marker          VA_LIST marker for the variable argument list.
 190
 191   @return The number of ASCII characters in the produced output buffer not including the
 192           Null-terminator.
 193
 194 **/
 195 typedef
 196 UINTN
 197 (EFIAPI *ASCII_VSPRINT)(
 198   OUT CHAR8         *StartOfBuffer,
 199   IN  UINTN         BufferSize,
 200   IN  CONST CHAR8   *FormatString,
 201   IN  VA_LIST       Marker
 202   );
 203
 204 /**
 205   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 206   Unicode format string and a VA_LIST argument list.
 207
 208   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 209   and BufferSize.
 210   The ASCII string is produced by parsing the format string specified by FormatString.
 211   Arguments are pulled from the variable argument list specified by Marker based on
 212   the contents of the format string.
 213   The number of ASCII characters in the produced output buffer is returned not including
 214   the Null-terminator.
 215   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 216
 217   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 218   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 219   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 220   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 221   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 222   ASSERT().
 223   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 224   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 225   Null-terminator, then ASSERT().
 226
 227   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 228                           ASCII string.
 229   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 230   @param  FormatString    Null-terminated Unicode format string.
 231   @param  Marker          VA_LIST marker for the variable argument list.
 232
 233   @return The number of ASCII characters in the produced output buffer not including the
 234           Null-terminator.
 235
 236 **/
 237 typedef
 238 UINTN
 239 (EFIAPI *ASCII_VSPRINT_UNI)(
 240   OUT CHAR8         *StartOfBuffer,
 241   IN  UINTN         BufferSize,
 242   IN  CONST CHAR16  *FormatString,
 243   IN  VA_LIST       Marker
 244   );
 245
 246 /**
 247   Converts a decimal value to a Null-terminated ASCII string.
 248
 249   Converts the decimal number specified by Value to a Null-terminated ASCII string
 250   specified by Buffer containing at most Width characters. No padding of spaces
 251   is ever performed.
 252   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 253   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 254   If the conversion contains more than Width characters, then only the first Width
 255   characters are returned, and the total number of characters required to perform
 256   the conversion is returned.
 257   Additional conversion parameters are specified in Flags.
 258   The Flags bit LEFT_JUSTIFY is always ignored.
 259   All conversions are left justified in Buffer.
 260   If Width is 0, PREFIX_ZERO is ignored in Flags.
 261   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 262   are inserted every 3rd digit starting from the right.
 263   If HEX_RADIX is set in Flags, then the output buffer will be
 264   formatted in hexadecimal format.
 265   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 266   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 267   then Buffer is padded with '0' characters so the combination of the optional '-'
 268   sign character, '0' characters, digit characters for Value, and the Null-terminator
 269   add up to Width characters.
 270
 271   If Buffer is NULL, then ASSERT().
 272   If unsupported bits are set in Flags, then ASSERT().
 273   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 274   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 275
 276   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 277                   ASCII string.
 278   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 279   @param  Value   The 64-bit signed value to convert to a string.
 280   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 281                   the Null-terminator.
 282
 283   @return The number of ASCII characters in Buffer not including the Null-terminator.
 284
 285 **/
 286 typedef
 287 UINTN
 288 (EFIAPI *VALUE_TO_ASCIISTRING)(
 289   IN OUT CHAR8  *Buffer,
 290   IN UINTN      Flags,
 291   IN INT64      Value,
 292   IN UINTN      Width
 293   );
 294
 295 struct _EFI_PRINT2_PROTOCOL {
 296   UNI_VSPRINT2              VSPrint;
 297   UNI_VSPRINT_ASCII         UniVSPrintAscii;
 298   VALUE_TO_UNISTRING        UniValueToString;
 299   ASCII_VSPRINT             AsciiVSPrint;
 300   ASCII_VSPRINT_UNI         AsciiVSPrintUni;
 301   VALUE_TO_ASCIISTRING      AsciiValueToString;
 302 };
 303
 304 extern EFI_GUID gEfiPrint2ProtocolGuid;
 305
 306 #endif