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
 195 typedef struct {
 196   LIST_ENTRY  Link;
 197   CHAR16      *CommandString;
 198 } COMMAND_LIST;
 199
 200 /**
 201   Get the list of all available shell internal commands.  This is a linked list,
 202   via the LIST_ENTRY structure.  Enumerate through it using the BaseLib linked
 203   list functions.  Do not modify the values.
 204
 205   @param[in] Sort       TRUE to alphabetically sort the values first.  FALSE otherwise.
 206
 207   @return A linked list of all available shell commands.
 208 **/
 209 CONST COMMAND_LIST*
 210 EFIAPI
 211 ShellCommandGetCommandList (
 212   IN CONST BOOLEAN Sort
 213   );
 214
 215 typedef struct {
 216   LIST_ENTRY  Link;
 217   CHAR16      *CommandString;
 218   CHAR16      *Alias;
 219 } ALIAS_LIST;
 220
 221 /**
 222   Registers aliases to be set as part of the initialization of the shell application.
 223
 224   If Command is NULL, then ASSERT().
 225   If Alias is NULL, then ASSERT().
 226
 227   @param[in]  Command               The pointer to the Command.
 228   @param[in]  Alias                 The pointer to Alias.
 229
 230   @retval  RETURN_SUCCESS           The handlers were registered.
 231   @retval  RETURN_OUT_OF_RESOURCES  There are not enough resources available to
 232                                     register the shell command.
 233 **/
 234 RETURN_STATUS
 235 EFIAPI
 236 ShellCommandRegisterAlias (
 237   IN CONST CHAR16                       *Command,
 238   IN CONST CHAR16                       *Alias
 239   );
 240
 241 /**
 242   Get the list of all shell alias commands.  This is a linked list,
 243   via LIST_ENTRY structure.  Enumerate through it using the BaseLib linked
 244   list functions.  Do not modify the values.
 245
 246   @return A linked list of all requested shell aliases.
 247 **/
 248 CONST ALIAS_LIST*
 249 EFIAPI
 250 ShellCommandGetInitAliasList (
 251   VOID
 252   );
 253
 254 /**
 255   Determine if a given alias is on the list of built in aliases.
 256
 257   @param[in] Alias              The alias to test for.
 258
 259   @retval TRUE                  The alias is a built in alias.
 260   @retval FALSE                 The alias is not a built in alias.
 261 **/
 262 BOOLEAN
 263 EFIAPI
 264 ShellCommandIsOnAliasList (
 265   IN CONST CHAR16 *Alias
 266   );
 267
 268 /**
 269   Checks if a command is already on the list.
 270
 271   @param[in] CommandString        The command string to check for on the list.
 272
 273   @retval TRUE  CommandString represents a registered command.
 274   @retval FALSE CommandString does not represent a registered command.
 275 **/
 276 BOOLEAN
 277 EFIAPI
 278 ShellCommandIsCommandOnList (
 279   IN CONST  CHAR16                      *CommandString
 280   );
 281
 282 /**
 283   Get the help text for a command.
 284
 285   @param[in] CommandString        The command name.
 286
 287   @retval NULL  No help text was found.
 288   @return       The string of the help text.  The caller required to free.
 289 **/
 290 CHAR16*
 291 EFIAPI
 292 ShellCommandGetCommandHelp (
 293   IN CONST  CHAR16                      *CommandString
 294   );
 295
 296 /**
 297   Function to make sure that the above pointers are valid.
 298 **/
 299 EFI_STATUS
 300 EFIAPI
 301 CommandInit (
 302   VOID
 303   );
 304
 305 /**
 306   Function to determine current state of ECHO.  Echo determines if lines from scripts
 307   and ECHO commands are enabled.
 308
 309   @retval TRUE    Echo is currently enabled.
 310   @retval FALSE   Echo is currently disabled.
 311 **/
 312 BOOLEAN
 313 EFIAPI
 314 ShellCommandGetEchoState (
 315   VOID
 316   );
 317
 318 /**
 319   Function to set current state of ECHO.  Echo determines if lines from scripts
 320   and ECHO commands are enabled.
 321
 322   @param[in] State    TRUE to enable Echo, FALSE otherwise.
 323 **/
 324 VOID
 325 EFIAPI
 326 ShellCommandSetEchoState (
 327   IN BOOLEAN State
 328   );
 329
 330
 331
 332 /**
 333   Indicate that the current shell or script should exit.
 334
 335   @param[in] ScriptOnly   TRUE if exiting a script; FALSE otherwise.
 336   @param[in] ErrorCode    The 64 bit error code to return.
 337 **/
 338 VOID
 339 EFIAPI
 340 ShellCommandRegisterExit (
 341   IN BOOLEAN      ScriptOnly,
 342   IN CONST UINT64 ErrorCode
 343   );
 344
 345 /**
 346   Retrieve the Exit code.
 347
 348   @return the value passed into RegisterExit.
 349 **/
 350 UINT64
 351 EFIAPI
 352 ShellCommandGetExitCode (
 353   VOID
 354   );
 355
 356 /**
 357   Retrieve the Exit indicator.
 358
 359   @retval TRUE      Exit was indicated.
 360   @retval FALSE     Exit was not indicated.
 361 **/
 362 BOOLEAN
 363 EFIAPI
 364 ShellCommandGetExit (
 365   VOID
 366   );
 367
 368 /**
 369   Retrieve the Exit script indicator.
 370
 371   If ShellCommandGetExit returns FALSE, then the return from this is undefined.
 372
 373   @retval TRUE      ScriptOnly was indicated.
 374   @retval FALSE     ScriptOnly was not indicated.
 375 **/
 376 BOOLEAN
 377 EFIAPI
 378 ShellCommandGetScriptExit (
 379   VOID
 380   );
 381
 382 typedef struct {
 383   LIST_ENTRY      Link;     ///< List enumerator items.
 384   UINTN           Line;     ///< What line of the script file this was on.
 385   CHAR16          *Cl;      ///< The original command line.
 386   VOID            *Data;    ///< The data structure format dependant upon Command. (not always used)
 387   BOOLEAN         Reset;    ///< Reset the command (it must be treated like a initial run (but it may have data already))
 388 } SCRIPT_COMMAND_LIST;
 389
 390 typedef struct {
 391   CHAR16              *ScriptName;        ///< The filename of this script.
 392   CHAR16              **Argv;             ///< The parmameters to the script file.
 393   UINTN               Argc;               ///< The count of parameters.
 394   LIST_ENTRY          CommandList;        ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects).
 395   SCRIPT_COMMAND_LIST *CurrentCommand;    ///< The command currently being operated.  If !=NULL must be a member of CommandList.
 396   LIST_ENTRY          SubstList;          ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement).
 397 } SCRIPT_FILE;
 398
 399 /**
 400   Function to return a pointer to the currently running script file object.
 401
 402   @retval NULL        A script file is not currently running.
 403   @return             A pointer to the current script file object.
 404 **/
 405 SCRIPT_FILE*
 406 EFIAPI
 407 ShellCommandGetCurrentScriptFile (
 408   VOID
 409   );
 410
 411 /**
 412   Function to set a new script as the currently running one.
 413
 414   This function will correctly stack and unstack nested scripts.
 415
 416   @param[in] Script   The pointer to new script information structure.  If NULL,
 417                       it removes and de-allocates the topmost Script structure.
 418
 419   @return             A pointer to the current running script file after this
 420                       change.  It is NULL if removing the final script.
 421 **/
 422 SCRIPT_FILE*
 423 EFIAPI
 424 ShellCommandSetNewScript (
 425   IN SCRIPT_FILE *Script OPTIONAL
 426   );
 427
 428 /**
 429   Function to cleanup all memory from a SCRIPT_FILE structure.
 430
 431   @param[in] Script     The pointer to the structure to cleanup.
 432 **/
 433 VOID
 434 EFIAPI
 435 DeleteScriptFileStruct (
 436   IN SCRIPT_FILE *Script
 437   );
 438
 439 /**
 440   Function to get the current Profile string.
 441
 442   This is used to retrieve what profiles were installed.
 443
 444   @retval NULL  There are no installed profiles.
 445   @return       A semicolon-delimited list of profiles.
 446 **/
 447 CONST CHAR16 *
 448 EFIAPI
 449 ShellCommandGetProfileList (
 450   VOID
 451   );
 452
 453 typedef enum {
 454   MappingTypeFileSystem,
 455   MappingTypeBlockIo,
 456   MappingTypeMax
 457 } SHELL_MAPPING_TYPE;
 458
 459 /**
 460   Function to generate the next default mapping name.
 461
 462   If the return value is not NULL then it must be callee freed.
 463
 464   @param Type                   What kind of mapping name to make.
 465
 466   @retval NULL                  a memory allocation failed.
 467   @return a new map name string
 468 **/
 469 CHAR16*
 470 EFIAPI
 471 ShellCommandCreateNewMappingName(
 472   IN CONST SHELL_MAPPING_TYPE Type
 473   );
 474
 475 /**
 476   Function to initialize the table for creating consistent map names.
 477
 478   @param[out] Table             The pointer to pointer to pointer to DevicePathProtocol object.
 479
 480   @retval EFI_SUCCESS           The table was created successfully.
 481 **/
 482 EFI_STATUS
 483 EFIAPI
 484 ShellCommandConsistMappingInitialize (
 485   EFI_DEVICE_PATH_PROTOCOL           ***Table
 486   );
 487
 488 /**
 489   Function to uninitialize the table for creating consistent map names.
 490
 491   The parameter must have been received from ShellCommandConsistMappingInitialize.
 492
 493   @param[out] Table             The pointer to pointer to DevicePathProtocol object.
 494
 495   @retval EFI_SUCCESS           The table was deleted successfully.
 496 **/
 497 EFI_STATUS
 498 EFIAPI
 499 ShellCommandConsistMappingUnInitialize (
 500   EFI_DEVICE_PATH_PROTOCOL      **Table
 501   );
 502
 503 /**
 504   Create a consistent mapped name for the device specified by DevicePath
 505   based on the Table.
 506
 507   This must be called after ShellCommandConsistMappingInitialize() and
 508   before ShellCommandConsistMappingUnInitialize() is called.
 509
 510   @param[in] DevicePath   The pointer to the dev path for the device.
 511   @param[in] Table        The Table of mapping information.
 512
 513   @retval NULL            A consistent mapped name could not be created.
 514   @return                 A pointer to a string allocated from pool with the device name.
 515 **/
 516 CHAR16*
 517 EFIAPI
 518 ShellCommandConsistMappingGenMappingName (
 519   IN EFI_DEVICE_PATH_PROTOCOL      *DevicePath,
 520   IN EFI_DEVICE_PATH_PROTOCOL      **Table
 521   );
 522
 523 /**
 524   Function to search the list of mappings for the first matching node on the
 525   list based on the MapKey.
 526
 527   @param[in] MapKey             The pointer to the string key to search for in the map.
 528
 529   @return the node on the list.
 530 **/
 531 SHELL_MAP_LIST*
 532 EFIAPI
 533 ShellCommandFindMapItem (
 534   IN CONST CHAR16               *MapKey
 535   );
 536
 537 /**
 538   Function to add a map node to the list of map items and update the "path" environment variable (optionally).
 539
 540   If Path is TRUE (during initialization only), the path environment variable will also be updated to include
 541   default paths on the new map name...
 542
 543   Path should be FALSE when this function is called from the protocol SetMap function.
 544
 545   @param[in] Name               The human readable mapped name.
 546   @param[in] DevicePath         The Device Path for this map.
 547   @param[in] Flags              The Flags attribute for this map item.
 548   @param[in] Path               TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
 549
 550   @retval EFI_SUCCESS           The addition was sucessful.
 551   @retval EFI_OUT_OF_RESOURCES  A memory allocation failed.
 552   @retval EFI_INVALID_PARAMETER A parameter was invalid.
 553 **/
 554 EFI_STATUS
 555 EFIAPI
 556 ShellCommandAddMapItemAndUpdatePath(
 557   IN CONST CHAR16                   *Name,
 558   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
 559   IN CONST UINT64                   Flags,
 560   IN CONST BOOLEAN                  Path
 561   );
 562
 563 /**
 564   Creates the default map names for each device path in the system with
 565   a protocol depending on the Type.
 566
 567   Also sets up the default path environment variable if Type is FileSystem.
 568
 569   @retval EFI_SUCCESS           All map names were created sucessfully.
 570   @retval EFI_NOT_FOUND         No protocols were found in the system.
 571   @return                       Error returned from gBS->LocateHandle().
 572
 573   @sa LocateHandle
 574 **/
 575 EFI_STATUS
 576 EFIAPI
 577 ShellCommandCreateInitialMappingsAndPaths(
 578   VOID
 579   );
 580
 581 /**
 582   Add mappings for any devices without one.  Do not change any existing maps.
 583
 584   @retval EFI_SUCCESS   The operation was successful.
 585 **/
 586 EFI_STATUS
 587 EFIAPI
 588 ShellCommandUpdateMapping (
 589   VOID
 590   );
 591
 592 /**
 593   Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
 594
 595   @param[in] Handle     The SHELL_FILE_HANDLE to convert.
 596
 597   @return a EFI_FILE_PROTOCOL* representing the same file.
 598 **/
 599 EFI_FILE_PROTOCOL*
 600 EFIAPI
 601 ConvertShellHandleToEfiFileProtocol(
 602   IN CONST SHELL_FILE_HANDLE Handle
 603   );
 604
 605 /**
 606   Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
 607
 608   @param[in] Handle     The SHELL_FILE_HANDLE to remove.
 609
 610   @retval TRUE          The item was removed.
 611   @retval FALSE         The item was not found.
 612 **/
 613 BOOLEAN
 614 EFIAPI
 615 ShellFileHandleRemove(
 616   IN CONST SHELL_FILE_HANDLE Handle
 617   );
 618
 619 /**
 620   Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
 621
 622   @param[in] Handle     The pointer to EFI_FILE_PROTOCOL to convert.
 623   @param[in] Path       The path to the file for verification.
 624
 625   @return a SHELL_FILE_HANDLE representing the same file.
 626 **/
 627 SHELL_FILE_HANDLE
 628 EFIAPI
 629 ConvertEfiFileProtocolToShellHandle(
 630   IN CONST EFI_FILE_PROTOCOL *Handle,
 631   IN CONST CHAR16            *Path
 632   );
 633
 634 /**
 635   Find the path that was logged with the specified SHELL_FILE_HANDLE.
 636
 637   @param[in] Handle     The SHELL_FILE_HANDLE to query on.
 638
 639   @return A pointer to the path for the file.
 640 **/
 641 CONST CHAR16*
 642 EFIAPI
 643 ShellFileHandleGetPath(
 644   IN CONST SHELL_FILE_HANDLE Handle
 645   );
 646
 647
 648 /**
 649   Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
 650
 651   This will NOT work on directories.
 652
 653   If Handle is NULL, then ASSERT.
 654
 655   @param[in] Handle     the file handle
 656
 657   @retval TRUE          the position is at the end of the file
 658   @retval FALSE         the position is not at the end of the file
 659 **/
 660 BOOLEAN
 661 EFIAPI
 662 ShellFileHandleEof(
 663   IN SHELL_FILE_HANDLE Handle
 664   );
 665
 666 typedef struct {
 667   LIST_ENTRY    Link;
 668   void          *Buffer;
 669 } BUFFER_LIST;
 670
 671 /**
 672   Frees any BUFFER_LIST defined type.
 673
 674   @param[in] List   The pointer to the list head.
 675 **/
 676 VOID
 677 EFIAPI
 678 FreeBufferList (
 679   IN BUFFER_LIST *List
 680   );
 681
 682 /**
 683   Function printing hex output to the console.
 684
 685   @param[in] Indent       Number of spaces to indent.
 686   @param[in] Offset       Offset to start with.
 687   @param[in] DataSize     Length of data.
 688   @param[in] UserData     Pointer to some data.
 689 **/
 690 VOID
 691 EFIAPI
 692 DumpHex (
 693   IN UINTN        Indent,
 694   IN UINTN        Offset,
 695   IN UINTN        DataSize,
 696   IN VOID         *UserData
 697   );
 698
 699 /**
 700   Dump HEX data into buffer.
 701
 702   @param[in] Buffer     HEX data to be dumped in Buffer.
 703   @param[in] Indent     How many spaces to indent the output.
 704   @param[in] Offset     The offset of the printing.
 705   @param[in] DataSize   The size in bytes of UserData.
 706   @param[in] UserData   The data to print out.
 707 **/
 708 CHAR16*
 709 EFIAPI
 710 CatSDumpHex (
 711   IN CHAR16  *Buffer,
 712   IN UINTN   Indent,
 713   IN UINTN   Offset,
 714   IN UINTN   DataSize,
 715   IN VOID    *UserData
 716   );
 717
 718 //
 719 // Determines the ordering operation for ShellSortFileList().
 720 //
 721 typedef enum {
 722   //
 723   // Sort the EFI_SHELL_FILE_INFO objects by the FileName field, in increasing
 724   // order, using gUnicodeCollation->StriColl().
 725   //
 726   ShellSortFileListByFileName,
 727   //
 728   // Sort the EFI_SHELL_FILE_INFO objects by the FullName field, in increasing
 729   // order, using gUnicodeCollation->StriColl().
 730   //
 731   ShellSortFileListByFullName,
 732   ShellSortFileListMax
 733 } SHELL_SORT_FILE_LIST;
 734
 735 /**
 736   Sort an EFI_SHELL_FILE_INFO list, optionally moving duplicates to a separate
 737   list.
 738
 739   @param[in,out] FileList  The list of EFI_SHELL_FILE_INFO objects to sort.
 740
 741                            If FileList is NULL on input, then FileList is
 742                            considered an empty, hence already sorted, list.
 743
 744                            Otherwise, if (*FileList) is NULL on input, then
 745                            EFI_INVALID_PARAMETER is returned.
 746
 747                            Otherwise, the caller is responsible for having
 748                            initialized (*FileList)->Link with
 749                            InitializeListHead(). No other fields in the
 750                            (**FileList) head element are accessed by this
 751                            function.
 752
 753                            On output, (*FileList) is sorted according to Order.
 754                            If Duplicates is NULL on input, then duplicate
 755                            elements are preserved, sorted stably, on
 756                            (*FileList). If Duplicates is not NULL on input,
 757                            then duplicates are moved (stably sorted) to the
 758                            new, dynamically allocated (*Duplicates) list.
 759
 760   @param[out] Duplicates   If Duplicates is NULL on input, (*FileList) will be
 761                            a monotonically ordered list on output, with
 762                            duplicates stably sorted.
 763
 764                            If Duplicates is not NULL on input, (*FileList) will
 765                            be a strictly monotonically oredered list on output,
 766                            with duplicates separated (stably sorted) to
 767                            (*Duplicates). All fields except Link will be
 768                            zero-initialized in the (**Duplicates) head element.
 769                            If no duplicates exist, then (*Duplicates) is set to
 770                            NULL on output.
 771
 772   @param[in] Order         Determines the comparison operation between
 773                            EFI_SHELL_FILE_INFO objects.
 774
 775   @retval EFI_INVALID_PARAMETER  (UINTN)Order is greater than or equal to
 776                                  (UINTN)ShellSortFileListMax. Neither the
 777                                  (*FileList) nor the (*Duplicates) list has
 778                                  been modified.
 779
 780   @retval EFI_INVALID_PARAMETER  (*FileList) was NULL on input. Neither the
 781                                  (*FileList) nor the (*Duplicates) list has
 782                                  been modified.
 783
 784   @retval EFI_OUT_OF_RESOURCES   Memory allocation failed. Neither the
 785                                  (*FileList) nor the (*Duplicates) list has
 786                                  been modified.
 787
 788   @retval EFI_SUCCESS            Sorting successful, including the case when
 789                                  FileList is NULL on input.
 790 **/
 791 EFI_STATUS
 792 EFIAPI
 793 ShellSortFileList (
 794   IN OUT EFI_SHELL_FILE_INFO  **FileList,
 795      OUT EFI_SHELL_FILE_INFO  **Duplicates OPTIONAL,
 796   IN     SHELL_SORT_FILE_LIST Order
 797   );
 798 #endif //_SHELL_COMMAND_LIB_