1 /** @file 2 Defines for EFI shell environment 2 ported to EDK II build environment. (no spec) 3 4 Copyright (c) 2005 - 2010, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 16 #ifndef _SHELL_ENVIRONMENT_2_PROTOCOL_H_ 17 #define _SHELL_ENVIRONMENT_2_PROTOCOL_H_ 18 19 #define DEFAULT_INIT_ROW 1 20 #define DEFAULT_AUTO_LF FALSE 21 22 /** 23 This function is a prototype for a function that dumps information on a protocol 24 to a given location. The location is dependant on the implementation. This is 25 used when programatically adding shell commands. 26 27 @param[in] Handle The handle the protocol is on. 28 @param[in] Interface The interface to the protocol. 29 30 **/ 31 typedef 32 VOID 33 (EFIAPI *SHELLENV_DUMP_PROTOCOL_INFO) ( 34 IN EFI_HANDLE Handle, 35 IN VOID *Interface 36 ); 37 38 /** 39 This function is a prototype for each command internal to the EFI shell 40 implementation. The specific command depends on the implementation. This is 41 used when programatically adding shell commands. 42 43 @param[in] ImageHandle The handle to the binary shell. 44 @param[in] SystemTable The pointer to the system table. 45 46 @retval EFI_SUCCESS The command completed. 47 @retval other An error occurred. Any error is possible 48 depending on the implementation of the shell 49 command. 50 51 **/ 52 typedef 53 EFI_STATUS 54 (EFIAPI *SHELLENV_INTERNAL_COMMAND) ( 55 IN EFI_HANDLE ImageHandle, 56 IN EFI_SYSTEM_TABLE *SystemTable 57 ); 58 59 /** 60 This function is a prototype for one that gets a help string for a given command. 61 This is used when programatically adding shell commands. Upon successful return 62 the memory allocated is up to the caller to free. 63 64 @param[in, out] Str Pointer to pointer to string to display for help. 65 66 @retval EFI_SUCCESS The help string is in the parameter Str. 67 68 **/ 69 typedef 70 EFI_STATUS 71 (EFIAPI *SHELLCMD_GET_LINE_HELP) ( 72 IN OUT CHAR16 **Str 73 ); 74 75 /** 76 Structure returned from functions that open multiple files. 77 **/ 78 typedef struct { 79 UINT32 Signature; ///< SHELL_FILE_ARG_SIGNATURE. 80 LIST_ENTRY Link; ///< Linked list helper. 81 EFI_STATUS Status; ///< File's status. 82 83 EFI_FILE_HANDLE Parent; ///< What is the Parent file of this file. 84 UINT64 OpenMode; ///< How was the file opened. 85 CHAR16 *ParentName; ///< String representation of parent. 86 EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath; ///< DevicePath for Parent. 87 88 CHAR16 *FullName; ///< Path and file name for this file. 89 CHAR16 *FileName; ///< File name for this file. 90 91 EFI_FILE_HANDLE Handle; ///< Handle to this file. 92 EFI_FILE_INFO *Info; ///< Pointer to file info for this file. 93 } SHELL_FILE_ARG; 94 95 /// Signature for SHELL_FILE_ARG. 96 #define SHELL_FILE_ARG_SIGNATURE SIGNATURE_32 ('g', 'r', 'a', 'f') 97 98 /** 99 GUID for the shell environment2 and shell environment. 100 **/ 101 #define SHELL_ENVIRONMENT_PROTOCOL_GUID \ 102 { \ 103 0x47c7b221, 0xc42a, 0x11d2, {0x8e, 0x57, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b} \ 104 } 105 106 /** 107 GUID for the shell environment2 extension (main GUID above). 108 **/ 109 #define EFI_SE_EXT_SIGNATURE_GUID \ 110 { \ 111 0xd2c18636, 0x40e5, 0x4eb5, {0xa3, 0x1b, 0x36, 0x69, 0x5f, 0xd4, 0x2c, 0x87} \ 112 } 113 114 #define EFI_SHELL_MAJOR_VER 0x00000001 ///< Major version of the EFI_SHELL_ENVIRONMENT2. 115 #define EFI_SHELL_MINOR_VER 0x00000000 ///< Minor version of the EFI_SHELL_ENVIRONMENT2. 116 117 /** 118 Execute a command line. 119 120 This function will run the CommandLine. This includes loading any required images, 121 parsing any requires scripts, and if DebugOutput is TRUE printing errors 122 encountered directly to the screen. 123 124 @param[in] ParentImageHandle Handle of the image executing this operation. 125 @param[in] CommandLine The string command line to execute. 126 @param[in] DebugOutput TRUE indicates that errors should be printed directly. 127 FALSE supresses error messages. 128 129 @retval EFI_SUCCESS The command line executed and completed. 130 @retval EFI_ABORTED The operation aborted. 131 @retval EFI_INVALID_PARAMETER A parameter did not have a valid value. 132 @retval EFI_OUT_OF_RESOURCES A required memory allocation failed. 133 134 @sa HandleProtocol 135 **/ 136 typedef 137 EFI_STATUS 138 (EFIAPI *SHELLENV_EXECUTE) ( 139 IN EFI_HANDLE *ParentImageHandle, 140 IN CHAR16 *CommandLine, 141 IN BOOLEAN DebugOutput 142 ); 143 144 /** 145 This function returns a shell environment variable value. 146 147 @param[in] Name The pointer to the string with the shell environment 148 variable name. 149 150 @retval NULL The shell environment variable's value could not be found. 151 @retval !=NULL The value of the shell environment variable Name. 152 153 **/ 154 typedef 155 CHAR16 * 156 (EFIAPI *SHELLENV_GET_ENV) ( 157 IN CHAR16 *Name 158 ); 159 160 /** 161 This function returns a shell environment map value. 162 163 @param[in] Name The pointer to the string with the shell environment 164 map name. 165 166 @retval NULL The shell environment map's value could not be found. 167 @retval !=NULL The value of the shell environment map Name. 168 169 **/ 170 typedef 171 CHAR16 * 172 (EFIAPI *SHELLENV_GET_MAP) ( 173 IN CHAR16 *Name 174 ); 175 176 /** 177 This function will add an internal command to the shell interface. 178 179 This will allocate all required memory, put the new command on the command 180 list in the correct location. 181 182 @param[in] Handler The handler function to call when the command gets called. 183 @param[in] Cmd The command name. 184 @param[in] GetLineHelp The function to call of type "get help" for this command. 185 186 @retval EFI_SUCCESS The command is now part of the command list. 187 @retval EFI_OUT_OF_RESOURCES A memory allocation failed. 188 @sa SHELLENV_INTERNAL_COMMAND 189 @sa SHELLCMD_GET_LINE_HELP 190 **/ 191 typedef 192 EFI_STATUS 193 (EFIAPI *SHELLENV_ADD_CMD) ( 194 IN SHELLENV_INTERNAL_COMMAND Handler, 195 IN CHAR16 *Cmd, 196 IN SHELLCMD_GET_LINE_HELP GetLineHelp 197 ); 198 199 /** 200 Internal interface to add protocol handlers. 201 202 This function is for internal shell use only. This is how protocol handlers are added. 203 This will get the current protocol info and add the new info or update existing info 204 and then resave the info. 205 206 @param[in] Protocol The pointer to the protocol's GUID. 207 @param[in] DumpToken The function pointer to dump token function or 208 NULL. 209 @param[in] DumpInfo The function pointer to dump infomation function 210 or NULL. 211 @param[in] IdString The English name of the protocol. 212 **/ 213 typedef 214 VOID 215 (EFIAPI *SHELLENV_ADD_PROT) ( 216 IN EFI_GUID *Protocol, 217 IN SHELLENV_DUMP_PROTOCOL_INFO DumpToken OPTIONAL, 218 IN SHELLENV_DUMP_PROTOCOL_INFO DumpInfo OPTIONAL, 219 IN CHAR16 *IdString 220 ); 221 222 /** 223 This function finds a protocol handle by a GUID. 224 225 This function will check for already known protocols by GUID and if one is 226 found it will return the name of that protocol. If no name is found and 227 GenId is TRUE it will generate ths string. 228 229 @param[in] Protocol The GUID of the protocol to look for. 230 @param[in] GenId Whether to generate a name string if it is not found. 231 232 @return !NULL The Name of the protocol. 233 @retval NULL The Name was not found, and GenId was not TRUE. 234 **/ 235 typedef 236 CHAR16* 237 (EFIAPI *SHELLENV_GET_PROT) ( 238 IN EFI_GUID *Protocol, 239 IN BOOLEAN GenId 240 ); 241 242 /** 243 This function returns a string array containing the current directory on 244 a given device. 245 246 If DeviceName is specified, then return the current shell directory on that 247 device. If DeviceName is NULL, then return the current directory on the 248 current device. The caller us responsible to free the returned string when 249 no longer required. 250 251 @param[in] DeviceName The name of the device to get the current 252 directory on, or NULL for current device. 253 254 @return String array with the current directory on the current or specified device. 255 256 **/ 257 typedef 258 CHAR16* 259 (EFIAPI *SHELLENV_CUR_DIR) ( 260 IN CHAR16 *DeviceName OPTIONAL 261 ); 262 263 /** 264 This function will open a group of files that match the Arg path, including 265 support for wildcard characters ('?' and '*') in the Arg path. If there are 266 any wildcard characters in the path this function will find any and all files 267 that match the wildcards. It returns a double linked list based on the 268 LIST_ENTRY linked list structure. Use this in conjunction with the 269 SHELL_FILE_ARG_SIGNATURE to get the SHELL_FILE_ARG structures that are returned. 270 The memory allocated by the callee for this list is freed by making a call to 271 SHELLENV_FREE_FILE_LIST. 272 273 @param[in] Arg The pointer Path to files to open. 274 @param[in, out] ListHead The pointer to the allocated and initialized list head 275 upon which to append all opened file structures. 276 277 @retval EFI_SUCCESS One or more files was opened and a struct of each file's 278 information was appended to ListHead. 279 @retval EFI_OUT_OF_RESOURCES A memory allocation failed. 280 @retval EFI_NOT_FOUND No matching files could be found. 281 @sa SHELLENV_FREE_FILE_LIST 282 **/typedef 283 EFI_STATUS 284 (EFIAPI *SHELLENV_FILE_META_ARG) ( 285 IN CHAR16 *Arg, 286 IN OUT LIST_ENTRY *ListHead 287 ); 288 289 /** 290 This frees all of the nodes under the ListHead, but not ListHead itself. 291 292 @param[in, out] ListHead Pointer to list to free all nodes of. 293 294 @retval EFI_SUCCESS This function always returns EFI_SUCCESS. 295 **/ 296 typedef 297 EFI_STATUS 298 (EFIAPI *SHELLENV_FREE_FILE_LIST) ( 299 IN OUT LIST_ENTRY *ListHead 300 ); 301 302 /** 303 This function creates a new instance of the ShellInterface protocol for use on 304 the ImageHandle. 305 306 This function is for internal shell usage. This will allocate and then populate 307 EFI_SHELL_INTERFACE protocol. It is the caller's responsibility to free the 308 memory. 309 310 @param[in] ImageHandle The handle which will use the new ShellInterface 311 protocol. 312 313 @return The newly allocated shell interface protocol. 314 315 **/ 316 typedef 317 EFI_SHELL_INTERFACE* 318 (EFIAPI *SHELLENV_NEW_SHELL) ( 319 IN EFI_HANDLE ImageHandle 320 ); 321 322 /** 323 This function determines whether a script file is currently being processed. 324 325 A script file (.nsh file) can contain a series of commands and this is useful to 326 know for some shell commands whether they are being run manually or as part of a 327 script. 328 329 @retval TRUE A script file is being processed. 330 @retval FALSE A script file is not being processed. 331 **/ 332 typedef 333 BOOLEAN 334 (EFIAPI *SHELLENV_BATCH_IS_ACTIVE) ( 335 VOID 336 ); 337 338 /** 339 This is an internal shell function to free any and all allocated resources. 340 This should be called immediately prior to closing the shell. 341 **/ 342 typedef 343 VOID 344 (EFIAPI *SHELLENV_FREE_RESOURCES) ( 345 VOID 346 ); 347 348 /** 349 This function enables the page break mode. 350 351 This mode causes the output to pause after each complete screen to enable a 352 user to more easily read it. If AutoWrap is TRUE, then rows with too many 353 characters will be chopped and divided into 2 rows. If FALSE, then rows with 354 too many characters may not be fully visible to the user on the screen. 355 356 @param[in] StartRow The row number to start this on. 357 @param[in] AutoWrap Whether to auto wrap rows that are too long. 358 **/ 359 typedef 360 VOID 361 (EFIAPI *SHELLENV_ENABLE_PAGE_BREAK) ( 362 IN INT32 StartRow, 363 IN BOOLEAN AutoWrap 364 ); 365 366 /** 367 This function disables the page break mode. 368 369 Disabling this causes the output to print out exactly as coded, with no breaks 370 for readability. 371 **/ 372 typedef 373 VOID 374 (EFIAPI *SHELLENV_DISABLE_PAGE_BREAK) ( 375 VOID 376 ); 377 378 /** 379 Get the status of the page break output mode. 380 381 @retval FALSE Page break output mode is not enabled. 382 @retval TRUE Page break output mode is enabled. 383 **/ 384 typedef 385 BOOLEAN 386 (EFIAPI *SHELLENV_GET_PAGE_BREAK) ( 387 VOID 388 ); 389 390 /** 391 This function sets the keys to filter for for the console in. The valid 392 values to set are: 393 394 #define EFI_OUTPUT_SCROLL 0x00000001 395 #define EFI_OUTPUT_PAUSE 0x00000002 396 #define EFI_EXECUTION_BREAK 0x00000004 397 398 @param[in] KeyFilter The new key filter to use. 399 **/ 400 typedef 401 VOID 402 (EFIAPI *SHELLENV_SET_KEY_FILTER) ( 403 IN UINT32 KeyFilter 404 ); 405 406 /** 407 This function gets the keys to filter for for the console in. 408 409 The valid values to get are: 410 #define EFI_OUTPUT_SCROLL 0x00000001 411 #define EFI_OUTPUT_PAUSE 0x00000002 412 #define EFI_EXECUTION_BREAK 0x00000004 413 414 @retval The current filter mask. 415 **/ 416 typedef 417 UINT32 418 (EFIAPI *SHELLENV_GET_KEY_FILTER) ( 419 VOID 420 ); 421 422 /** 423 This function determines if the shell application should break. 424 425 This is used to inform a shell application that a break condition has been 426 initiated. Long loops should check this to prevent delays to the break. 427 428 @retval TRUE A break has been signaled. The application 429 should exit with EFI_ABORTED as soon as possible. 430 @retval FALSE Continue as normal. 431 **/ 432 typedef 433 BOOLEAN 434 (EFIAPI *SHELLENV_GET_EXECUTION_BREAK) ( 435 VOID 436 ); 437 438 /** 439 This is an internal shell function used to increment the shell nesting level. 440 441 **/ 442 typedef 443 VOID 444 (EFIAPI *SHELLENV_INCREMENT_SHELL_NESTING_LEVEL) ( 445 VOID 446 ); 447 448 /** 449 This is an internal shell function used to decrement the shell nesting level. 450 **/ 451 typedef 452 VOID 453 (EFIAPI *SHELLENV_DECREMENT_SHELL_NESTING_LEVEL) ( 454 VOID 455 ); 456 457 /** 458 This function determines if the caller is running under the root shell. 459 460 @retval TRUE The caller is running under the root shell. 461 @retval FALSE The caller is not running under the root shell. 462 463 **/ 464 typedef 465 BOOLEAN 466 (EFIAPI *SHELLENV_IS_ROOT_SHELL) ( 467 VOID 468 ); 469 470 /** 471 Close the console proxy to restore the original console. 472 473 This is an internal shell function to handle shell cascading. It restores the 474 original set of console protocols. 475 476 @param[in] ConInHandle The handle of ConIn. 477 @param[in, out] ConIn The pointer to the location to return the pointer to 478 the original console input. 479 @param[in] ConOutHandle The handle of ConOut 480 @param[in, out] ConOut The pointer to the location to return the pointer to 481 the original console output. 482 **/ 483 typedef 484 VOID 485 (EFIAPI *SHELLENV_CLOSE_CONSOLE_PROXY) ( 486 IN EFI_HANDLE ConInHandle, 487 IN OUT EFI_SIMPLE_TEXT_INPUT_PROTOCOL **ConIn, 488 IN EFI_HANDLE ConOutHandle, 489 IN OUT EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL **ConOut 490 ); 491 492 // 493 // declarations of handle enumerator 494 // 495 /** 496 For ease of use the shell maps handle #'s to short numbers. 497 This is only done on request for various internal commands and the references 498 are immediately freed when the internal command completes. 499 **/ 500 typedef 501 VOID 502 (EFIAPI *INIT_HANDLE_ENUMERATOR) ( 503 VOID 504 ); 505 506 /** 507 This is an internal shell function to enumerate the handle database. 508 509 This function gets the next handle in the handle database. If no handles are 510 found, EFI_NOT_FOUND is returned. If the previous Handle was the last handle, 511 it is set to NULL before returning. 512 513 This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. 514 515 @param[in, out] Handle The pointer to pointer to Handle. It is set 516 on a sucessful return. 517 518 @retval EFI_SUCCESS The next handle in the handle database is *Handle. 519 @retval EFI_NOT_FOUND There is not another handle. 520 **/ 521 typedef 522 EFI_STATUS 523 (EFIAPI *NEXT_HANDLE) ( 524 IN OUT EFI_HANDLE **Handle 525 ); 526 527 /** 528 This is an internal shell function to enumerate the handle database. 529 530 This function skips the next SkipNum handles in the handle database. If there 531 are not enough handles left to skip that many EFI_ACCESS_DENIED is returned and 532 no skip is performed. 533 534 This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. 535 536 @param[in] SkipNum How many handles to skip 537 538 @retval EFI_SUCCESS The next handle in the handle database is *Handle 539 @retval EFI_ACCESS_DENIED There are not SkipNum handles left in the database 540 **/ 541 typedef 542 EFI_STATUS 543 (EFIAPI *SKIP_HANDLE) ( 544 IN UINTN SkipNum 545 ); 546 547 /** 548 This is an internal shell function to enumerate the handle database. 549 550 This function resets the the handle database so that NEXT_HANDLE and SKIP_HANDLE 551 will start from EnumIndex on the next call. 552 553 This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. 554 555 @param[in] EnumIndex Where to start. 556 557 @return The number of handles either read out or skipped before this reset. 558 **/ 559 typedef 560 UINTN 561 (EFIAPI *RESET_HANDLE_ENUMERATOR) ( 562 IN UINTN EnumIndex 563 ); 564 565 /** 566 This is an internal shell function to enumerate the handle database. 567 568 This must be called after INIT_HANDLE_ENUMERATOR. 569 570 This function releases all memory and resources associated with the handle database. 571 After this no other handle enumerator functions except INIT_HANDLE_ENUMERATOR will 572 function properly. 573 **/ 574 typedef 575 VOID 576 (EFIAPI *CLOSE_HANDLE_ENUMERATOR) ( 577 VOID 578 ); 579 580 /** 581 This is an internal shell function to enumerate the handle database. 582 583 This function returns the number of handles in the handle database. 584 585 This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. 586 587 @return The number of handles in the handle database. 588 **/ 589 typedef 590 UINTN 591 (EFIAPI *GET_NUM) ( 592 VOID 593 ); 594 595 /** 596 Handle Enumerator structure. 597 **/ 598 typedef struct { 599 INIT_HANDLE_ENUMERATOR Init; ///< The pointer to INIT_HANDLE_ENUMERATOR function. 600 NEXT_HANDLE Next; ///< The pointer to NEXT_HANDLE function. 601 SKIP_HANDLE Skip; ///< The pointer to SKIP_HANDLE function. 602 RESET_HANDLE_ENUMERATOR Reset; ///< The pointer to RESET_HANDLE_ENUMERATOR function. 603 CLOSE_HANDLE_ENUMERATOR Close; ///< The pointer to CLOSE_HANDLE_ENUMERATOR function. 604 GET_NUM GetNum; ///< The pointer to GET_NUM function. 605 } HANDLE_ENUMERATOR; 606 607 /** 608 Signature for the PROTOCOL_INFO structure. 609 **/ 610 #define PROTOCOL_INFO_SIGNATURE SIGNATURE_32 ('s', 'p', 'i', 'n') 611 612 /** 613 PROTOCOL_INFO structure for protocol enumerator functions. 614 **/ 615 typedef struct { 616 UINTN Signature; ///< PROTOCOL_INFO_SIGNATURE. 617 LIST_ENTRY Link; ///< Standard linked list helper member. 618 // 619 // The parsing info for the protocol. 620 // 621 EFI_GUID ProtocolId; ///< The GUID for the protocol. 622 CHAR16 *IdString; ///< The name of the protocol. 623 SHELLENV_DUMP_PROTOCOL_INFO DumpToken; ///< The pointer to DumpToken function for the protocol. 624 SHELLENV_DUMP_PROTOCOL_INFO DumpInfo; ///< The pointer to DumpInfo function for the protocol. 625 // 626 // Patabase info on which handles are supporting this protocol. 627 // 628 UINTN NoHandles; ///< The number of handles producing this protocol. 629 EFI_HANDLE *Handles; ///< The array of handles. 630 631 } PROTOCOL_INFO; 632 633 // 634 // Declarations of protocol info enumerator. 635 // 636 /** 637 This is an internal shell function to initialize the protocol enumerator. 638 639 This must be called before NEXT_PROTOCOL_INFO, SKIP_PROTOCOL_INFO, 640 RESET_PROTOCOL_INFO_ENUMERATOR, and CLOSE_PROTOCOL_INFO_ENUMERATOR are 641 called. 642 **/ 643 typedef 644 VOID 645 (EFIAPI *INIT_PROTOCOL_INFO_ENUMERATOR) ( 646 VOID 647 ); 648 649 /** 650 This function is an internal shell function for enumeration of protocols. 651 652 This function returns the next protocol on the list. If this is called 653 immediately after initialization, it will return the first protocol on the list. 654 If this is called immediately after reset, it will return the first protocol again. 655 656 This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be 657 called after INIT_PROTOCOL_INFO_ENUMERATOR. 658 659 @param[in, out] ProtocolInfo The pointer to pointer to protocol information structure. 660 661 @retval EFI_SUCCESS The next protocol's information was sucessfully returned. 662 @retval NULL There are no more protocols. 663 **/ 664 typedef 665 EFI_STATUS 666 (EFIAPI *NEXT_PROTOCOL_INFO) ( 667 IN OUT PROTOCOL_INFO **ProtocolInfo 668 ); 669 670 /** 671 This function is an internal shell function for enumeration of protocols. 672 673 This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be 674 called after INIT_PROTOCOL_INFO_ENUMERATOR. 675 676 This function does nothing and always returns EFI_SUCCESS. 677 678 @retval EFI_SUCCESS Always returned (see above). 679 **/ 680 typedef 681 EFI_STATUS 682 (EFIAPI *SKIP_PROTOCOL_INFO) ( 683 IN UINTN SkipNum 684 ); 685 686 /** 687 This function is an internal shell function for enumeration of protocols. 688 689 This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be 690 called after INIT_PROTOCOL_INFO_ENUMERATOR. 691 692 This function resets the list of protocols such that the next one in the 693 list is the begining of the list. 694 **/ 695 typedef 696 VOID 697 (EFIAPI *RESET_PROTOCOL_INFO_ENUMERATOR) ( 698 VOID 699 ); 700 701 702 /** 703 This function is an internal shell function for enumeration of protocols. 704 705 This must be called after INIT_PROTOCOL_INFO_ENUMERATOR. After this call 706 no protocol enumerator calls except INIT_PROTOCOL_INFO_ENUMERATOR may be made. 707 708 This function frees any memory or resources associated with the protocol 709 enumerator. 710 **/ 711 typedef 712 VOID 713 (EFIAPI *CLOSE_PROTOCOL_INFO_ENUMERATOR) ( 714 VOID 715 ); 716 717 /** 718 Protocol enumerator structure of function pointers. 719 **/ 720 typedef struct { 721 INIT_PROTOCOL_INFO_ENUMERATOR Init; ///< The pointer to INIT_PROTOCOL_INFO_ENUMERATOR function. 722 NEXT_PROTOCOL_INFO Next; ///< The pointer to NEXT_PROTOCOL_INFO function. 723 SKIP_PROTOCOL_INFO Skip; ///< The pointer to SKIP_PROTOCOL_INFO function. 724 RESET_PROTOCOL_INFO_ENUMERATOR Reset; ///< The pointer to RESET_PROTOCOL_INFO_ENUMERATOR function. 725 CLOSE_PROTOCOL_INFO_ENUMERATOR Close; ///< The pointer to CLOSE_PROTOCOL_INFO_ENUMERATOR function. 726 } PROTOCOL_INFO_ENUMERATOR; 727 728 /** 729 This function is used to retrieve a user-friendly display name for a handle. 730 731 If UseComponentName is TRUE then the component name protocol for this device 732 or it's parent device (if required) will be used to obtain the name of the 733 device. If UseDevicePath is TRUE it will get the human readable device path 734 and return that. If both are TRUE it will try to use component name first 735 and device path if that fails. 736 737 It will use either ComponentName or ComponentName2 protocol, depending on 738 what is present. 739 740 This function will furthur verify whether the handle in question produced either 741 EFI_DRIVER_CONFIGRATION_PROTOCOL or EFI_DRIVER_CONFIGURATION2_PROTOCOL and also 742 whether the handle in question produced either EFI_DRIVER_DIAGNOSTICS_PROTOCOL or 743 EFI_DRIVER_DIAGNOSTICS2_PROTOCOL. 744 745 Upon successful return, the memory for *BestDeviceName is up to the caller to free. 746 747 @param[in] DeviceHandle The device handle whose name is desired. 748 @param[in] UseComponentName Whether to use the ComponentName protocol at all. 749 @param[in] UseDevicePath Whether to use the DevicePath protocol at all. 750 @param[in] Language The pointer to the language string to use. 751 @param[in, out] BestDeviceName The pointer to pointer to string allocated with the name. 752 @param[out] ConfigurationStatus The pointer to status for opening a Configuration protocol. 753 @param[out] DiagnosticsStatus The pointer to status for opening a Diagnostics protocol. 754 @param[in] Display Whether to Print this out to default Print location. 755 @param[in] Indent How many characters to indent the printing. 756 757 @retval EFI_SUCCESS This function always returns EFI_SUCCESS. 758 **/ 759 typedef 760 EFI_STATUS 761 (EFIAPI *GET_DEVICE_NAME) ( 762 IN EFI_HANDLE DeviceHandle, 763 IN BOOLEAN UseComponentName, 764 IN BOOLEAN UseDevicePath, 765 IN CHAR8 *Language, 766 IN OUT CHAR16 **BestDeviceName, 767 OUT EFI_STATUS *ConfigurationStatus, 768 OUT EFI_STATUS *DiagnosticsStatus, 769 IN BOOLEAN Display, 770 IN UINTN Indent 771 ); 772 773 #define EFI_SHELL_COMPATIBLE_MODE_VER L"1.1.1" ///< The string for lowest version this shell supports. 774 #define EFI_SHELL_ENHANCED_MODE_VER L"1.1.2" ///< The string for highest version this shell supports. 775 776 /** 777 This function gets the shell mode as stored in the shell environment 778 "efishellmode". It will not fail. 779 780 @param[out] Mode Returns a string representing one of the 781 2 supported modes of the shell. 782 783 @retval EFI_SUCCESS This function always returns success. 784 **/ 785 typedef 786 EFI_STATUS 787 (EFIAPI *GET_SHELL_MODE) ( 788 OUT CHAR16 **Mode 789 ); 790 791 /** 792 Convert a file system style name to a device path. 793 794 This function will convert a shell path name to a Device Path Protocol path. 795 This function will allocate any required memory for this operation and it 796 is the responsibility of the caller to free that memory when no longer required. 797 798 If anything prevents the complete conversion free any allocated memory and 799 return NULL. 800 801 @param[in] Path The path to convert. 802 803 @retval !NULL A pointer to the callee allocated Device Path. 804 @retval NULL The operation could not be completed. 805 **/ 806 typedef 807 EFI_DEVICE_PATH_PROTOCOL* 808 (EFIAPI *SHELLENV_NAME_TO_PATH) ( 809 IN CHAR16 *Path 810 ); 811 812 /** 813 Converts a device path into a file system map name. 814 815 If DevPath is NULL, then ASSERT. 816 817 This function looks through the shell environment map for a map whose device 818 path matches the DevPath parameter. If one is found the Name is returned via 819 Name parameter. If sucessful the caller must free the memory allocated for 820 Name. 821 822 This function will use the internal lock to prevent changes to the map during 823 the lookup operation. 824 825 @param[in] DevPath The device path to search for a name for. 826 @param[in] ConsistMapping What state to verify map flag VAR_ID_CONSIST. 827 @param[out] Name On sucessful return the name of that device path. 828 829 @retval EFI_SUCCESS The DevPath was found and the name returned 830 in Name. 831 @retval EFI_OUT_OF_RESOURCES A required memory allocation failed. 832 @retval EFI_UNSUPPORTED The DevPath was not found in the map. 833 **/ 834 typedef 835 EFI_STATUS 836 (EFIAPI *SHELLENV_GET_FS_NAME) ( 837 IN EFI_DEVICE_PATH_PROTOCOL * DevPath, 838 IN BOOLEAN ConsistMapping, 839 OUT CHAR16 **Name 840 ); 841 842 /** 843 This function will open a group of files that match the Arg path, but will not 844 support the wildcard characters ('?' and '*') in the Arg path. If there are 845 any wildcard characters in the path this function will return 846 EFI_INVALID_PARAMETER. The return is a double linked list based on the 847 LIST_ENTRY linked list structure. Use this in conjunction with the 848 SHELL_FILE_ARG_SIGNATURE to get the SHELL_FILE_ARG structures that are returned. 849 The memory allocated by the callee for this list is freed by making a call to 850 SHELLENV_FREE_FILE_LIST. 851 852 @param[in] Arg The pointer to the path of the files to be opened. 853 @param[in, out] ListHead The pointer to allocated and initialized list head 854 upon which to append all the opened file structures. 855 856 @retval EFI_SUCCESS One or more files was opened and a struct of each file's 857 information was appended to ListHead. 858 @retval EFI_OUT_OF_RESOURCES A memory allocation failed. 859 @retval EFI_NOT_FOUND No matching files could be found. 860 @sa SHELLENV_FREE_FILE_LIST 861 **/ 862 typedef 863 EFI_STATUS 864 (EFIAPI *SHELLENV_FILE_META_ARG_NO_WILDCARD) ( 865 IN CHAR16 *Arg, 866 IN OUT LIST_ENTRY *ListHead 867 ); 868 869 /** 870 This function removes duplicate file listings from lists. 871 872 This is a function for use with SHELLENV_FILE_META_ARG_NO_WILDCARD and 873 SHELLENV_FILE_META_ARG. This function will verify that there are no duplicate 874 files in the list of returned files. Any file listed twice will have one of its 875 instances removed. 876 877 @param[in] ListHead The pointer to linked list head that was returned from 878 SHELLENV_FILE_META_ARG_NO_WILDCARD or 879 SHELLENV_FILE_META_ARG. 880 881 @retval EFI_SUCCESS This function always returns success. 882 883 **/ 884 typedef 885 EFI_STATUS 886 (EFIAPI *SHELLENV_DEL_DUP_FILE) ( 887 IN LIST_ENTRY * ListHead 888 ); 889 890 /** 891 Converts a File System map name to a device path. 892 893 If DevPath is NULL, then ASSERT(). 894 895 This function looks through the shell environment map for a map whose Name 896 matches the Name parameter. If one is found, the device path pointer is 897 updated to point to that file systems device path. The caller should not 898 free the memory from that device path. 899 900 This function will use the internal lock to prevent changes to the map during 901 the lookup operation. 902 903 @param[in] Name The pointer to the NULL terminated UNICODE string of the 904 file system name. 905 @param[out] DevPath The pointer to pointer to DevicePath. Only valid on 906 successful return. 907 908 @retval EFI_SUCCESS The conversion was successful, and the device 909 path was returned. 910 @retval EFI_NOT_FOUND The file system could not be found in the map. 911 **/ 912 typedef 913 EFI_STATUS 914 (EFIAPI *SHELLENV_GET_FS_DEVICE_PATH) ( 915 IN CHAR16 *Name, 916 OUT EFI_DEVICE_PATH_PROTOCOL **DevPath 917 ); 918 919 /// EFI_SHELL_ENVIRONMENT2 protocol structure. 920 typedef struct { 921 SHELLENV_EXECUTE Execute; 922 SHELLENV_GET_ENV GetEnv; 923 SHELLENV_GET_MAP GetMap; 924 SHELLENV_ADD_CMD AddCmd; 925 SHELLENV_ADD_PROT AddProt; 926 SHELLENV_GET_PROT GetProt; 927 SHELLENV_CUR_DIR CurDir; 928 SHELLENV_FILE_META_ARG FileMetaArg; 929 SHELLENV_FREE_FILE_LIST FreeFileList; 930 931 // 932 // The following services are only used by the shell itself. 933 // 934 SHELLENV_NEW_SHELL NewShell; 935 SHELLENV_BATCH_IS_ACTIVE BatchIsActive; 936 937 SHELLENV_FREE_RESOURCES FreeResources; 938 939 // 940 // GUID to differentiate ShellEnvironment2 from ShellEnvironment. 941 // 942 EFI_GUID SESGuid; 943 // 944 // Major Version grows if shell environment interface has been changes. 945 // 946 UINT32 MajorVersion; 947 UINT32 MinorVersion; 948 SHELLENV_ENABLE_PAGE_BREAK EnablePageBreak; 949 SHELLENV_DISABLE_PAGE_BREAK DisablePageBreak; 950 SHELLENV_GET_PAGE_BREAK GetPageBreak; 951 952 SHELLENV_SET_KEY_FILTER SetKeyFilter; 953 SHELLENV_GET_KEY_FILTER GetKeyFilter; 954 955 SHELLENV_GET_EXECUTION_BREAK GetExecutionBreak; 956 SHELLENV_INCREMENT_SHELL_NESTING_LEVEL IncrementShellNestingLevel; 957 SHELLENV_DECREMENT_SHELL_NESTING_LEVEL DecrementShellNestingLevel; 958 SHELLENV_IS_ROOT_SHELL IsRootShell; 959 960 SHELLENV_CLOSE_CONSOLE_PROXY CloseConsoleProxy; 961 HANDLE_ENUMERATOR HandleEnumerator; 962 PROTOCOL_INFO_ENUMERATOR ProtocolInfoEnumerator; 963 GET_DEVICE_NAME GetDeviceName; 964 GET_SHELL_MODE GetShellMode; 965 SHELLENV_NAME_TO_PATH NameToPath; 966 SHELLENV_GET_FS_NAME GetFsName; 967 SHELLENV_FILE_META_ARG_NO_WILDCARD FileMetaArgNoWildCard; 968 SHELLENV_DEL_DUP_FILE DelDupFileArg; 969 SHELLENV_GET_FS_DEVICE_PATH GetFsDevicePath; 970 } EFI_SHELL_ENVIRONMENT2; 971 972 extern EFI_GUID gEfiShellEnvironment2Guid; 973 extern EFI_GUID gEfiShellEnvironment2ExtGuid; 974 975 #endif // _SHELL_ENVIRONMENT_2_PROTOCOL_H_ 976