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