MdeModulePkg/Include/Protocol/Print.h

   1 /** @file
   2
   3   This file defines the Print protocol.
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __PPRINT_H__
  17 #define __PPRINT_H__
  18
  19 #define EFI_PRINT_PROTOCOL_GUID  \
  20    { 0x5bcc3dbc, 0x8c57, 0x450a, { 0xbb, 0xc, 0xa1, 0xc0, 0xbd, 0xde, 0x48, 0xc } }
  21
  22 //
  23 // Forward reference for pure ANSI compatability
  24 //
  25 typedef struct _EFI_PRINT_PROTOCOL  EFI_PRINT_PROTOCOL;
  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 number of Unicode characters in the produced output buffer is returned not including
  37   the Null-terminator.
  38   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  39
  40   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  41   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  42   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  43   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
  44   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  45   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
  46   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          VA_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 *UNI_VSPRINT) (
  64   OUT CHAR16        *StartOfBuffer,
  65   IN  UINTN         BufferSize,
  66   IN  CONST CHAR16  *FormatString,
  67   IN  VA_LIST       Marker
  68   );
  69
  70 /**
  71   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
  72   ASCII format string and a VA_LIST argument list
  73
  74   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  75   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 specified by Marker based on the
  78   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 PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
  87   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
  88   ASSERT().
  89   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  90   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  91   Null-terminator, then ASSERT().
  92
  93   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  94                           Unicode string.
  95   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  96   @param  FormatString    Null-terminated Unicode format string.
  97   @param  Marker          VA_LIST marker for the variable argument list.
  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 *UNI_VSPRINT_ASCII) (
 106   OUT CHAR16       *StartOfBuffer,
 107   IN  UINTN        BufferSize,
 108   IN  CONST CHAR8  *FormatString,
 109   IN  VA_LIST      Marker
 110   );
 111
 112 /**
 113   Converts a decimal value to a Null-terminated Unicode string.
 114
 115   Converts the decimal number specified by Value to a Null-terminated Unicode
 116   string specified by Buffer containing at most Width characters. No padding of spaces
 117   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 118   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 119   If the conversion contains more than Width characters, then only the first
 120   Width characters are returned, and the total number of characters
 121   required to perform the conversion is returned.
 122   Additional conversion parameters are specified in Flags.
 123
 124   The Flags bit LEFT_JUSTIFY is always ignored.
 125   All conversions are left justified in Buffer.
 126   If Width is 0, PREFIX_ZERO is ignored in Flags.
 127   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 128   are inserted every 3rd digit starting from the right.
 129   If HEX_RADIX is set in Flags, then the output buffer will be
 130   formatted in hexadecimal format.
 131   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 132   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 133   then Buffer is padded with '0' characters so the combination of the optional '-'
 134   sign character, '0' characters, digit characters for Value, and the Null-terminator
 135   add up to Width characters.
 136   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 137   If Buffer is NULL, then ASSERT().
 138   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 139   If unsupported bits are set in Flags, then ASSERT().
 140   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 141   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 142
 143   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 144                   Unicode string.
 145   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 146   @param  Value   The 64-bit signed value to convert to a string.
 147   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 148                   the Null-terminator.
 149
 150   @return The number of Unicode characters in Buffer not including the Null-terminator.
 151
 152 **/
 153 typedef
 154 UINTN
 155 (EFIAPI *VALUE_TO_UNISTRING) (
 156   IN OUT CHAR16  *Buffer,
 157   IN UINTN       Flags,
 158   IN INT64       Value,
 159   IN UINTN       Width
 160   );
 161
 162 /**
 163   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 164   ASCII format string and a VA_LIST argument list.
 165
 166   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 167   and BufferSize.
 168   The ASCII string is produced by parsing the format string specified by FormatString.
 169   Arguments are pulled from the variable argument list specified by Marker based on
 170   the contents of the format string.
 171   The number of ASCII characters in the produced output buffer is returned not including
 172   the Null-terminator.
 173   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 174
 175   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 176   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 177   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 178   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 179   ASSERT().
 180   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 181   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 182   Null-terminator, then ASSERT().
 183
 184   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 185                           ASCII string.
 186   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 187   @param  FormatString    Null-terminated Unicode format string.
 188   @param  Marker          VA_LIST marker for the variable argument list.
 189
 190   @return The number of ASCII characters in the produced output buffer not including the
 191           Null-terminator.
 192
 193 **/
 194 typedef
 195 UINTN
 196 (EFIAPI *ASCII_VSPRINT) (
 197   OUT CHAR8         *StartOfBuffer,
 198   IN  UINTN         BufferSize,
 199   IN  CONST CHAR8   *FormatString,
 200   IN  VA_LIST       Marker
 201   );
 202
 203 /**
 204   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 205   ASCII format string and a VA_LIST argument list.
 206
 207   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 208   and BufferSize.
 209   The ASCII string is produced by parsing the format string specified by FormatString.
 210   Arguments are pulled from the variable argument list specified by Marker based on
 211   the contents of the format string.
 212   The number of ASCII characters in the produced output buffer is returned not including
 213   the Null-terminator.
 214   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 215
 216   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 217   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 218   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 219   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 220   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 221   ASSERT().
 222   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 223   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 224   Null-terminator, then ASSERT().
 225
 226   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 227                           ASCII string.
 228   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 229   @param  FormatString    Null-terminated Unicode format string.
 230   @param  Marker          VA_LIST marker for the variable argument list.
 231
 232   @return The number of ASCII characters in the produced output buffer not including the
 233           Null-terminator.
 234
 235 **/
 236 typedef
 237 UINTN
 238 (EFIAPI *ASCII_VSPRINT_UNI) (
 239   OUT CHAR8         *StartOfBuffer,
 240   IN  UINTN         BufferSize,
 241   IN  CONST CHAR16  *FormatString,
 242   IN  VA_LIST       Marker
 243   );
 244
 245 /**
 246   Converts a decimal value to a Null-terminated ASCII string.
 247
 248   Converts the decimal number specified by Value to a Null-terminated ASCII string
 249   specified by Buffer containing at most Width characters. No padding of spaces
 250   is ever performed.
 251   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 252   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 253   If the conversion contains more than Width characters, then only the first Width
 254   characters are returned, and the total number of characters required to perform
 255   the conversion is returned.
 256   Additional conversion parameters are specified in Flags.
 257   The Flags bit LEFT_JUSTIFY is always ignored.
 258   All conversions are left justified in Buffer.
 259   If Width is 0, PREFIX_ZERO is ignored in Flags.
 260   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 261   are inserted every 3rd digit starting from the right.
 262   If HEX_RADIX is set in Flags, then the output buffer will be
 263   formatted in hexadecimal format.
 264   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 265   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 266   then Buffer is padded with '0' characters so the combination of the optional '-'
 267   sign character, '0' characters, digit characters for Value, and the Null-terminator
 268   add up to Width characters.
 269
 270   If Buffer is NULL, then ASSERT().
 271   If unsupported bits are set in Flags, then ASSERT().
 272   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 273   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 274
 275   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 276                   ASCII string.
 277   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 278   @param  Value   The 64-bit signed value to convert to a string.
 279   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 280                   the Null-terminator.
 281
 282   @return The number of ASCII characters in Buffer not including the Null-terminator.
 283
 284 **/
 285 typedef
 286 UINTN
 287 (EFIAPI *VALUE_TO_ASCIISTRING) (
 288   IN OUT CHAR8  *Buffer,
 289   IN UINTN      Flags,
 290   IN INT64      Value,
 291   IN UINTN      Width
 292   );
 293
 294 struct _EFI_PRINT_PROTOCOL {
 295   UNI_VSPRINT               VSPrint;
 296   UNI_VSPRINT_ASCII         UniVSPrintAscii;
 297   VALUE_TO_UNISTRING        UniValueToString;
 298   ASCII_VSPRINT             AsciiVSPrint;
 299   ASCII_VSPRINT_UNI         AsciiVSPrintUni;
 300   VALUE_TO_ASCIISTRING      AsciiValueToString;
 301 };
 302
 303 extern EFI_GUID gEfiPrintProtocolGuid;
 304
 305 #endif