1 /** @file 2 Provides interface to shell internal functions for shell commands. 3 4 This library is for use ONLY by shell commands linked into the shell application. 5 This library will not funciton if it is used for UEFI Shell 2.0 Applications. 6 7 (C) Copyright 2013-2014 Hewlett-Packard Development Company, L.P.<BR> 8 Copyright (c) 2009 - 2014, Intel Corporation. All rights reserved.<BR> 9 This program and the accompanying materials 10 are licensed and made available under the terms and conditions of the BSD License 11 which accompanies this distribution. The full text of the license may be found at 12 http://opensource.org/licenses/bsd-license.php. 13 14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 16 17 **/ 18 19 #ifndef _SHELL_COMMAND_LIB_ 20 #define _SHELL_COMMAND_LIB_ 21 22 #include <Uefi.h> 23 #include <ShellBase.h> 24 25 #include <Protocol/EfiShell.h> 26 #include <Protocol/EfiShellParameters.h> 27 #include <Protocol/UnicodeCollation.h> 28 #include <Protocol/SimpleFileSystem.h> 29 30 #include <Library/UefiBootServicesTableLib.h> 31 32 // 33 // The extern global protocol poionters. 34 // 35 extern EFI_UNICODE_COLLATION_PROTOCOL *gUnicodeCollation; 36 extern CONST CHAR16* SupportLevel[]; 37 38 // 39 // The map list objects. 40 // 41 typedef struct { 42 LIST_ENTRY Link; 43 EFI_DEVICE_PATH_PROTOCOL *DevicePath; 44 CHAR16 *MapName; 45 CHAR16 *CurrentDirectoryPath; 46 UINT64 Flags; 47 } SHELL_MAP_LIST; 48 /// List of Mappings - DeviceName and Drive Letter(ism). 49 extern SHELL_MAP_LIST gShellMapList; 50 /// Pointer to node of current directory in the mMapList. 51 extern SHELL_MAP_LIST *gShellCurDir; 52 53 /** 54 Returns the help MAN fileName for a given shell command. 55 56 @retval !NULL The unicode string of the MAN filename. 57 @retval NULL An error ocurred. 58 59 **/ 60 typedef 61 CONST CHAR16 * 62 (EFIAPI *SHELL_GET_MAN_FILENAME)( 63 VOID 64 ); 65 66 /** 67 Runs a shell command on a given command line. 68 69 The specific operation of a given shell command is specified in the UEFI Shell 70 Specification 2.0, or in the source of the given command. 71 72 Upon completion of the command run the shell protocol and environment variables 73 may have been updated due to the operation. 74 75 @param[in] ImageHandle The ImageHandle to the app, or NULL if 76 the command built into shell. 77 @param[in] SystemTable The pointer to the system table. 78 79 @retval RETURN_SUCCESS The shell command was sucessful. 80 @retval RETURN_UNSUPPORTED The command is not supported. 81 **/ 82 typedef 83 SHELL_STATUS 84 (EFIAPI *SHELL_RUN_COMMAND)( 85 IN EFI_HANDLE ImageHandle, 86 IN EFI_SYSTEM_TABLE *SystemTable 87 ); 88 89 /** 90 Registers the handlers of type SHELL_RUN_COMMAND and 91 SHELL_GET_MAN_FILENAME for each shell command. 92 93 If the ShellSupportLevel is greater than the value of 94 PcdShellSupportLevel, then return RETURN_UNSUPPORTED. 95 96 Registers the the handlers specified by GetHelpInfoHandler and CommandHandler 97 with the command specified by CommandString. If the command named by 98 CommandString has already been registered, then return 99 RETURN_ALREADY_STARTED. 100 101 If there are not enough resources available to register the handlers, then 102 RETURN_OUT_OF_RESOURCES is returned. 103 104 If CommandString is NULL, then ASSERT(). 105 If GetHelpInfoHandler is NULL, then ASSERT(). 106 If CommandHandler is NULL, then ASSERT(). 107 If ProfileName is NULL, then ASSERT(). 108 109 @param[in] CommandString The pointer to the command name. This is the 110 name to look for on the command line in 111 the shell. 112 @param[in] CommandHandler The pointer to a function that runs the 113 specified command. 114 @param[in] GetManFileName The pointer to a function that provides man 115 filename. 116 @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this 117 function. 118 @param[in] ProfileName The profile name to require for support of this 119 function. 120 @param[in] CanAffectLE Indicates whether this command's return value 121 can change the LASTERROR environment variable. 122 @param[in] HiiHandle The handle of this command's HII entry. 123 @param[in] ManFormatHelp The HII locator for the help text. 124 125 @retval RETURN_SUCCESS The handlers were registered. 126 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to 127 register the shell command. 128 @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the 129 currently allowed support level. 130 @retval RETURN_ALREADY_STARTED The CommandString represents a command that 131 is already registered. Only one handler set for 132 a given command is allowed. 133 @sa SHELL_GET_MAN_FILENAME 134 @sa SHELL_RUN_COMMAND 135 **/ 136 RETURN_STATUS 137 EFIAPI 138 ShellCommandRegisterCommandName ( 139 IN CONST CHAR16 *CommandString, 140 IN SHELL_RUN_COMMAND CommandHandler, 141 IN SHELL_GET_MAN_FILENAME GetManFileName, 142 IN UINT32 ShellMinSupportLevel, 143 IN CONST CHAR16 *ProfileName, 144 IN CONST BOOLEAN CanAffectLE, 145 IN CONST EFI_HANDLE HiiHandle, 146 IN CONST EFI_STRING_ID ManFormatHelp 147 ); 148 149 /** 150 Checks if a command string has been registered for CommandString, and if so, it runs 151 the previously registered handler for that command with the command line. 152 153 If CommandString is NULL, then ASSERT(). 154 155 If Sections is specified, then each section name listed will be compared in a case sensitive 156 manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists, 157 it is appended to the returned help text. If the section does not exist, no 158 information is returned. If Sections is NULL, then all help text information 159 available is returned. 160 161 @param[in] CommandString The pointer to the command name. This is the name 162 found on the command line in the shell. 163 @param[in, out] RetVal The pointer to the return value from the command handler. 164 165 @param[in, out] CanAffectLE Indicates whether this command's return value 166 needs to be placed into LASTERROR environment variable. 167 168 @retval RETURN_SUCCESS The handler was run. 169 @retval RETURN_NOT_FOUND The CommandString did not match a registered 170 command name. 171 @sa SHELL_RUN_COMMAND 172 **/ 173 RETURN_STATUS 174 EFIAPI 175 ShellCommandRunCommandHandler ( 176 IN CONST CHAR16 *CommandString, 177 IN OUT SHELL_STATUS *RetVal, 178 IN OUT BOOLEAN *CanAffectLE OPTIONAL 179 ); 180 181 /** 182 Checks if a command string has been registered for CommandString, and if so, it 183 returns the MAN filename specified for that command. 184 185 If CommandString is NULL, then ASSERT(). 186 187 @param[in] CommandString The pointer to the command name. This is the name 188 found on the command line in the shell. 189 190 @retval NULL The CommandString was not a registered command. 191 @retval other The name of the MAN file. 192 @sa SHELL_GET_MAN_FILENAME 193 **/ 194 CONST CHAR16* 195 EFIAPI 196 ShellCommandGetManFileNameHandler ( 197 IN CONST CHAR16 *CommandString 198 ); 199 200 201 typedef struct { 202 LIST_ENTRY Link; 203 CHAR16 *CommandString; 204 } COMMAND_LIST; 205 206 /** 207 Get the list of all available shell internal commands. This is a linked list, 208 via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked 209 list functions. Do not modify the values. 210 211 @param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise. 212 213 @return A linked list of all available shell commands. 214 **/ 215 CONST COMMAND_LIST* 216 EFIAPI 217 ShellCommandGetCommandList ( 218 IN CONST BOOLEAN Sort 219 ); 220 221 typedef struct { 222 LIST_ENTRY Link; 223 CHAR16 *CommandString; 224 CHAR16 *Alias; 225 } ALIAS_LIST; 226 227 /** 228 Registers aliases to be set as part of the initialization of the shell application. 229 230 If Command is NULL, then ASSERT(). 231 If Alias is NULL, then ASSERT(). 232 233 @param[in] Command The pointer to the Command. 234 @param[in] Alias The pointer to Alias. 235 236 @retval RETURN_SUCCESS The handlers were registered. 237 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to 238 register the shell command. 239 **/ 240 RETURN_STATUS 241 EFIAPI 242 ShellCommandRegisterAlias ( 243 IN CONST CHAR16 *Command, 244 IN CONST CHAR16 *Alias 245 ); 246 247 /** 248 Get the list of all shell alias commands. This is a linked list, 249 via LIST_ENTRY structure. Enumerate through it using the BaseLib linked 250 list functions. Do not modify the values. 251 252 @return A linked list of all requested shell aliases. 253 **/ 254 CONST ALIAS_LIST* 255 EFIAPI 256 ShellCommandGetInitAliasList ( 257 VOID 258 ); 259 260 /** 261 Determine if a given alias is on the list of built in aliases. 262 263 @param[in] Alias The alias to test for. 264 265 @retval TRUE The alias is a built in alias. 266 @retval FALSE The alias is not a built in alias. 267 **/ 268 BOOLEAN 269 EFIAPI 270 ShellCommandIsOnAliasList ( 271 IN CONST CHAR16 *Alias 272 ); 273 274 /** 275 Checks if a command is already on the list. 276 277 @param[in] CommandString The command string to check for on the list. 278 279 @retval TRUE CommandString represents a registered command. 280 @retval FALSE CommandString does not represent a registered command. 281 **/ 282 BOOLEAN 283 EFIAPI 284 ShellCommandIsCommandOnList ( 285 IN CONST CHAR16 *CommandString 286 ); 287 288 /** 289 Get the help text for a command. 290 291 @param[in] CommandString The command name. 292 293 @retval NULL No help text was found. 294 @return The string of the help text. The caller required to free. 295 **/ 296 CHAR16* 297 EFIAPI 298 ShellCommandGetCommandHelp ( 299 IN CONST CHAR16 *CommandString 300 ); 301 302 /** 303 Function to make sure that the above pointers are valid. 304 **/ 305 EFI_STATUS 306 EFIAPI 307 CommandInit ( 308 VOID 309 ); 310 311 /** 312 Function to determine current state of ECHO. Echo determines if lines from scripts 313 and ECHO commands are enabled. 314 315 @retval TRUE Echo is currently enabled. 316 @retval FALSE Echo is currently disabled. 317 **/ 318 BOOLEAN 319 EFIAPI 320 ShellCommandGetEchoState ( 321 VOID 322 ); 323 324 /** 325 Function to set current state of ECHO. Echo determines if lines from scripts 326 and ECHO commands are enabled. 327 328 @param[in] State TRUE to enable Echo, FALSE otherwise. 329 **/ 330 VOID 331 EFIAPI 332 ShellCommandSetEchoState ( 333 IN BOOLEAN State 334 ); 335 336 337 338 /** 339 Indicate that the current shell or script should exit. 340 341 @param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise. 342 @param[in] ErrorCode The 64 bit error code to return. 343 **/ 344 VOID 345 EFIAPI 346 ShellCommandRegisterExit ( 347 IN BOOLEAN ScriptOnly, 348 IN CONST UINT64 ErrorCode 349 ); 350 351 /** 352 Retrieve the Exit code. 353 354 @return the value passed into RegisterExit. 355 **/ 356 UINT64 357 EFIAPI 358 ShellCommandGetExitCode ( 359 VOID 360 ); 361 362 /** 363 Retrieve the Exit indicator. 364 365 @retval TRUE Exit was indicated. 366 @retval FALSE Exit was not indicated. 367 **/ 368 BOOLEAN 369 EFIAPI 370 ShellCommandGetExit ( 371 VOID 372 ); 373 374 /** 375 Retrieve the Exit script indicator. 376 377 If ShellCommandGetExit returns FALSE, then the return from this is undefined. 378 379 @retval TRUE ScriptOnly was indicated. 380 @retval FALSE ScriptOnly was not indicated. 381 **/ 382 BOOLEAN 383 EFIAPI 384 ShellCommandGetScriptExit ( 385 VOID 386 ); 387 388 typedef struct { 389 LIST_ENTRY Link; ///< List enumerator items. 390 UINTN Line; ///< What line of the script file this was on. 391 CHAR16 *Cl; ///< The original command line. 392 VOID *Data; ///< The data structure format dependant upon Command. (not always used) 393 BOOLEAN Reset; ///< Reset the command (it must be treated like a initial run (but it may have data already)) 394 } SCRIPT_COMMAND_LIST; 395 396 typedef struct { 397 CHAR16 *ScriptName; ///< The filename of this script. 398 CHAR16 **Argv; ///< The parmameters to the script file. 399 UINTN Argc; ///< The count of parameters. 400 LIST_ENTRY CommandList; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects). 401 SCRIPT_COMMAND_LIST *CurrentCommand; ///< The command currently being operated. If !=NULL must be a member of CommandList. 402 LIST_ENTRY SubstList; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement). 403 } SCRIPT_FILE; 404 405 /** 406 Function to return a pointer to the currently running script file object. 407 408 @retval NULL A script file is not currently running. 409 @return A pointer to the current script file object. 410 **/ 411 SCRIPT_FILE* 412 EFIAPI 413 ShellCommandGetCurrentScriptFile ( 414 VOID 415 ); 416 417 /** 418 Function to set a new script as the currently running one. 419 420 This function will correctly stack and unstack nested scripts. 421 422 @param[in] Script The pointer to new script information structure. If NULL, 423 it removes and de-allocates the topmost Script structure. 424 425 @return A pointer to the current running script file after this 426 change. It is NULL if removing the final script. 427 **/ 428 SCRIPT_FILE* 429 EFIAPI 430 ShellCommandSetNewScript ( 431 IN SCRIPT_FILE *Script OPTIONAL 432 ); 433 434 /** 435 Function to cleanup all memory from a SCRIPT_FILE structure. 436 437 @param[in] Script The pointer to the structure to cleanup. 438 **/ 439 VOID 440 EFIAPI 441 DeleteScriptFileStruct ( 442 IN SCRIPT_FILE *Script 443 ); 444 445 /** 446 Function to get the current Profile string. 447 448 This is used to retrieve what profiles were installed. 449 450 @retval NULL There are no installed profiles. 451 @return A semicolon-delimited list of profiles. 452 **/ 453 CONST CHAR16 * 454 EFIAPI 455 ShellCommandGetProfileList ( 456 VOID 457 ); 458 459 typedef enum { 460 MappingTypeFileSystem, 461 MappingTypeBlockIo, 462 MappingTypeMax 463 } SHELL_MAPPING_TYPE; 464 465 /** 466 Function to generate the next default mapping name. 467 468 If the return value is not NULL then it must be callee freed. 469 470 @param Type What kind of mapping name to make. 471 472 @retval NULL a memory allocation failed. 473 @return a new map name string 474 **/ 475 CHAR16* 476 EFIAPI 477 ShellCommandCreateNewMappingName( 478 IN CONST SHELL_MAPPING_TYPE Type 479 ); 480 481 /** 482 Function to initialize the table for creating consistent map names. 483 484 @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object. 485 486 @retval EFI_SUCCESS The table was created successfully. 487 **/ 488 EFI_STATUS 489 EFIAPI 490 ShellCommandConsistMappingInitialize ( 491 EFI_DEVICE_PATH_PROTOCOL ***Table 492 ); 493 494 /** 495 Function to uninitialize the table for creating consistent map names. 496 497 The parameter must have been received from ShellCommandConsistMappingInitialize. 498 499 @param[out] Table The pointer to pointer to DevicePathProtocol object. 500 501 @retval EFI_SUCCESS The table was deleted successfully. 502 **/ 503 EFI_STATUS 504 EFIAPI 505 ShellCommandConsistMappingUnInitialize ( 506 EFI_DEVICE_PATH_PROTOCOL **Table 507 ); 508 509 /** 510 Create a consistent mapped name for the device specified by DevicePath 511 based on the Table. 512 513 This must be called after ShellCommandConsistMappingInitialize() and 514 before ShellCommandConsistMappingUnInitialize() is called. 515 516 @param[in] DevicePath The pointer to the dev path for the device. 517 @param[in] Table The Table of mapping information. 518 519 @retval NULL A consistent mapped name could not be created. 520 @return A pointer to a string allocated from pool with the device name. 521 **/ 522 CHAR16* 523 EFIAPI 524 ShellCommandConsistMappingGenMappingName ( 525 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, 526 IN EFI_DEVICE_PATH_PROTOCOL **Table 527 ); 528 529 /** 530 Function to search the list of mappings for the first matching node on the 531 list based on the MapKey. 532 533 @param[in] MapKey The pointer to the string key to search for in the map. 534 535 @return the node on the list. 536 **/ 537 SHELL_MAP_LIST* 538 EFIAPI 539 ShellCommandFindMapItem ( 540 IN CONST CHAR16 *MapKey 541 ); 542 543 /** 544 Function to add a map node to the list of map items and update the "path" environment variable (optionally). 545 546 If Path is TRUE (during initialization only), the path environment variable will also be updated to include 547 default paths on the new map name... 548 549 Path should be FALSE when this function is called from the protocol SetMap function. 550 551 @param[in] Name The human readable mapped name. 552 @param[in] DevicePath The Device Path for this map. 553 @param[in] Flags The Flags attribute for this map item. 554 @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization). 555 556 @retval EFI_SUCCESS The addition was sucessful. 557 @retval EFI_OUT_OF_RESOURCES A memory allocation failed. 558 @retval EFI_INVALID_PARAMETER A parameter was invalid. 559 **/ 560 EFI_STATUS 561 EFIAPI 562 ShellCommandAddMapItemAndUpdatePath( 563 IN CONST CHAR16 *Name, 564 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, 565 IN CONST UINT64 Flags, 566 IN CONST BOOLEAN Path 567 ); 568 569 /** 570 Creates the default map names for each device path in the system with 571 a protocol depending on the Type. 572 573 Also sets up the default path environment variable if Type is FileSystem. 574 575 @retval EFI_SUCCESS All map names were created sucessfully. 576 @retval EFI_NOT_FOUND No protocols were found in the system. 577 @return Error returned from gBS->LocateHandle(). 578 579 @sa LocateHandle 580 **/ 581 EFI_STATUS 582 EFIAPI 583 ShellCommandCreateInitialMappingsAndPaths( 584 VOID 585 ); 586 587 /** 588 Add mappings for any devices without one. Do not change any existing maps. 589 590 @retval EFI_SUCCESS The operation was successful. 591 **/ 592 EFI_STATUS 593 EFIAPI 594 ShellCommandUpdateMapping ( 595 VOID 596 ); 597 598 /** 599 Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*. 600 601 @param[in] Handle The SHELL_FILE_HANDLE to convert. 602 603 @return a EFI_FILE_PROTOCOL* representing the same file. 604 **/ 605 EFI_FILE_PROTOCOL* 606 EFIAPI 607 ConvertShellHandleToEfiFileProtocol( 608 IN CONST SHELL_FILE_HANDLE Handle 609 ); 610 611 /** 612 Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES. 613 614 @param[in] Handle The SHELL_FILE_HANDLE to remove. 615 616 @retval TRUE The item was removed. 617 @retval FALSE The item was not found. 618 **/ 619 BOOLEAN 620 EFIAPI 621 ShellFileHandleRemove( 622 IN CONST SHELL_FILE_HANDLE Handle 623 ); 624 625 /** 626 Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE. 627 628 @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert. 629 @param[in] Path The path to the file for verification. 630 631 @return a SHELL_FILE_HANDLE representing the same file. 632 **/ 633 SHELL_FILE_HANDLE 634 EFIAPI 635 ConvertEfiFileProtocolToShellHandle( 636 IN CONST EFI_FILE_PROTOCOL *Handle, 637 IN CONST CHAR16 *Path 638 ); 639 640 /** 641 Find the path that was logged with the specified SHELL_FILE_HANDLE. 642 643 @param[in] Handle The SHELL_FILE_HANDLE to query on. 644 645 @return A pointer to the path for the file. 646 **/ 647 CONST CHAR16* 648 EFIAPI 649 ShellFileHandleGetPath( 650 IN CONST SHELL_FILE_HANDLE Handle 651 ); 652 653 654 /** 655 Function to determine if a SHELL_FILE_HANDLE is at the end of the file. 656 657 This will NOT work on directories. 658 659 If Handle is NULL, then ASSERT. 660 661 @param[in] Handle the file handle 662 663 @retval TRUE the position is at the end of the file 664 @retval FALSE the position is not at the end of the file 665 **/ 666 BOOLEAN 667 EFIAPI 668 ShellFileHandleEof( 669 IN SHELL_FILE_HANDLE Handle 670 ); 671 672 typedef struct { 673 LIST_ENTRY Link; 674 void *Buffer; 675 } BUFFER_LIST; 676 677 /** 678 Frees any BUFFER_LIST defined type. 679 680 @param[in] List The pointer to the list head. 681 **/ 682 VOID 683 EFIAPI 684 FreeBufferList ( 685 IN BUFFER_LIST *List 686 ); 687 688 #endif //_SHELL_COMMAND_LIB_ 689