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