ShellPkg/Include/Library/ShellCommandLib.h

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