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