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