ShellPkg/Application/Shell/ShellProtocol.h

   1 /** @file
   2   Member functions of EFI_SHELL_PROTOCOL and functions for creation,
   3   manipulation, and initialization of EFI_SHELL_PROTOCOL.
   4
   5   (C) Copyright 2014 Hewlett-Packard Development Company, L.P.<BR>
   6   Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR>
   7   This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef _SHELL_PROTOCOL_HEADER_
  18 #define _SHELL_PROTOCOL_HEADER_
  19
  20 #include "Shell.h"
  21
  22 typedef struct {
  23   LIST_ENTRY                Link;
  24   EFI_SHELL_PROTOCOL        *Interface;
  25   EFI_HANDLE                Handle;
  26 } SHELL_PROTOCOL_HANDLE_LIST;
  27
  28 // flags values...
  29 #define SHELL_MAP_FLAGS_CONSIST BIT1
  30
  31 /**
  32   Function to create and install on the current handle.
  33
  34   Will overwrite any existing ShellProtocols in the system to be sure that
  35   the current shell is in control.
  36
  37   This must be removed via calling CleanUpShellProtocol().
  38
  39   @param[in, out] NewShell   The pointer to the pointer to the structure
  40   to install.
  41
  42   @retval EFI_SUCCESS     The operation was successful.
  43   @return                 An error from LocateHandle, CreateEvent, or other core function.
  44 **/
  45 EFI_STATUS
  46 EFIAPI
  47 CreatePopulateInstallShellProtocol (
  48   IN OUT EFI_SHELL_PROTOCOL  **NewShell
  49   );
  50
  51 /**
  52   Opposite of CreatePopulateInstallShellProtocol.
  53
  54   Free all memory and restore the system to the state it was in before calling
  55   CreatePopulateInstallShellProtocol.
  56
  57   @param[in, out] NewShell   The pointer to the new shell protocol structure.
  58
  59   @retval EFI_SUCCESS       The operation was successful.
  60 **/
  61 EFI_STATUS
  62 CleanUpShellProtocol (
  63   IN OUT EFI_SHELL_PROTOCOL  *NewShell
  64   );
  65
  66 /**
  67   Cleanup the shell environment.
  68
  69   @param[in, out] NewShell   The pointer to the new shell protocol structure.
  70
  71   @retval EFI_SUCCESS       The operation was successful.
  72 **/
  73 EFI_STATUS
  74 CleanUpShellEnvironment (
  75   IN OUT EFI_SHELL_PROTOCOL  *NewShell
  76   );
  77
  78 /**
  79   This function creates a mapping for a device path.
  80
  81   @param DevicePath             Points to the device path. If this is NULL and Mapping points to a valid mapping,
  82                                 then the mapping will be deleted.
  83   @param Mapping                Points to the NULL-terminated mapping for the device path.  Must end with a ':'
  84
  85   @retval EFI_SUCCESS           Mapping created or deleted successfully.
  86   @retval EFI_NO_MAPPING        There is no handle that corresponds exactly to DevicePath. See the
  87                                 boot service function LocateDevicePath().
  88   @retval EFI_ACCESS_DENIED     The mapping is a built-in alias.
  89   @retval EFI_INVALID_PARAMETER Mapping was NULL
  90   @retval EFI_INVALID_PARAMETER Mapping did not end with a ':'
  91   @retval EFI_INVALID_PARAMETER DevicePath was not pointing at a device that had a SIMPLE_FILE_SYSTEM_PROTOCOL installed.
  92   @retval EFI_NOT_FOUND         There was no mapping found to delete
  93   @retval EFI_OUT_OF_RESOURCES  Memory allocation failed
  94 **/
  95 EFI_STATUS
  96 EFIAPI
  97 EfiShellSetMap(
  98   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath OPTIONAL,
  99   IN CONST CHAR16 *Mapping
 100   );
 101
 102 /**
 103   Gets the device path from the mapping.
 104
 105   This function gets the device path associated with a mapping.
 106
 107   @param Mapping                A pointer to the mapping
 108
 109   @retval !=NULL                Pointer to the device path that corresponds to the
 110                                 device mapping. The returned pointer does not need
 111                                 to be freed.
 112   @retval NULL                  There is no device path associated with the
 113                                 specified mapping.
 114 **/
 115 CONST EFI_DEVICE_PATH_PROTOCOL *
 116 EFIAPI
 117 EfiShellGetDevicePathFromMap(
 118   IN CONST CHAR16 *Mapping
 119   );
 120
 121 /**
 122   Gets the mapping that most closely matches the device path.
 123
 124   This function gets the mapping which corresponds to the device path *DevicePath. If
 125   there is no exact match, then the mapping which most closely matches *DevicePath
 126   is returned, and *DevicePath is updated to point to the remaining portion of the
 127   device path. If there is an exact match, the mapping is returned and *DevicePath
 128   points to the end-of-device-path node.
 129
 130   @param DevicePath             On entry, points to a device path pointer. On
 131                                 exit, updates the pointer to point to the
 132                                 portion of the device path after the mapping.
 133
 134   @retval NULL                  No mapping was found.
 135   @return !=NULL                Pointer to NULL-terminated mapping. The buffer
 136                                 is callee allocated and should be freed by the caller.
 137 **/
 138 CONST CHAR16 *
 139 EFIAPI
 140 EfiShellGetMapFromDevicePath(
 141   IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath
 142   );
 143
 144 /**
 145   Converts a device path to a file system-style path.
 146
 147   This function converts a device path to a file system path by replacing part, or all, of
 148   the device path with the file-system mapping. If there are more than one application
 149   file system mappings, the one that most closely matches Path will be used.
 150
 151   @param Path                   The pointer to the device path
 152
 153   @retval NULL                  the device path could not be found.
 154   @return all                   The pointer of the NULL-terminated file path. The path
 155                                 is callee-allocated and should be freed by the caller.
 156 **/
 157 CHAR16 *
 158 EFIAPI
 159 EfiShellGetFilePathFromDevicePath(
 160   IN CONST EFI_DEVICE_PATH_PROTOCOL *Path
 161   );
 162
 163 /**
 164   Converts a file system style name to a device path.
 165
 166   This function converts a file system style name to a device path, by replacing any
 167   mapping references to the associated device path.
 168
 169   @param Path                   the pointer to the path
 170
 171   @return all                   The pointer of the file path. The file path is callee
 172                                 allocated and should be freed by the caller.
 173 **/
 174 EFI_DEVICE_PATH_PROTOCOL *
 175 EFIAPI
 176 EfiShellGetDevicePathFromFilePath(
 177   IN CONST CHAR16 *Path
 178   );
 179
 180 /**
 181   Gets the name of the device specified by the device handle.
 182
 183   This function gets the user-readable name of the device specified by the device
 184   handle. If no user-readable name could be generated, then *BestDeviceName will be
 185   NULL and EFI_NOT_FOUND will be returned.
 186
 187   If EFI_DEVICE_NAME_USE_COMPONENT_NAME is set, then the function will return the
 188   device's name using the EFI_COMPONENT_NAME2_PROTOCOL, if present on
 189   DeviceHandle.
 190
 191   If EFI_DEVICE_NAME_USE_DEVICE_PATH is set, then the function will return the
 192   device's name using the EFI_DEVICE_PATH_PROTOCOL, if present on DeviceHandle.
 193   If both EFI_DEVICE_NAME_USE_COMPONENT_NAME and
 194   EFI_DEVICE_NAME_USE_DEVICE_PATH are set, then
 195   EFI_DEVICE_NAME_USE_COMPONENT_NAME will have higher priority.
 196
 197   @param DeviceHandle           The handle of the device.
 198   @param Flags                  Determines the possible sources of component names.
 199                                 Valid bits are:
 200                                   EFI_DEVICE_NAME_USE_COMPONENT_NAME
 201                                   EFI_DEVICE_NAME_USE_DEVICE_PATH
 202   @param Language               A pointer to the language specified for the device
 203                                 name, in the same format as described in the UEFI
 204                                 specification, Appendix M
 205   @param BestDeviceName         On return, points to the callee-allocated NULL-
 206                                 terminated name of the device. If no device name
 207                                 could be found, points to NULL. The name must be
 208                                 freed by the caller...
 209
 210   @retval EFI_SUCCESS           Get the name successfully.
 211   @retval EFI_NOT_FOUND         Fail to get the device name.
 212   @retval EFI_INVALID_PARAMETER Flags did not have a valid bit set.
 213   @retval EFI_INVALID_PARAMETER BestDeviceName was NULL
 214   @retval EFI_INVALID_PARAMETER DeviceHandle was NULL
 215 **/
 216 EFI_STATUS
 217 EFIAPI
 218 EfiShellGetDeviceName(
 219   IN EFI_HANDLE DeviceHandle,
 220   IN EFI_SHELL_DEVICE_NAME_FLAGS Flags,
 221   IN CHAR8 *Language,
 222   OUT CHAR16 **BestDeviceName
 223   );
 224
 225 /**
 226   Opens the root directory of a device on a handle
 227
 228   This function opens the root directory of a device and returns a file handle to it.
 229
 230   @param DeviceHandle           The handle of the device that contains the volume.
 231   @param FileHandle             On exit, points to the file handle corresponding to the root directory on the
 232                                 device.
 233
 234   @retval EFI_SUCCESS           Root opened successfully.
 235   @retval EFI_NOT_FOUND         EFI_SIMPLE_FILE_SYSTEM could not be found or the root directory
 236                                 could not be opened.
 237   @retval EFI_VOLUME_CORRUPTED  The data structures in the volume were corrupted.
 238   @retval EFI_DEVICE_ERROR      The device had an error
 239 **/
 240 EFI_STATUS
 241 EFIAPI
 242 EfiShellOpenRootByHandle(
 243   IN EFI_HANDLE DeviceHandle,
 244   OUT SHELL_FILE_HANDLE *FileHandle
 245   );
 246
 247 /**
 248   Opens the root directory of a device.
 249
 250   This function opens the root directory of a device and returns a file handle to it.
 251
 252   @param DevicePath             Points to the device path corresponding to the device where the
 253                                 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL is installed.
 254   @param FileHandle             On exit, points to the file handle corresponding to the root directory on the
 255                                 device.
 256
 257   @retval EFI_SUCCESS           Root opened successfully.
 258   @retval EFI_NOT_FOUND         EFI_SIMPLE_FILE_SYSTEM could not be found or the root directory
 259                                 could not be opened.
 260   @retval EFI_VOLUME_CORRUPTED  The data structures in the volume were corrupted.
 261   @retval EFI_DEVICE_ERROR      The device had an error
 262 **/
 263 EFI_STATUS
 264 EFIAPI
 265 EfiShellOpenRoot(
 266   IN EFI_DEVICE_PATH_PROTOCOL *DevicePath,
 267   OUT SHELL_FILE_HANDLE *FileHandle
 268   );
 269
 270 /**
 271   Returns whether any script files are currently being processed.
 272
 273   @retval TRUE                 There is at least one script file active.
 274   @retval FALSE                No script files are active now.
 275
 276 **/
 277 BOOLEAN
 278 EFIAPI
 279 EfiShellBatchIsActive (
 280   VOID
 281   );
 282
 283 /**
 284   Worker function to open a file based on a device path.  this will open the root
 285   of the volume and then traverse down to the file itself.
 286
 287   @param DevicePath2                 Device Path of the file
 288   @param FileHandle               Pointer to the file upon a successful return
 289   @param OpenMode                 mode to open file in.
 290   @param Attributes               the File Attributes to use when creating a new file
 291
 292   @retval EFI_SUCCESS             the file is open and FileHandle is valid
 293   @retval EFI_UNSUPPORTED         the device path cotained non-path elements
 294   @retval other                   an error ocurred.
 295 **/
 296 EFI_STATUS
 297 EFIAPI
 298 InternalOpenFileDevicePath(
 299   IN OUT EFI_DEVICE_PATH_PROTOCOL *DevicePath2,
 300   OUT SHELL_FILE_HANDLE             *FileHandle,
 301   IN UINT64                       OpenMode,
 302   IN UINT64                       Attributes OPTIONAL
 303   );
 304
 305 /**
 306   Creates a file or directory by name.
 307
 308   This function creates an empty new file or directory with the specified attributes and
 309   returns the new file's handle. If the file already exists and is read-only, then
 310   EFI_INVALID_PARAMETER will be returned.
 311
 312   If the file already existed, it is truncated and its attributes updated. If the file is
 313   created successfully, the FileHandle is the file's handle, else, the FileHandle is NULL.
 314
 315   If the file name begins with >v, then the file handle which is returned refers to the
 316   shell environment variable with the specified name. If the shell environment variable
 317   already exists and is non-volatile then EFI_INVALID_PARAMETER is returned.
 318
 319   @param FileName           Pointer to NULL-terminated file path
 320   @param FileAttribs        The new file's attrbiutes.  the different attributes are
 321                             described in EFI_FILE_PROTOCOL.Open().
 322   @param FileHandle         On return, points to the created file handle or directory's handle
 323
 324   @retval EFI_SUCCESS       The file was opened.  FileHandle points to the new file's handle.
 325   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
 326   @retval EFI_UNSUPPORTED   could not open the file path
 327   @retval EFI_NOT_FOUND     the specified file could not be found on the devide, or could not
 328                             file the file system on the device.
 329   @retval EFI_NO_MEDIA      the device has no medium.
 330   @retval EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no
 331                             longer supported.
 332   @retval EFI_DEVICE_ERROR The device reported an error or can't get the file path according
 333                             the DirName.
 334   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 335   @retval EFI_WRITE_PROTECTED An attempt was made to create a file, or open a file for write
 336                             when the media is write-protected.
 337   @retval EFI_ACCESS_DENIED The service denied access to the file.
 338   @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.
 339   @retval EFI_VOLUME_FULL   The volume is full.
 340 **/
 341 EFI_STATUS
 342 EFIAPI
 343 EfiShellCreateFile(
 344   IN CONST CHAR16     *FileName,
 345   IN UINT64           FileAttribs,
 346   OUT SHELL_FILE_HANDLE *FileHandle
 347   );
 348
 349 /**
 350   Opens a file or a directory by file name.
 351
 352   This function opens the specified file in the specified OpenMode and returns a file
 353   handle.
 354   If the file name begins with >v, then the file handle which is returned refers to the
 355   shell environment variable with the specified name. If the shell environment variable
 356   exists, is non-volatile and the OpenMode indicates EFI_FILE_MODE_WRITE, then
 357   EFI_INVALID_PARAMETER is returned.
 358
 359   If the file name is >i, then the file handle which is returned refers to the standard
 360   input. If the OpenMode indicates EFI_FILE_MODE_WRITE, then EFI_INVALID_PARAMETER
 361   is returned.
 362
 363   If the file name is >o, then the file handle which is returned refers to the standard
 364   output. If the OpenMode indicates EFI_FILE_MODE_READ, then EFI_INVALID_PARAMETER
 365   is returned.
 366
 367   If the file name is >e, then the file handle which is returned refers to the standard
 368   error. If the OpenMode indicates EFI_FILE_MODE_READ, then EFI_INVALID_PARAMETER
 369   is returned.
 370
 371   If the file name is NUL, then the file handle that is returned refers to the standard NUL
 372   file. If the OpenMode indicates EFI_FILE_MODE_READ, then EFI_INVALID_PARAMETER is
 373   returned.
 374
 375   If return EFI_SUCCESS, the FileHandle is the opened file's handle, else, the
 376   FileHandle is NULL.
 377
 378   @param FileName               Points to the NULL-terminated UCS-2 encoded file name.
 379   @param FileHandle             On return, points to the file handle.
 380   @param OpenMode               File open mode. Either EFI_FILE_MODE_READ or
 381                                 EFI_FILE_MODE_WRITE from section 12.4 of the UEFI
 382                                 Specification.
 383   @retval EFI_SUCCESS           The file was opened. FileHandle has the opened file's handle.
 384   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. FileHandle is NULL.
 385   @retval EFI_UNSUPPORTED       Could not open the file path. FileHandle is NULL.
 386   @retval EFI_NOT_FOUND         The specified file could not be found on the device or the file
 387                                 system could not be found on the device. FileHandle is NULL.
 388   @retval EFI_NO_MEDIA          The device has no medium. FileHandle is NULL.
 389   @retval EFI_MEDIA_CHANGED     The device has a different medium in it or the medium is no
 390                                 longer supported. FileHandle is NULL.
 391   @retval EFI_DEVICE_ERROR      The device reported an error or can't get the file path according
 392                                 the FileName. FileHandle is NULL.
 393   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted. FileHandle is NULL.
 394   @retval EFI_WRITE_PROTECTED   An attempt was made to create a file, or open a file for write
 395                                 when the media is write-protected. FileHandle is NULL.
 396   @retval EFI_ACCESS_DENIED     The service denied access to the file. FileHandle is NULL.
 397   @retval EFI_OUT_OF_RESOURCES  Not enough resources were available to open the file. FileHandle
 398                                 is NULL.
 399   @retval EFI_VOLUME_FULL       The volume is full. FileHandle is NULL.
 400 **/
 401 EFI_STATUS
 402 EFIAPI
 403 EfiShellOpenFileByName(
 404   IN CONST CHAR16 *FileName,
 405   OUT SHELL_FILE_HANDLE *FileHandle,
 406   IN UINT64 OpenMode
 407   );
 408
 409 /**
 410   Deletes the file specified by the file name.
 411
 412   This function deletes a file.
 413
 414   @param FileName                 Points to the NULL-terminated file name.
 415
 416   @retval EFI_SUCCESS             The file was closed and deleted, and the handle was closed.
 417   @retval EFI_WARN_DELETE_FAILURE The handle was closed but the file was not deleted.
 418   @sa EfiShellCreateFile
 419   @sa FileHandleDelete
 420 **/
 421 EFI_STATUS
 422 EFIAPI
 423 EfiShellDeleteFileByName(
 424   IN CONST CHAR16 *FileName
 425   );
 426
 427 /**
 428   Disables the page break output mode.
 429 **/
 430 VOID
 431 EFIAPI
 432 EfiShellDisablePageBreak (
 433   VOID
 434   );
 435
 436 /**
 437   Enables the page break output mode.
 438 **/
 439 VOID
 440 EFIAPI
 441 EfiShellEnablePageBreak (
 442   VOID
 443   );
 444
 445 /**
 446   internal worker function to run a command via Device Path
 447
 448   @param ParentImageHandle      A handle of the image that is executing the specified
 449                                 command line.
 450   @param DevicePath             device path of the file to execute
 451   @param CommandLine            Points to the NULL-terminated UCS-2 encoded string
 452                                 containing the command line. If NULL then the command-
 453                                 line will be empty.
 454   @param Environment            Points to a NULL-terminated array of environment
 455                                 variables with the format 'x=y', where x is the
 456                                 environment variable name and y is the value. If this
 457                                 is NULL, then the current shell environment is used.
 458   @param[out] StartImageStatus  Returned status from gBS->StartImage.
 459
 460   @retval EFI_SUCCESS       The command executed successfully. The  status code
 461                             returned by the command is pointed to by StatusCode.
 462   @retval EFI_INVALID_PARAMETER The parameters are invalid.
 463   @retval EFI_OUT_OF_RESOURCES Out of resources.
 464   @retval EFI_UNSUPPORTED   Nested shell invocations are not allowed.
 465 **/
 466 EFI_STATUS
 467 EFIAPI
 468 InternalShellExecuteDevicePath(
 469   IN CONST EFI_HANDLE               *ParentImageHandle,
 470   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
 471   IN CONST CHAR16                   *CommandLine OPTIONAL,
 472   IN CONST CHAR16                   **Environment OPTIONAL,
 473   OUT EFI_STATUS                    *StartImageStatus OPTIONAL
 474   );
 475
 476 /**
 477   Execute the command line.
 478
 479   This function creates a nested instance of the shell and executes the specified
 480   command (CommandLine) with the specified environment (Environment). Upon return,
 481   the status code returned by the specified command is placed in StatusCode.
 482
 483   If Environment is NULL, then the current environment is used and all changes made
 484   by the commands executed will be reflected in the current environment. If the
 485   Environment is non-NULL, then the changes made will be discarded.
 486
 487   The CommandLine is executed from the current working directory on the current
 488   device.
 489
 490   @param ParentImageHandle      A handle of the image that is executing the specified
 491                                 command line.
 492   @param CommandLine            Points to the NULL-terminated UCS-2 encoded string
 493                                 containing the command line. If NULL then the command-
 494                                 line will be empty.
 495   @param Environment            Points to a NULL-terminated array of environment
 496                                 variables with the format 'x=y', where x is the
 497                                 environment variable name and y is the value. If this
 498                                 is NULL, then the current shell environment is used.
 499   @param StatusCode             Points to the status code returned by the command.
 500
 501   @retval EFI_SUCCESS           The command executed successfully. The  status code
 502                                 returned by the command is pointed to by StatusCode.
 503   @retval EFI_INVALID_PARAMETER The parameters are invalid.
 504   @retval EFI_OUT_OF_RESOURCES  Out of resources.
 505   @retval EFI_UNSUPPORTED       Nested shell invocations are not allowed.
 506 **/
 507 EFI_STATUS
 508 EFIAPI
 509 EfiShellExecute(
 510   IN EFI_HANDLE *ParentImageHandle,
 511   IN CHAR16 *CommandLine OPTIONAL,
 512   IN CHAR16 **Environment OPTIONAL,
 513   OUT EFI_STATUS *StatusCode OPTIONAL
 514   );
 515
 516 /**
 517   Utility cleanup function for EFI_SHELL_FILE_INFO objects.
 518
 519   1) frees all pointers (non-NULL)
 520   2) Closes the SHELL_FILE_HANDLE
 521
 522   @param FileListNode     pointer to the list node to free
 523 **/
 524 VOID
 525 EFIAPI
 526 FreeShellFileInfoNode(
 527   IN EFI_SHELL_FILE_INFO *FileListNode
 528   );
 529
 530 /**
 531   Frees the file list.
 532
 533   This function cleans up the file list and any related data structures. It has no
 534   impact on the files themselves.
 535
 536   @param FileList               The file list to free. Type EFI_SHELL_FILE_INFO is
 537                                 defined in OpenFileList()
 538
 539   @retval EFI_SUCCESS           Free the file list successfully.
 540   @retval EFI_INVALID_PARAMETER FileList was NULL or *FileList was NULL;
 541 **/
 542 EFI_STATUS
 543 EFIAPI
 544 EfiShellFreeFileList(
 545   IN EFI_SHELL_FILE_INFO **FileList
 546   );
 547
 548 /**
 549   Deletes the duplicate file names files in the given file list.
 550
 551   This function deletes the reduplicate files in the given file list.
 552
 553   @param FileList               A pointer to the first entry in the file list.
 554
 555   @retval EFI_SUCCESS           Always success.
 556   @retval EFI_INVALID_PARAMETER FileList was NULL or *FileList was NULL;
 557 **/
 558 EFI_STATUS
 559 EFIAPI
 560 EfiShellRemoveDupInFileList(
 561   IN EFI_SHELL_FILE_INFO **FileList
 562   );
 563
 564 /**
 565   Allocates and populates a EFI_SHELL_FILE_INFO structure.  if any memory operation
 566   failed it will return NULL.
 567
 568   @param[in] BasePath         the Path to prepend onto filename for FullPath
 569   @param[in] Status           Status member initial value.
 570   @param[in] FileName         FileName member initial value.
 571   @param[in] Handle           Handle member initial value.
 572   @param[in] Info             Info struct to copy.
 573
 574 **/
 575 EFI_SHELL_FILE_INFO *
 576 EFIAPI
 577 CreateAndPopulateShellFileInfo(
 578   IN CONST CHAR16 *BasePath,
 579   IN CONST EFI_STATUS Status,
 580   IN CONST CHAR16 *FileName,
 581   IN CONST SHELL_FILE_HANDLE Handle,
 582   IN CONST EFI_FILE_INFO *Info
 583   );
 584
 585 /**
 586   Find all files in a specified directory.
 587
 588   @param FileDirHandle     Handle of the directory to search.
 589   @param FileList          On return, points to the list of files in the directory
 590                            or NULL if there are no files in the directory.
 591
 592   @retval EFI_SUCCESS           File information was returned successfully.
 593   @retval EFI_VOLUME_CORRUPTED  The file system structures have been corrupted.
 594   @retval EFI_DEVICE_ERROR      The device reported an error.
 595   @retval EFI_NO_MEDIA          The device media is not present.
 596   @retval EFI_INVALID_PARAMETER The FileDirHandle was not a directory.
 597 **/
 598 EFI_STATUS
 599 EFIAPI
 600 EfiShellFindFilesInDir(
 601   IN SHELL_FILE_HANDLE FileDirHandle,
 602   OUT EFI_SHELL_FILE_INFO **FileList
 603   );
 604
 605 /**
 606   Find files that match a specified pattern.
 607
 608   This function searches for all files and directories that match the specified
 609   FilePattern. The FilePattern can contain wild-card characters. The resulting file
 610   information is placed in the file list FileList.
 611
 612   Wildcards are processed
 613   according to the rules specified in UEFI Shell 2.0 spec section 3.7.1.
 614
 615   The files in the file list are not opened. The OpenMode field is set to 0 and the FileInfo
 616   field is set to NULL.
 617
 618   if *FileList is not NULL then it must be a pre-existing and properly initialized list.
 619
 620   @param FilePattern      Points to a NULL-terminated shell file path, including wildcards.
 621   @param FileList         On return, points to the start of a file list containing the names
 622                           of all matching files or else points to NULL if no matching files
 623                           were found.  only on a EFI_SUCCESS return will; this be non-NULL.
 624
 625   @retval EFI_SUCCESS           Files found.  FileList is a valid list.
 626   @retval EFI_NOT_FOUND         No files found.
 627   @retval EFI_NO_MEDIA          The device has no media
 628   @retval EFI_DEVICE_ERROR      The device reported an error
 629   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted
 630 **/
 631 EFI_STATUS
 632 EFIAPI
 633 EfiShellFindFiles(
 634   IN CONST CHAR16 *FilePattern,
 635   OUT EFI_SHELL_FILE_INFO **FileList
 636   );
 637
 638 /**
 639   Opens the files that match the path specified.
 640
 641   This function opens all of the files specified by Path. Wildcards are processed
 642   according to the rules specified in UEFI Shell 2.0 spec section 3.7.1. Each
 643   matching file has an EFI_SHELL_FILE_INFO structure created in a linked list.
 644
 645   @param Path                   A pointer to the path string.
 646   @param OpenMode               Specifies the mode used to open each file, EFI_FILE_MODE_READ or
 647                                 EFI_FILE_MODE_WRITE.
 648   @param FileList               Points to the start of a list of files opened.
 649
 650   @retval EFI_SUCCESS           Create the file list successfully.
 651   @return Others                Can't create the file list.
 652 **/
 653 EFI_STATUS
 654 EFIAPI
 655 EfiShellOpenFileList(
 656   IN CHAR16 *Path,
 657   IN UINT64 OpenMode,
 658   IN OUT EFI_SHELL_FILE_INFO **FileList
 659   );
 660
 661 /**
 662   Gets the environment variable.
 663
 664   This function returns the current value of the specified environment variable.
 665
 666   @param Name                   A pointer to the environment variable name
 667
 668   @retval !=NULL                The environment variable's value. The returned
 669                                 pointer does not need to be freed by the caller.
 670   @retval NULL                  The environment variable doesn't exist.
 671 **/
 672 CONST CHAR16 *
 673 EFIAPI
 674 EfiShellGetEnv(
 675   IN CONST CHAR16 *Name
 676   );
 677
 678 /**
 679   Sets the environment variable.
 680
 681   This function changes the current value of the specified environment variable. If the
 682   environment variable exists and the Value is an empty string, then the environment
 683   variable is deleted. If the environment variable exists and the Value is not an empty
 684   string, then the value of the environment variable is changed. If the environment
 685   variable does not exist and the Value is an empty string, there is no action. If the
 686   environment variable does not exist and the Value is a non-empty string, then the
 687   environment variable is created and assigned the specified value.
 688
 689   For a description of volatile and non-volatile environment variables, see UEFI Shell
 690   2.0 specification section 3.6.1.
 691
 692   @param Name                   Points to the NULL-terminated environment variable name.
 693   @param Value                  Points to the NULL-terminated environment variable value. If the value is an
 694                                 empty string then the environment variable is deleted.
 695   @param Volatile               Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).
 696
 697   @retval EFI_SUCCESS           The environment variable was successfully updated.
 698 **/
 699 EFI_STATUS
 700 EFIAPI
 701 EfiShellSetEnv(
 702   IN CONST CHAR16 *Name,
 703   IN CONST CHAR16 *Value,
 704   IN BOOLEAN Volatile
 705   );
 706
 707 /**
 708   Returns the current directory on the specified device.
 709
 710   If FileSystemMapping is NULL, it returns the current working directory. If the
 711   FileSystemMapping is not NULL, it returns the current directory associated with the
 712   FileSystemMapping. In both cases, the returned name includes the file system
 713   mapping (i.e. fs0:\current-dir).
 714
 715   @param FileSystemMapping      A pointer to the file system mapping. If NULL,
 716                                 then the current working directory is returned.
 717
 718   @retval !=NULL                The current directory.
 719   @retval NULL                  Current directory does not exist.
 720 **/
 721 CONST CHAR16 *
 722 EFIAPI
 723 EfiShellGetCurDir(
 724   IN CONST CHAR16 *FileSystemMapping OPTIONAL
 725   );
 726
 727 /**
 728   Changes the current directory on the specified device.
 729
 730   If the FileSystem is NULL, and the directory Dir does not contain a file system's
 731   mapped name, this function changes the current working directory. If FileSystem is
 732   NULL and the directory Dir contains a mapped name, then the current file system and
 733   the current directory on that file system are changed.
 734
 735   If FileSystem is not NULL, and Dir is NULL, then this changes the current working file
 736   system.
 737
 738   If FileSystem is not NULL and Dir is not NULL, then this function changes the current
 739   directory on the specified file system.
 740
 741   If the current working directory or the current working file system is changed then the
 742   %cwd% environment variable will be updated
 743
 744   @param FileSystem             A pointer to the file system's mapped name. If NULL, then the current working
 745                                 directory is changed.
 746   @param Dir                    Points to the NULL-terminated directory on the device specified by FileSystem.
 747
 748   @retval EFI_SUCCESS           The operation was sucessful
 749 **/
 750 EFI_STATUS
 751 EFIAPI
 752 EfiShellSetCurDir(
 753   IN CONST CHAR16 *FileSystem OPTIONAL,
 754   IN CONST CHAR16 *Dir
 755   );
 756
 757 /**
 758   Return help information about a specific command.
 759
 760   This function returns the help information for the specified command. The help text
 761   can be internal to the shell or can be from a UEFI Shell manual page.
 762
 763   If Sections is specified, then each section name listed will be compared in a casesensitive
 764   manner, to the section names described in Appendix B. If the section exists,
 765   it will be appended to the returned help text. If the section does not exist, no
 766   information will be returned. If Sections is NULL, then all help text information
 767   available will be returned.
 768
 769   @param Command                Points to the NULL-terminated UEFI Shell command name.
 770   @param Sections               Points to the NULL-terminated comma-delimited
 771                                 section names to return. If NULL, then all
 772                                 sections will be returned.
 773   @param HelpText               On return, points to a callee-allocated buffer
 774                                 containing all specified help text.
 775
 776   @retval EFI_SUCCESS           The help text was returned.
 777   @retval EFI_OUT_OF_RESOURCES  The necessary buffer could not be allocated to hold the
 778                                 returned help text.
 779   @retval EFI_INVALID_PARAMETER HelpText is NULL
 780   @retval EFI_NOT_FOUND         There is no help text available for Command.
 781 **/
 782 EFI_STATUS
 783 EFIAPI
 784 EfiShellGetHelpText(
 785   IN CONST CHAR16 *Command,
 786   IN CONST CHAR16 *Sections OPTIONAL,
 787   OUT CHAR16 **HelpText
 788   );
 789
 790 /**
 791   Gets the enable status of the page break output mode.
 792
 793   User can use this function to determine current page break mode.
 794
 795   @retval TRUE                  The page break output mode is enabled
 796   @retval FALSE                 The page break output mode is disabled
 797 **/
 798 BOOLEAN
 799 EFIAPI
 800 EfiShellGetPageBreak(
 801   VOID
 802   );
 803
 804 /**
 805   Judges whether the active shell is the root shell.
 806
 807   This function makes the user to know that whether the active Shell is the root shell.
 808
 809   @retval TRUE                  The active Shell is the root Shell.
 810   @retval FALSE                 The active Shell is NOT the root Shell.
 811 **/
 812 BOOLEAN
 813 EFIAPI
 814 EfiShellIsRootShell(
 815   VOID
 816   );
 817
 818 /**
 819   This function returns the command associated with a alias or a list of all
 820   alias'.
 821
 822   @param[in] Command            Points to the NULL-terminated shell alias.
 823                                 If this parameter is NULL, then all
 824                                 aliases will be returned in ReturnedData.
 825   @param[out] Volatile          upon return of a single command if TRUE indicates
 826                                 this is stored in a volatile fashion.  FALSE otherwise.
 827   @return                       If Alias is not NULL, it will return a pointer to
 828                                 the NULL-terminated command for that alias.
 829                                 If Alias is NULL, ReturnedData points to a ';'
 830                                 delimited list of alias (e.g.
 831                                 ReturnedData = "dir;del;copy;mfp") that is NULL-terminated.
 832   @retval NULL                  an error ocurred
 833   @retval NULL                  Alias was not a valid Alias
 834 **/
 835 CONST CHAR16 *
 836 EFIAPI
 837 EfiShellGetAlias(
 838   IN  CONST CHAR16 *Command,
 839   OUT BOOLEAN      *Volatile OPTIONAL
 840   );
 841
 842 /**
 843   Changes a shell command alias.
 844
 845   This function creates an alias for a shell command or if Alias is NULL it will delete an existing alias.
 846
 847   this function does not check for built in alias'.
 848
 849   @param[in] Command            Points to the NULL-terminated shell command or existing alias.
 850   @param[in] Alias              Points to the NULL-terminated alias for the shell command. If this is NULL, and
 851                                 Command refers to an alias, that alias will be deleted.
 852   @param[in] Volatile           if TRUE the Alias being set will be stored in a volatile fashion.  if FALSE the
 853                                 Alias being set will be stored in a non-volatile fashion.
 854
 855   @retval EFI_SUCCESS           Alias created or deleted successfully.
 856   @retval EFI_NOT_FOUND         the Alias intended to be deleted was not found
 857 **/
 858 EFI_STATUS
 859 EFIAPI
 860 InternalSetAlias(
 861   IN CONST CHAR16 *Command,
 862   IN CONST CHAR16 *Alias OPTIONAL,
 863   IN BOOLEAN Volatile
 864   );
 865
 866 /**
 867   Changes a shell command alias.
 868
 869   This function creates an alias for a shell command or if Alias is NULL it will delete an existing alias.
 870
 871
 872   @param[in] Command            Points to the NULL-terminated shell command or existing alias.
 873   @param[in] Alias              Points to the NULL-terminated alias for the shell command. If this is NULL, and
 874                                 Command refers to an alias, that alias will be deleted.
 875   @param[in] Replace            If TRUE and the alias already exists, then the existing alias will be replaced. If
 876                                 FALSE and the alias already exists, then the existing alias is unchanged and
 877                                 EFI_ACCESS_DENIED is returned.
 878   @param[in] Volatile           if TRUE the Alias being set will be stored in a volatile fashion.  if FALSE the
 879                                 Alias being set will be stored in a non-volatile fashion.
 880
 881   @retval EFI_SUCCESS           Alias created or deleted successfully.
 882   @retval EFI_NOT_FOUND         the Alias intended to be deleted was not found
 883   @retval EFI_ACCESS_DENIED     The alias is a built-in alias or already existed and Replace was set to
 884                                 FALSE.
 885 **/
 886 EFI_STATUS
 887 EFIAPI
 888 EfiShellSetAlias(
 889   IN CONST CHAR16 *Command,
 890   IN CONST CHAR16 *Alias OPTIONAL,
 891   IN BOOLEAN Replace,
 892   IN BOOLEAN Volatile
 893   );
 894
 895 /**
 896   Utility cleanup function for EFI_SHELL_FILE_INFO objects.
 897
 898   1) frees all pointers (non-NULL)
 899   2) Closes the SHELL_FILE_HANDLE
 900
 901   @param FileListNode     pointer to the list node to free
 902 **/
 903 VOID
 904 EFIAPI
 905 InternalFreeShellFileInfoNode(
 906   IN EFI_SHELL_FILE_INFO *FileListNode
 907   );
 908
 909 /**
 910   Internal variable setting function.  Allows for setting of the read only variables.
 911
 912   @param Name                   Points to the NULL-terminated environment variable name.
 913   @param Value                  Points to the NULL-terminated environment variable value. If the value is an
 914                                 empty string then the environment variable is deleted.
 915   @param Volatile               Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).
 916
 917   @retval EFI_SUCCESS           The environment variable was successfully updated.
 918 **/
 919 EFI_STATUS
 920 EFIAPI
 921 InternalEfiShellSetEnv(
 922   IN CONST CHAR16 *Name,
 923   IN CONST CHAR16 *Value,
 924   IN BOOLEAN Volatile
 925   );
 926
 927 /**
 928   Function to start monitoring for CTRL-C using SimpleTextInputEx.  This
 929   feature's enabled state was not known when the shell initially launched.
 930
 931   @retval EFI_SUCCESS           The feature is enabled.
 932   @retval EFI_OUT_OF_RESOURCES  There is not enough mnemory available.
 933 **/
 934 EFI_STATUS
 935 EFIAPI
 936 InernalEfiShellStartMonitor(
 937   VOID
 938   );
 939
 940 /**
 941   Notification function for keystrokes.
 942
 943   @param[in] KeyData    The key that was pressed.
 944
 945   @retval EFI_SUCCESS   The operation was successful.
 946 **/
 947 EFI_STATUS
 948 EFIAPI
 949 NotificationFunction(
 950   IN EFI_KEY_DATA *KeyData
 951   );
 952 #endif //_SHELL_PROTOCOL_HEADER_
 953