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