ShellPkg/Include/Library/ShellLib.h

   1 /** @file
   2   Provides interface to shell functionality for shell commands and applications.
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   Copyright 2018 Dell Technologies.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __SHELL_LIB__
  11 #define __SHELL_LIB__
  12
  13 #include <Uefi.h>
  14 #include <Guid/FileInfo.h>
  15 #include <Protocol/SimpleFileSystem.h>
  16 #include <Protocol/LoadedImage.h>
  17 #include <Protocol/EfiShellInterface.h>
  18 #include <Protocol/EfiShellEnvironment2.h>
  19 #include <Protocol/Shell.h>
  20 #include <Protocol/ShellParameters.h>
  21
  22 #define SHELL_FREE_NON_NULL(Pointer)  \
  23   do {                                \
  24     if ((Pointer) != NULL) {          \
  25       FreePool((Pointer));            \
  26       (Pointer) = NULL;               \
  27     }                                 \
  28   } while(FALSE)
  29
  30 extern EFI_SHELL_PARAMETERS_PROTOCOL  *gEfiShellParametersProtocol;
  31 extern EFI_SHELL_PROTOCOL             *gEfiShellProtocol;
  32
  33 /**
  34   Return a clean, fully-qualified version of an input path.  If the return value
  35   is non-NULL the caller must free the memory when it is no longer needed.
  36
  37   If asserts are disabled, and if the input parameter is NULL, NULL is returned.
  38
  39   If there is not enough memory available to create the fully-qualified path or
  40   a copy of the input path, NULL is returned.
  41
  42   If there is no working directory, a clean copy of Path is returned.
  43
  44   Otherwise, the current file system or working directory (as appropriate) is
  45   prepended to Path and the resulting path is cleaned and returned.
  46
  47   NOTE: If the input path is an empty string, then the current working directory
  48   (if it exists) is returned.  In other words, an empty input path is treated
  49   exactly the same as ".".
  50
  51   @param[in] Path  A pointer to some file or directory path.
  52
  53   @retval NULL          The input path is NULL or out of memory.
  54
  55   @retval non-NULL      A pointer to a clean, fully-qualified version of Path.
  56                         If there is no working directory, then a pointer to a
  57                         clean, but not necessarily fully-qualified version of
  58                         Path.  The caller must free this memory when it is no
  59                         longer needed.
  60 **/
  61 CHAR16 *
  62 EFIAPI
  63 FullyQualifyPath (
  64   IN     CONST CHAR16  *Path
  65   );
  66
  67 /**
  68   This function will retrieve the information about the file for the handle
  69   specified and store it in allocated pool memory.
  70
  71   This function allocates a buffer to store the file's information. It is the
  72   caller's responsibility to free the buffer.
  73
  74   @param[in] FileHandle         The file handle of the file for which information is
  75                                 being requested.
  76
  77   @retval NULL                  Information could not be retrieved.
  78
  79   @return                       The information about the file.
  80 **/
  81 EFI_FILE_INFO *
  82 EFIAPI
  83 ShellGetFileInfo (
  84   IN SHELL_FILE_HANDLE  FileHandle
  85   );
  86
  87 /**
  88   This function sets the information about the file for the opened handle
  89   specified.
  90
  91   @param[in]  FileHandle        The file handle of the file for which information
  92                                 is being set.
  93
  94   @param[in]  FileInfo          The information to set.
  95
  96   @retval EFI_SUCCESS           The information was set.
  97   @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid.
  98   @retval EFI_UNSUPPORTED       The FileHandle does not support FileInfo.
  99   @retval EFI_NO_MEDIA          The device has no medium.
 100   @retval EFI_DEVICE_ERROR      The device reported an error.
 101   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 102   @retval EFI_WRITE_PROTECTED   The file or medium is write protected.
 103   @retval EFI_ACCESS_DENIED     The file was opened read only.
 104   @retval EFI_VOLUME_FULL       The volume is full.
 105 **/
 106 EFI_STATUS
 107 EFIAPI
 108 ShellSetFileInfo (
 109   IN SHELL_FILE_HANDLE  FileHandle,
 110   IN EFI_FILE_INFO      *FileInfo
 111   );
 112
 113 /**
 114   This function will open a file or directory referenced by DevicePath.
 115
 116   This function opens a file with the open mode according to the file path. The
 117   Attributes is valid only for EFI_FILE_MODE_CREATE.
 118
 119   @param[in, out]  FilePath      On input, the device path to the file.  On output,
 120                                  the remaining device path.
 121   @param[out]   FileHandle       Pointer to the file handle.
 122   @param[in]    OpenMode         The mode to open the file with.
 123   @param[in]    Attributes       The file's file attributes.
 124
 125   @retval EFI_SUCCESS         The information was set.
 126   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
 127   @retval EFI_UNSUPPORTED       Could not open the file path.
 128   @retval EFI_NOT_FOUND         The specified file could not be found on the
 129                                 device or the file system could not be found on
 130                                 the device.
 131   @retval EFI_NO_MEDIA          The device has no medium.
 132   @retval EFI_MEDIA_CHANGED     The device has a different medium in it or the
 133                                 medium is no longer supported.
 134   @retval EFI_DEVICE_ERROR      The device reported an error.
 135   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 136   @retval EFI_WRITE_PROTECTED   The file or medium is write protected.
 137   @retval EFI_ACCESS_DENIED     The file was opened read only.
 138   @retval EFI_OUT_OF_RESOURCES  Not enough resources were available to open the
 139                                 file.
 140   @retval EFI_VOLUME_FULL       The volume is full.
 141 **/
 142 EFI_STATUS
 143 EFIAPI
 144 ShellOpenFileByDevicePath (
 145   IN OUT EFI_DEVICE_PATH_PROTOCOL  **FilePath,
 146   OUT SHELL_FILE_HANDLE            *FileHandle,
 147   IN UINT64                        OpenMode,
 148   IN UINT64                        Attributes
 149   );
 150
 151 /**
 152   This function will open a file or directory referenced by filename.
 153
 154   If return is EFI_SUCCESS, the Filehandle is the opened file's handle;
 155   otherwise, the Filehandle is NULL. Attributes is valid only for
 156   EFI_FILE_MODE_CREATE.
 157
 158   @param[in] FileName           The pointer to file name.
 159   @param[out] FileHandle        The pointer to the file handle.
 160   @param[in] OpenMode           The mode to open the file with.
 161   @param[in] Attributes         The file's file attributes.
 162
 163   @retval EFI_SUCCESS         The information was set.
 164   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
 165   @retval EFI_UNSUPPORTED       Could not open the file path.
 166   @retval EFI_NOT_FOUND         The specified file could not be found on the
 167                                 device or the file system could not be found
 168                                 on the device.
 169   @retval EFI_NO_MEDIA          The device has no medium.
 170   @retval EFI_MEDIA_CHANGED     The device has a different medium in it or the
 171                                 medium is no longer supported.
 172   @retval EFI_DEVICE_ERROR      The device reported an error.
 173   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 174   @retval EFI_WRITE_PROTECTED   The file or medium is write protected.
 175   @retval EFI_ACCESS_DENIED     The file was opened read only.
 176   @retval EFI_OUT_OF_RESOURCES  Not enough resources were available to open the
 177                                 file.
 178   @retval EFI_VOLUME_FULL       The volume is full.
 179 **/
 180 EFI_STATUS
 181 EFIAPI
 182 ShellOpenFileByName (
 183   IN CONST CHAR16        *FileName,
 184   OUT SHELL_FILE_HANDLE  *FileHandle,
 185   IN UINT64              OpenMode,
 186   IN UINT64              Attributes
 187   );
 188
 189 /**
 190   This function creates a directory.
 191
 192   If return is EFI_SUCCESS, the Filehandle is the opened directory's handle;
 193   otherwise, the Filehandle is NULL. If the directory already existed, this
 194   function opens the existing directory.
 195
 196   @param[in]  DirectoryName     The pointer to Directory name.
 197   @param[out] FileHandle        The pointer to the file handle.
 198
 199   @retval EFI_SUCCESS         The information was set.
 200   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
 201   @retval EFI_UNSUPPORTED       Could not open the file path.
 202   @retval EFI_NOT_FOUND         The specified file could not be found on the
 203                                 device, or the file system could not be found
 204                                 on the device.
 205   @retval EFI_NO_MEDIA          The device has no medium.
 206   @retval EFI_MEDIA_CHANGED     The device has a different medium in it or the
 207                                 medium is no longer supported.
 208   @retval EFI_DEVICE_ERROR      The device reported an error.
 209   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 210   @retval EFI_WRITE_PROTECTED   The file or medium is write protected.
 211   @retval EFI_ACCESS_DENIED     The file was opened read only.
 212   @retval EFI_OUT_OF_RESOURCES  Not enough resources were available to open the
 213                                 file.
 214   @retval EFI_VOLUME_FULL       The volume is full.
 215 **/
 216 EFI_STATUS
 217 EFIAPI
 218 ShellCreateDirectory (
 219   IN CONST CHAR16        *DirectoryName,
 220   OUT SHELL_FILE_HANDLE  *FileHandle
 221   );
 222
 223 /**
 224   This function reads information from an opened file.
 225
 226   If FileHandle is not a directory, the function reads the requested number of
 227   bytes from the file at the file's current position and returns them in Buffer.
 228   If the read goes beyond the end of the file, the read length is truncated to the
 229   end of the file. The file's current position is increased by the number of bytes
 230   returned.  If FileHandle is a directory, the function reads the directory entry
 231   at the file's current position and returns the entry in Buffer. If the Buffer
 232   is not large enough to hold the current directory entry, then
 233   EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated.
 234   BufferSize is set to be the size of the buffer needed to read the entry. On
 235   success, the current position is updated to the next directory entry. If there
 236   are no more directory entries, the read returns a zero-length buffer.
 237   EFI_FILE_INFO is the structure returned as the directory entry.
 238
 239   @param[in] FileHandle          The opened file handle.
 240   @param[in, out] ReadSize       On input the size of buffer in bytes.  On return
 241                                  the number of bytes written.
 242   @param[out] Buffer             The buffer to put read data into.
 243
 244   @retval EFI_SUCCESS           Data was read.
 245   @retval EFI_NO_MEDIA          The device has no media.
 246   @retval EFI_DEVICE_ERROR      The device reported an error.
 247   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 248   @retval EFI_BUFFER_TO_SMALL   Buffer is too small. ReadSize contains required
 249                                 size.
 250
 251 **/
 252 EFI_STATUS
 253 EFIAPI
 254 ShellReadFile (
 255   IN SHELL_FILE_HANDLE  FileHandle,
 256   IN OUT UINTN          *ReadSize,
 257   OUT VOID              *Buffer
 258   );
 259
 260 /**
 261   Write data to a file.
 262
 263   This function writes the specified number of bytes to the file at the current
 264   file position. The current file position is advanced the actual number of bytes
 265   written, which is returned in BufferSize. Partial writes only occur when there
 266   has been a data error during the write attempt (such as "volume space full").
 267   The file is automatically grown to hold the data if required. Direct writes to
 268   opened directories are not supported.
 269
 270   @param[in] FileHandle          The opened file for writing.
 271
 272   @param[in, out] BufferSize     On input the number of bytes in Buffer.  On output
 273                                  the number of bytes written.
 274
 275   @param[in] Buffer              The buffer containing data to write is stored.
 276
 277   @retval EFI_SUCCESS           Data was written.
 278   @retval EFI_UNSUPPORTED       Writes to an open directory are not supported.
 279   @retval EFI_NO_MEDIA          The device has no media.
 280   @retval EFI_DEVICE_ERROR      The device reported an error.
 281   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 282   @retval EFI_WRITE_PROTECTED   The device is write-protected.
 283   @retval EFI_ACCESS_DENIED     The file was open for read only.
 284   @retval EFI_VOLUME_FULL       The volume is full.
 285 **/
 286 EFI_STATUS
 287 EFIAPI
 288 ShellWriteFile (
 289   IN SHELL_FILE_HANDLE  FileHandle,
 290   IN OUT UINTN          *BufferSize,
 291   IN VOID               *Buffer
 292   );
 293
 294 /**
 295   Close an open file handle.
 296
 297   This function closes a specified file handle. All "dirty" cached file data is
 298   flushed to the device, and the file is closed. In all cases the handle is
 299   closed.
 300
 301   @param[in] FileHandle           The file handle to close.
 302
 303   @retval EFI_SUCCESS             The file handle was closed sucessfully.
 304   @retval INVALID_PARAMETER       One of the parameters has an invalid value.
 305 **/
 306 EFI_STATUS
 307 EFIAPI
 308 ShellCloseFile (
 309   IN SHELL_FILE_HANDLE  *FileHandle
 310   );
 311
 312 /**
 313   Delete a file and close the handle
 314
 315   This function closes and deletes a file. In all cases the file handle is closed.
 316   If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is
 317   returned, but the handle is still closed.
 318
 319   @param[in] FileHandle             The file handle to delete.
 320
 321   @retval EFI_SUCCESS               The file was closed sucessfully.
 322   @retval EFI_WARN_DELETE_FAILURE   The handle was closed, but the file was not
 323                                     deleted.
 324   @retval INVALID_PARAMETER         One of the parameters has an invalid value.
 325 **/
 326 EFI_STATUS
 327 EFIAPI
 328 ShellDeleteFile (
 329   IN SHELL_FILE_HANDLE  *FileHandle
 330   );
 331
 332 /**
 333   Set the current position in a file.
 334
 335   This function sets the current file position for the handle to the position
 336   supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only
 337   absolute positioning is supported, and moving past the end of the file is
 338   allowed (a subsequent write would grow the file). Moving to position
 339   0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file.
 340   If FileHandle is a directory, the only position that may be set is zero. This
 341   has the effect of starting the read process of the directory entries over.
 342
 343   @param[in] FileHandle         The file handle on which the position is being set.
 344
 345   @param[in] Position           The byte position from the begining of the file.
 346
 347   @retval EFI_SUCCESS           Operation completed sucessfully.
 348   @retval EFI_UNSUPPORTED       The seek request for non-zero is not valid on
 349                                 directories.
 350   @retval INVALID_PARAMETER     One of the parameters has an invalid value.
 351 **/
 352 EFI_STATUS
 353 EFIAPI
 354 ShellSetFilePosition (
 355   IN SHELL_FILE_HANDLE  FileHandle,
 356   IN UINT64             Position
 357   );
 358
 359 /**
 360   Gets a file's current position
 361
 362   This function retrieves the current file position for the file handle. For
 363   directories, the current file position has no meaning outside of the file
 364   system driver and as such the operation is not supported. An error is returned
 365   if FileHandle is a directory.
 366
 367   @param[in] FileHandle         The open file handle on which to get the position.
 368   @param[out] Position          The byte position from the begining of the file.
 369
 370   @retval EFI_SUCCESS           The operation completed sucessfully.
 371   @retval INVALID_PARAMETER     One of the parameters has an invalid value.
 372   @retval EFI_UNSUPPORTED       The request is not valid on directories.
 373 **/
 374 EFI_STATUS
 375 EFIAPI
 376 ShellGetFilePosition (
 377   IN SHELL_FILE_HANDLE  FileHandle,
 378   OUT UINT64            *Position
 379   );
 380
 381 /**
 382   Flushes data on a file
 383
 384   This function flushes all modified data associated with a file to a device.
 385
 386   @param[in] FileHandle         The file handle on which to flush data.
 387
 388   @retval EFI_SUCCESS           The data was flushed.
 389   @retval EFI_NO_MEDIA          The device has no media.
 390   @retval EFI_DEVICE_ERROR      The device reported an error.
 391   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 392   @retval EFI_WRITE_PROTECTED   The file or medium is write protected.
 393   @retval EFI_ACCESS_DENIED     The file was opened for read only.
 394 **/
 395 EFI_STATUS
 396 EFIAPI
 397 ShellFlushFile (
 398   IN SHELL_FILE_HANDLE  FileHandle
 399   );
 400
 401 /** Retrieve first entry from a directory.
 402
 403   This function takes an open directory handle and gets information from the
 404   first entry in the directory.  A buffer is allocated to contain
 405   the information and a pointer to the buffer is returned in *Buffer.  The
 406   caller can use ShellFindNextFile() to get subsequent directory entries.
 407
 408   The buffer will be freed by ShellFindNextFile() when the last directory
 409   entry is read.  Otherwise, the caller must free the buffer, using FreePool,
 410   when finished with it.
 411
 412   @param[in]  DirHandle         The file handle of the directory to search.
 413   @param[out] Buffer            The pointer to the buffer for the file's information.
 414
 415   @retval EFI_SUCCESS           Found the first file.
 416   @retval EFI_NOT_FOUND         Cannot find the directory.
 417   @retval EFI_NO_MEDIA          The device has no media.
 418   @retval EFI_DEVICE_ERROR      The device reported an error.
 419   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 420   @return Others                Status of ShellGetFileInfo, ShellSetFilePosition,
 421                                 or ShellReadFile.
 422
 423   @sa ShellReadFile
 424 **/
 425 EFI_STATUS
 426 EFIAPI
 427 ShellFindFirstFile (
 428   IN      SHELL_FILE_HANDLE  DirHandle,
 429   OUT  EFI_FILE_INFO         **Buffer
 430   );
 431
 432 /** Retrieve next entries from a directory.
 433
 434   To use this function, the caller must first call the ShellFindFirstFile()
 435   function to get the first directory entry.  Subsequent directory entries are
 436   retrieved by using the ShellFindNextFile() function.  This function can
 437   be called several times to get each entry from the directory.  If the call of
 438   ShellFindNextFile() retrieved the last directory entry, the next call of
 439   this function will set *NoFile to TRUE and free the buffer.
 440
 441   @param[in]  DirHandle         The file handle of the directory.
 442   @param[in, out] Buffer        The pointer to buffer for file's information.
 443   @param[in, out] NoFile        The pointer to boolean when last file is found.
 444
 445   @retval EFI_SUCCESS           Found the next file.
 446   @retval EFI_NO_MEDIA          The device has no media.
 447   @retval EFI_DEVICE_ERROR      The device reported an error.
 448   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 449
 450   @sa ShellReadFile
 451 **/
 452 EFI_STATUS
 453 EFIAPI
 454 ShellFindNextFile (
 455   IN      SHELL_FILE_HANDLE  DirHandle,
 456   IN OUT  EFI_FILE_INFO      *Buffer,
 457   IN OUT  BOOLEAN            *NoFile
 458   );
 459
 460 /**
 461   Retrieve the size of a file.
 462
 463   This function extracts the file size info from the FileHandle's EFI_FILE_INFO
 464   data.
 465
 466   @param[in] FileHandle         The file handle from which size is retrieved.
 467   @param[out] Size              The pointer to size.
 468
 469   @retval EFI_SUCCESS           The operation was completed sucessfully.
 470   @retval EFI_DEVICE_ERROR      Cannot access the file.
 471 **/
 472 EFI_STATUS
 473 EFIAPI
 474 ShellGetFileSize (
 475   IN SHELL_FILE_HANDLE  FileHandle,
 476   OUT UINT64            *Size
 477   );
 478
 479 /**
 480   Retrieves the status of the break execution flag
 481
 482   This function is useful to check whether the application is being asked to halt by the shell.
 483
 484   @retval TRUE                  The execution break is enabled.
 485   @retval FALSE                 The execution break is not enabled.
 486 **/
 487 BOOLEAN
 488 EFIAPI
 489 ShellGetExecutionBreakFlag (
 490   VOID
 491   );
 492
 493 /**
 494   Return the value of an environment variable.
 495
 496   This function gets the value of the environment variable set by the
 497   ShellSetEnvironmentVariable function.
 498
 499   @param[in] EnvKey             The key name of the environment variable.
 500
 501   @retval NULL                  The named environment variable does not exist.
 502   @return != NULL               The pointer to the value of the environment variable.
 503 **/
 504 CONST CHAR16 *
 505 EFIAPI
 506 ShellGetEnvironmentVariable (
 507   IN CONST CHAR16  *EnvKey
 508   );
 509
 510 /**
 511   Set the value of an environment variable.
 512
 513   This function changes the current value of the specified environment variable. If the
 514   environment variable exists and the Value is an empty string, then the environment
 515   variable is deleted. If the environment variable exists and the Value is not an empty
 516   string, then the value of the environment variable is changed. If the environment
 517   variable does not exist and the Value is an empty string, there is no action. If the
 518   environment variable does not exist and the Value is a non-empty string, then the
 519   environment variable is created and assigned the specified value.
 520
 521   This is not supported pre-UEFI Shell 2.0.
 522
 523   @param[in] EnvKey             The key name of the environment variable.
 524   @param[in] EnvVal             The Value of the environment variable
 525   @param[in] Volatile           Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).
 526
 527   @retval EFI_SUCCESS           The operation completed sucessfully
 528   @retval EFI_UNSUPPORTED       This operation is not allowed in pre-UEFI 2.0 Shell environments.
 529 **/
 530 EFI_STATUS
 531 EFIAPI
 532 ShellSetEnvironmentVariable (
 533   IN CONST CHAR16  *EnvKey,
 534   IN CONST CHAR16  *EnvVal,
 535   IN BOOLEAN       Volatile
 536   );
 537
 538 /**
 539   Cause the shell to parse and execute a command line.
 540
 541   This function creates a nested instance of the shell and executes the specified
 542   command (CommandLine) with the specified environment (Environment). Upon return,
 543   the status code returned by the specified command is placed in StatusCode.
 544   If Environment is NULL, then the current environment is used and all changes made
 545   by the commands executed will be reflected in the current environment. If the
 546   Environment is non-NULL, then the changes made will be discarded.
 547   The CommandLine is executed from the current working directory on the current
 548   device.
 549
 550   The EnvironmentVariables and Status parameters are ignored in a pre-UEFI Shell 2.0
 551   environment.  The values pointed to by the parameters will be unchanged by the
 552   ShellExecute() function.  The Output parameter has no effect in a
 553   UEFI Shell 2.0 environment.
 554
 555   @param[in] ParentHandle         The parent image starting the operation.
 556   @param[in] CommandLine          The pointer to a NULL terminated command line.
 557   @param[in] Output               True to display debug output.  False to hide it.
 558   @param[in] EnvironmentVariables Optional pointer to array of environment variables
 559                                   in the form "x=y".  If NULL, the current set is used.
 560   @param[out] Status              The status of the run command line.
 561
 562   @retval EFI_SUCCESS             The operation completed sucessfully.  Status
 563                                   contains the status code returned.
 564   @retval EFI_INVALID_PARAMETER   A parameter contains an invalid value.
 565   @retval EFI_OUT_OF_RESOURCES    Out of resources.
 566   @retval EFI_UNSUPPORTED         The operation is not allowed.
 567 **/
 568 EFI_STATUS
 569 EFIAPI
 570 ShellExecute (
 571   IN EFI_HANDLE   *ParentHandle,
 572   IN CHAR16       *CommandLine,
 573   IN BOOLEAN      Output,
 574   IN CHAR16       **EnvironmentVariables,
 575   OUT EFI_STATUS  *Status
 576   );
 577
 578 /**
 579   Retreives the current directory path.
 580
 581   If the DeviceName is NULL, it returns the current device's current directory
 582   name. If the DeviceName is not NULL, it returns the current directory name
 583   on specified drive.
 584
 585   Note that the current directory string should exclude the tailing backslash character.
 586
 587   @param[in] DeviceName         The name of the file system to get directory on.
 588
 589   @retval NULL                  The directory does not exist.
 590   @retval != NULL               The directory.
 591 **/
 592 CONST CHAR16 *
 593 EFIAPI
 594 ShellGetCurrentDir (
 595   IN CHAR16                     *CONST  DeviceName OPTIONAL
 596   );
 597
 598 /**
 599   Sets (enabled or disabled) the page break mode.
 600
 601   When page break mode is enabled the screen will stop scrolling
 602   and wait for operator input before scrolling a subsequent screen.
 603
 604   @param[in] CurrentState       TRUE to enable and FALSE to disable.
 605 **/
 606 VOID
 607 EFIAPI
 608 ShellSetPageBreakMode (
 609   IN BOOLEAN  CurrentState
 610   );
 611
 612 /**
 613   Opens a group of files based on a path.
 614
 615   This function uses the Arg to open all the matching files. Each matched
 616   file has a SHELL_FILE_ARG structure to record the file information. These
 617   structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG
 618   structures from ListHead to access each file. This function supports wildcards
 619   and will process '?' and '*' as such.  The list must be freed with a call to
 620   ShellCloseFileMetaArg().
 621
 622   If you are NOT appending to an existing list *ListHead must be NULL.  If
 623   *ListHead is NULL then it must be callee freed.
 624
 625   @param[in] Arg                 The pointer to path string.
 626   @param[in] OpenMode            Mode to open files with.
 627   @param[in, out] ListHead       Head of linked list of results.
 628
 629   @retval EFI_SUCCESS           The operation was sucessful and the list head
 630                                 contains the list of opened files.
 631   @retval != EFI_SUCCESS        The operation failed.
 632
 633   @sa InternalShellConvertFileListType
 634 **/
 635 EFI_STATUS
 636 EFIAPI
 637 ShellOpenFileMetaArg (
 638   IN CHAR16                   *Arg,
 639   IN UINT64                   OpenMode,
 640   IN OUT EFI_SHELL_FILE_INFO  **ListHead
 641   );
 642
 643 /**
 644   Free the linked list returned from ShellOpenFileMetaArg.
 645
 646   @param[in, out] ListHead       The pointer to free.
 647
 648   @retval EFI_SUCCESS           The operation was sucessful.
 649   @retval EFI_INVALID_PARAMETER A parameter was invalid.
 650 **/
 651 EFI_STATUS
 652 EFIAPI
 653 ShellCloseFileMetaArg (
 654   IN OUT EFI_SHELL_FILE_INFO  **ListHead
 655   );
 656
 657 /**
 658   Find a file by searching the CWD and then the path.
 659
 660   If FileName is NULL, then ASSERT.
 661
 662   If the return value is not NULL then the memory must be caller freed.
 663
 664   @param[in] FileName           Filename string.
 665
 666   @retval NULL                  The file was not found.
 667   @retval !NULL                 The path to the file.
 668 **/
 669 CHAR16 *
 670 EFIAPI
 671 ShellFindFilePath (
 672   IN CONST CHAR16  *FileName
 673   );
 674
 675 /**
 676   Find a file by searching the CWD and then the path with a variable set of file
 677   extensions.  If the file is not found it will append each extension in the list
 678   in the order provided and return the first one that is successful.
 679
 680   If FileName is NULL, then ASSERT.
 681   If FileExtension is NULL, then the behavior is identical to ShellFindFilePath.
 682
 683   If the return value is not NULL then the memory must be caller freed.
 684
 685   @param[in] FileName           The filename string.
 686   @param[in] FileExtension      Semicolon delimited list of possible extensions.
 687
 688   @retval NULL                  The file was not found.
 689   @retval !NULL                 The path to the file.
 690 **/
 691 CHAR16 *
 692 EFIAPI
 693 ShellFindFilePathEx (
 694   IN CONST CHAR16  *FileName,
 695   IN CONST CHAR16  *FileExtension
 696   );
 697
 698 typedef enum {
 699   TypeFlag = 0,     ///< A flag that is present or not present only (IE "-a").
 700   TypeValue,        ///< A flag that has some data following it with a space (IE "-a 1").
 701   TypePosition,     ///< Some data that did not follow a parameter (IE "filename.txt").
 702   TypeStart,        ///< A flag that has variable value appended to the end (IE "-ad", "-afd", "-adf", etc...).
 703   TypeDoubleValue,  ///< A flag that has 2 space seperated value data following it (IE "-a 1 2").
 704   TypeMaxValue,     ///< A flag followed by all the command line data before the next flag.
 705   TypeTimeValue,    ///< A flag that has a time value following it (IE "-a -5:00").
 706   TypeMax,
 707 } SHELL_PARAM_TYPE;
 708
 709 typedef struct {
 710   CHAR16              *Name;
 711   SHELL_PARAM_TYPE    Type;
 712 } SHELL_PARAM_ITEM;
 713
 714 /// Helper structure for no parameters (besides -? and -b)
 715 extern SHELL_PARAM_ITEM  EmptyParamList[];
 716
 717 /// Helper structure for -sfo only (besides -? and -b)
 718 extern SHELL_PARAM_ITEM  SfoParamList[];
 719
 720 /**
 721   Checks the command line arguments passed against the list of valid ones.
 722   Optionally removes NULL values first.
 723
 724   If no initialization is required, then return RETURN_SUCCESS.
 725
 726   @param[in] CheckList          The pointer to list of parameters to check.
 727   @param[out] CheckPackage      The package of checked values.
 728   @param[out] ProblemParam      Optional pointer to pointer to unicode string for
 729                                 the paramater that caused failure.
 730   @param[in] AutoPageBreak      Will automatically set PageBreakEnabled.
 731   @param[in] AlwaysAllowNumbers Will never fail for number based flags.
 732
 733   @retval EFI_SUCCESS           The operation completed sucessfully.
 734   @retval EFI_OUT_OF_RESOURCES  A memory allocation failed.
 735   @retval EFI_INVALID_PARAMETER A parameter was invalid.
 736   @retval EFI_VOLUME_CORRUPTED  The command line was corrupt.
 737   @retval EFI_DEVICE_ERROR      The commands contained 2 opposing arguments.  One
 738                                 of the command line arguments was returned in
 739                                 ProblemParam if provided.
 740   @retval EFI_NOT_FOUND         A argument required a value that was missing.
 741                                 The invalid command line argument was returned in
 742                                 ProblemParam if provided.
 743 **/
 744 EFI_STATUS
 745 EFIAPI
 746 ShellCommandLineParseEx (
 747   IN CONST SHELL_PARAM_ITEM  *CheckList,
 748   OUT LIST_ENTRY             **CheckPackage,
 749   OUT CHAR16                 **ProblemParam OPTIONAL,
 750   IN BOOLEAN                 AutoPageBreak,
 751   IN BOOLEAN                 AlwaysAllowNumbers
 752   );
 753
 754 /// Make it easy to upgrade from older versions of the shell library.
 755 #define ShellCommandLineParse(CheckList, CheckPackage, ProblemParam, AutoPageBreak)  ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE)
 756
 757 /**
 758   Frees shell variable list that was returned from ShellCommandLineParse.
 759
 760   This function will free all the memory that was used for the CheckPackage
 761   list of postprocessed shell arguments.
 762
 763   If CheckPackage is NULL, then return.
 764
 765   @param[in] CheckPackage       The list to de-allocate.
 766   **/
 767 VOID
 768 EFIAPI
 769 ShellCommandLineFreeVarList (
 770   IN LIST_ENTRY  *CheckPackage
 771   );
 772
 773 /**
 774   Checks for presence of a flag parameter.
 775
 776   Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key.
 777
 778   If CheckPackage is NULL then return FALSE.
 779   If KeyString is NULL then ASSERT().
 780
 781   @param[in] CheckPackage       The package of parsed command line arguments.
 782   @param[in] KeyString          The Key of the command line argument to check for.
 783
 784   @retval TRUE                  The flag is on the command line.
 785   @retval FALSE                 The flag is not on the command line.
 786 **/
 787 BOOLEAN
 788 EFIAPI
 789 ShellCommandLineGetFlag (
 790   IN CONST LIST_ENTRY         *CONST  CheckPackage,
 791   IN CONST CHAR16             *CONST  KeyString
 792   );
 793
 794 /**
 795   Returns value from command line argument.
 796
 797   Value parameters are in the form of "-<Key> value" or "/<Key> value".
 798
 799   If CheckPackage is NULL, then return NULL.
 800
 801   @param[in] CheckPackage       The package of parsed command line arguments.
 802   @param[in] KeyString          The Key of the command line argument to check for.
 803
 804   @retval NULL                  The flag is not on the command line.
 805   @retval !=NULL                The pointer to unicode string of the value.
 806 **/
 807 CONST CHAR16 *
 808 EFIAPI
 809 ShellCommandLineGetValue (
 810   IN CONST LIST_ENTRY  *CheckPackage,
 811   IN CHAR16            *KeyString
 812   );
 813
 814 /**
 815   Returns raw value from command line argument.
 816
 817   Raw value parameters are in the form of "value" in a specific position in the list.
 818
 819   If CheckPackage is NULL, then return NULL.
 820
 821   @param[in] CheckPackage       The package of parsed command line arguments.
 822   @param[in] Position           The position of the value.
 823
 824   @retval NULL                  The flag is not on the command line.
 825   @retval !=NULL                The pointer to unicode string of the value.
 826 **/
 827 CONST CHAR16 *
 828 EFIAPI
 829 ShellCommandLineGetRawValue (
 830   IN CONST LIST_ENTRY              *CONST  CheckPackage,
 831   IN UINTN                                 Position
 832   );
 833
 834 /**
 835   Returns the number of command line value parameters that were parsed.
 836
 837   This will not include flags.
 838
 839   @param[in] CheckPackage       The package of parsed command line arguments.
 840
 841   @retval (UINTN)-1             No parsing has occurred.
 842   @retval other                 The number of value parameters found.
 843 **/
 844 UINTN
 845 EFIAPI
 846 ShellCommandLineGetCount (
 847   IN CONST LIST_ENTRY  *CheckPackage
 848   );
 849
 850 /**
 851   Determines if a parameter is duplicated.
 852
 853   If Param is not NULL, then it will point to a callee-allocated string buffer
 854   with the parameter value, if a duplicate is found.
 855
 856   If CheckPackage is NULL, then ASSERT.
 857
 858   @param[in] CheckPackage       The package of parsed command line arguments.
 859   @param[out] Param             Upon finding one, a pointer to the duplicated parameter.
 860
 861   @retval EFI_SUCCESS           No parameters were duplicated.
 862   @retval EFI_DEVICE_ERROR      A duplicate was found.
 863   **/
 864 EFI_STATUS
 865 EFIAPI
 866 ShellCommandLineCheckDuplicate (
 867   IN CONST LIST_ENTRY  *CheckPackage,
 868   OUT CHAR16           **Param
 869   );
 870
 871 /**
 872   This function causes the shell library to initialize itself.  If the shell library
 873   is already initialized it will de-initialize all the current protocol pointers and
 874   re-populate them again.
 875
 876   When the library is used with PcdShellLibAutoInitialize set to true this function
 877   will return EFI_SUCCESS and perform no actions.
 878
 879   This function is intended for internal access for shell commands only.
 880
 881   @retval EFI_SUCCESS   The initialization was complete sucessfully.
 882
 883 **/
 884 EFI_STATUS
 885 EFIAPI
 886 ShellInitialize (
 887   VOID
 888   );
 889
 890 /**
 891   Print at a specific location on the screen.
 892
 893   This function will move the cursor to a given screen location and print the specified string.
 894
 895   If -1 is specified for either the Row or Col the current screen location for BOTH
 896   will be used.
 897
 898   If either Row or Col is out of range for the current console, then ASSERT.
 899   If Format is NULL, then ASSERT.
 900
 901   In addition to the standard %-based flags as supported by UefiLib Print() this supports
 902   the following additional flags:
 903     %N       -   Set output attribute to normal
 904     %H       -   Set output attribute to highlight
 905     %E       -   Set output attribute to error
 906     %B       -   Set output attribute to blue color
 907     %V       -   Set output attribute to green color
 908
 909   Note: The background color is controlled by the shell command cls.
 910
 911   @param[in] Col        The column to print at.
 912   @param[in] Row        The row to print at.
 913   @param[in] Format     The format string.
 914   @param[in] ...        The variable argument list.
 915
 916   @return EFI_SUCCESS           The printing was successful.
 917   @return EFI_DEVICE_ERROR      The console device reported an error.
 918 **/
 919 EFI_STATUS
 920 EFIAPI
 921 ShellPrintEx (
 922   IN INT32         Col OPTIONAL,
 923   IN INT32         Row OPTIONAL,
 924   IN CONST CHAR16  *Format,
 925   ...
 926   );
 927
 928 /**
 929   Print at a specific location on the screen.
 930
 931   This function will move the cursor to a given screen location and print the specified string.
 932
 933   If -1 is specified for either the Row or Col the current screen location for BOTH
 934   will be used.
 935
 936   If either Row or Col is out of range for the current console, then ASSERT.
 937   If Format is NULL, then ASSERT.
 938
 939   In addition to the standard %-based flags as supported by UefiLib Print() this supports
 940   the following additional flags:
 941     %N       -   Set output attribute to normal.
 942     %H       -   Set output attribute to highlight.
 943     %E       -   Set output attribute to error.
 944     %B       -   Set output attribute to blue color.
 945     %V       -   Set output attribute to green color.
 946
 947   Note: The background color is controlled by the shell command cls.
 948
 949   @param[in] Col                The column to print at.
 950   @param[in] Row                The row to print at.
 951   @param[in] Language           The language of the string to retrieve.  If this parameter
 952                                 is NULL, then the current platform language is used.
 953   @param[in] HiiFormatStringId  The format string Id for getting from Hii.
 954   @param[in] HiiFormatHandle    The format string Handle for getting from Hii.
 955   @param[in] ...                The variable argument list.
 956
 957   @return EFI_SUCCESS           The printing was successful.
 958   @return EFI_DEVICE_ERROR      The console device reported an error.
 959 **/
 960 EFI_STATUS
 961 EFIAPI
 962 ShellPrintHiiEx (
 963   IN INT32                 Col OPTIONAL,
 964   IN INT32                 Row OPTIONAL,
 965   IN CONST CHAR8           *Language OPTIONAL,
 966   IN CONST EFI_STRING_ID   HiiFormatStringId,
 967   IN CONST EFI_HII_HANDLE  HiiFormatHandle,
 968   ...
 969   );
 970
 971 /**
 972   Function to determine if a given filename represents a directory.
 973
 974   If DirName is NULL, then ASSERT.
 975
 976   @param[in] DirName      Path to directory to test.
 977
 978   @retval EFI_SUCCESS     The Path represents a directory.
 979   @retval EFI_NOT_FOUND   The Path does not represent a directory.
 980   @retval other           The path failed to open.
 981 **/
 982 EFI_STATUS
 983 EFIAPI
 984 ShellIsDirectory (
 985   IN CONST CHAR16  *DirName
 986   );
 987
 988 /**
 989   Function to determine if a given filename represents a file.
 990
 991   This will search the CWD only.
 992
 993   If Name is NULL, then ASSERT.
 994
 995   @param[in] Name         Path to file to test.
 996
 997   @retval EFI_SUCCESS     The Path represents a file.
 998   @retval EFI_NOT_FOUND   The Path does not represent a file.
 999   @retval other           The path failed to open.
1000 **/
1001 EFI_STATUS
1002 EFIAPI
1003 ShellIsFile (
1004   IN CONST CHAR16  *Name
1005   );
1006
1007 /**
1008   Function to determine if a given filename represents a file.
1009
1010   This will search the CWD and then the Path.
1011
1012   If Name is NULL, then ASSERT.
1013
1014   @param[in] Name         Path to file to test.
1015
1016   @retval EFI_SUCCESS     The Path represents a file.
1017   @retval EFI_NOT_FOUND   The Path does not represent a file.
1018   @retval other           The path failed to open.
1019 **/
1020 EFI_STATUS
1021 EFIAPI
1022 ShellIsFileInPath (
1023   IN CONST CHAR16  *Name
1024   );
1025
1026 /**
1027   Function to determine whether a string is decimal or hex representation of a number
1028   and return the number converted from the string.
1029
1030   Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
1031   result.  Use ShellConvertStringToUint64 instead.
1032
1033   @param[in] String   String representation of a number.
1034
1035   @return             The unsigned integer result of the conversion.
1036   @retval (UINTN)(-1) An error occurred.
1037 **/
1038 UINTN
1039 EFIAPI
1040 ShellStrToUintn (
1041   IN CONST CHAR16  *String
1042   );
1043
1044 /**
1045   Function return the number converted from a hex representation of a number.
1046
1047   Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
1048   result.  Use ShellConvertStringToUint64 instead.
1049
1050   @param[in] String   String representation of a number.
1051
1052   @return             The unsigned integer result of the conversion.
1053   @retval (UINTN)(-1) An error occurred.
1054 **/
1055 UINTN
1056 EFIAPI
1057 ShellHexStrToUintn (
1058   IN CONST CHAR16  *String
1059   );
1060
1061 /**
1062   Safely append with automatic string resizing given length of Destination and
1063   desired length of copy from Source.
1064
1065   Append the first D characters of Source to the end of Destination, where D is
1066   the lesser of Count and the StrLen() of Source. If appending those D characters
1067   will fit within Destination (whose Size is given as CurrentSize) and
1068   still leave room for a NULL terminator, then those characters are appended,
1069   starting at the original terminating NULL of Destination, and a new terminating
1070   NULL is appended.
1071
1072   If appending D characters onto Destination will result in a overflow of the size
1073   given in CurrentSize the string will be grown such that the copy can be performed
1074   and CurrentSize will be updated to the new size.
1075
1076   If Source is NULL, there is nothing to append, so return the current buffer in
1077   Destination.
1078
1079   If Destination is NULL, then ASSERT().
1080   If Destination's current length (including NULL terminator) is already more than
1081   CurrentSize, then ASSERT().
1082
1083   @param[in, out] Destination    The String to append onto.
1084   @param[in, out] CurrentSize    On call, the number of bytes in Destination.  On
1085                                  return, possibly the new size (still in bytes).  If NULL,
1086                                  then allocate whatever is needed.
1087   @param[in]      Source         The String to append from.
1088   @param[in]      Count          The maximum number of characters to append.  If 0, then
1089                                  all are appended.
1090
1091   @return                       The Destination after appending the Source.
1092 **/
1093 CHAR16 *
1094 EFIAPI
1095 StrnCatGrow (
1096   IN OUT CHAR16        **Destination,
1097   IN OUT UINTN         *CurrentSize,
1098   IN     CONST CHAR16  *Source,
1099   IN     UINTN         Count
1100   );
1101
1102 /**
1103   This is a find and replace function.  Upon successful return the NewString is a copy of
1104   SourceString with each instance of FindTarget replaced with ReplaceWith.
1105
1106   If SourceString and NewString overlap the behavior is undefined.
1107
1108   If the string would grow bigger than NewSize it will halt and return error.
1109
1110   @param[in] SourceString              The string with source buffer.
1111   @param[in, out] NewString            The string with resultant buffer.
1112   @param[in] NewSize                   The size in bytes of NewString.
1113   @param[in] FindTarget                The string to look for.
1114   @param[in] ReplaceWith               The string to replace FindTarget with.
1115   @param[in] SkipPreCarrot             If TRUE will skip a FindTarget that has a '^'
1116                                        immediately before it.
1117   @param[in] ParameterReplacing        If TRUE will add "" around items with spaces.
1118
1119   @retval EFI_INVALID_PARAMETER       SourceString was NULL.
1120   @retval EFI_INVALID_PARAMETER       NewString was NULL.
1121   @retval EFI_INVALID_PARAMETER       FindTarget was NULL.
1122   @retval EFI_INVALID_PARAMETER       ReplaceWith was NULL.
1123   @retval EFI_INVALID_PARAMETER       FindTarget had length < 1.
1124   @retval EFI_INVALID_PARAMETER       SourceString had length < 1.
1125   @retval EFI_BUFFER_TOO_SMALL        NewSize was less than the minimum size to hold
1126                                       the new string (truncation occurred).
1127   @retval EFI_SUCCESS                 The string was successfully copied with replacement.
1128 **/
1129 EFI_STATUS
1130 EFIAPI
1131 ShellCopySearchAndReplace (
1132   IN CHAR16 CONST   *SourceString,
1133   IN OUT CHAR16     *NewString,
1134   IN UINTN          NewSize,
1135   IN CONST CHAR16   *FindTarget,
1136   IN CONST CHAR16   *ReplaceWith,
1137   IN CONST BOOLEAN  SkipPreCarrot,
1138   IN CONST BOOLEAN  ParameterReplacing
1139   );
1140
1141 /**
1142   Check if a Unicode character is a hexadecimal character.
1143
1144   This internal function checks if a Unicode character is a
1145   numeric character.  The valid hexadecimal characters are
1146   L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
1147
1148
1149   @param  Char  The character to check against.
1150
1151   @retval TRUE  The Char is a hexadecmial character.
1152   @retval FALSE The Char is not a hexadecmial character.
1153
1154 **/
1155 BOOLEAN
1156 EFIAPI
1157 ShellIsHexaDecimalDigitCharacter (
1158   IN      CHAR16  Char
1159   );
1160
1161 /**
1162   Check if a Unicode character is a decimal character.
1163
1164   This internal function checks if a Unicode character is a
1165   decimal character.  The valid characters are
1166   L'0' to L'9'.
1167
1168
1169   @param  Char  The character to check against.
1170
1171   @retval TRUE  The Char is a hexadecmial character.
1172   @retval FALSE The Char is not a hexadecmial character.
1173
1174 **/
1175 BOOLEAN
1176 EFIAPI
1177 ShellIsDecimalDigitCharacter (
1178   IN      CHAR16  Char
1179   );
1180
1181 ///
1182 /// What type of answer is requested.
1183 ///
1184 typedef enum {
1185   ShellPromptResponseTypeYesNo,
1186   ShellPromptResponseTypeYesNoCancel,
1187   ShellPromptResponseTypeFreeform,
1188   ShellPromptResponseTypeQuitContinue,
1189   ShellPromptResponseTypeYesNoAllCancel,
1190   ShellPromptResponseTypeEnterContinue,
1191   ShellPromptResponseTypeAnyKeyContinue,
1192   ShellPromptResponseTypeMax
1193 } SHELL_PROMPT_REQUEST_TYPE;
1194
1195 ///
1196 /// What answer was given.
1197 ///
1198 typedef enum {
1199   ShellPromptResponseYes,
1200   ShellPromptResponseNo,
1201   ShellPromptResponseCancel,
1202   ShellPromptResponseQuit,
1203   ShellPromptResponseContinue,
1204   ShellPromptResponseAll,
1205   ShellPromptResponseMax
1206 } SHELL_PROMPT_RESPONSE;
1207
1208 /**
1209   Prompt the user and return the resultant answer to the requestor.
1210
1211   This function will display the requested question on the shell prompt and then
1212   wait for an appropriate answer to be input from the console.
1213
1214   If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue
1215   or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE.
1216
1217   If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type
1218   CHAR16*.
1219
1220   In either case *Response must be callee freed if Response was not NULL;
1221
1222   @param Type                     What type of question is asked.  This is used to filter the input
1223                                   to prevent invalid answers to question.
1224   @param Prompt                   The pointer to a string prompt used to request input.
1225   @param Response                 The pointer to Response, which will be populated upon return.
1226
1227   @retval EFI_SUCCESS             The operation was successful.
1228   @retval EFI_UNSUPPORTED         The operation is not supported as requested.
1229   @retval EFI_INVALID_PARAMETER   A parameter was invalid.
1230   @return other                   The operation failed.
1231 **/
1232 EFI_STATUS
1233 EFIAPI
1234 ShellPromptForResponse (
1235   IN SHELL_PROMPT_REQUEST_TYPE  Type,
1236   IN CHAR16                     *Prompt OPTIONAL,
1237   IN OUT VOID                   **Response OPTIONAL
1238   );
1239
1240 /**
1241   Prompt the user and return the resultant answer to the requestor.
1242
1243   This function is the same as ShellPromptForResponse, except that the prompt is
1244   automatically pulled from HII.
1245
1246   @param[in] Type What type of question is asked.  This is used to filter the input
1247                   to prevent invalid answers to question.
1248   @param[in] HiiFormatStringId   The format string Id for getting from Hii.
1249   @param[in] HiiFormatHandle     The format string Handle for getting from Hii.
1250   @param[in, out] Response       The pointer to Response, which will be populated upon return.
1251
1252   @retval EFI_SUCCESS The operation was sucessful.
1253   @return other       The operation failed.
1254
1255   @sa ShellPromptForResponse
1256 **/
1257 EFI_STATUS
1258 EFIAPI
1259 ShellPromptForResponseHii (
1260   IN SHELL_PROMPT_REQUEST_TYPE  Type,
1261   IN CONST EFI_STRING_ID        HiiFormatStringId,
1262   IN CONST EFI_HII_HANDLE       HiiFormatHandle,
1263   IN OUT VOID                   **Response
1264   );
1265
1266 /**
1267   Function to determin if an entire string is a valid number.
1268
1269   If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
1270
1271   @param[in] String       The string to evaluate.
1272   @param[in] ForceHex     TRUE - always assume hex.
1273   @param[in] StopAtSpace  TRUE to halt upon finding a space, FALSE to keep going.
1274
1275   @retval TRUE        It is all numeric (dec/hex) characters.
1276   @retval FALSE       There is a non-numeric character.
1277 **/
1278 BOOLEAN
1279 EFIAPI
1280 ShellIsHexOrDecimalNumber (
1281   IN CONST CHAR16   *String,
1282   IN CONST BOOLEAN  ForceHex,
1283   IN CONST BOOLEAN  StopAtSpace
1284   );
1285
1286 /**
1287   Function to verify and convert a string to its numerical 64 bit representation.
1288
1289   If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
1290
1291   @param[in] String       The string to evaluate.
1292   @param[out] Value       Upon a successful return the value of the conversion.
1293   @param[in] ForceHex     TRUE - always assume hex.
1294   @param[in] StopAtSpace  TRUE to halt upon finding a space, FALSE to
1295                           process the entire String.
1296
1297   @retval EFI_SUCCESS             The conversion was successful.
1298   @retval EFI_INVALID_PARAMETER   String contained an invalid character.
1299   @retval EFI_NOT_FOUND           String was a number, but Value was NULL.
1300 **/
1301 EFI_STATUS
1302 EFIAPI
1303 ShellConvertStringToUint64 (
1304   IN CONST CHAR16   *String,
1305   OUT   UINT64      *Value,
1306   IN CONST BOOLEAN  ForceHex,
1307   IN CONST BOOLEAN  StopAtSpace
1308   );
1309
1310 /**
1311   Function to determine if a given filename exists.
1312
1313   @param[in] Name         Path to test.
1314
1315   @retval EFI_SUCCESS     The Path represents a file.
1316   @retval EFI_NOT_FOUND   The Path does not represent a file.
1317   @retval other           The path failed to open.
1318 **/
1319 EFI_STATUS
1320 EFIAPI
1321 ShellFileExists (
1322   IN CONST CHAR16  *Name
1323   );
1324
1325 /**
1326   Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned
1327   buffer.  The returned buffer must be callee freed.
1328
1329   If the position upon start is 0, then the Ascii Boolean will be set.  This should be
1330   maintained and not changed for all operations with the same file.
1331
1332   @param[in]       Handle        SHELL_FILE_HANDLE to read from.
1333   @param[in, out]  Ascii         Boolean value for indicating whether the file is
1334                                  Ascii (TRUE) or UCS2 (FALSE).
1335
1336   @return                        The line of text from the file.
1337
1338   @sa ShellFileHandleReadLine
1339 **/
1340 CHAR16 *
1341 EFIAPI
1342 ShellFileHandleReturnLine (
1343   IN SHELL_FILE_HANDLE  Handle,
1344   IN OUT BOOLEAN        *Ascii
1345   );
1346
1347 /**
1348   Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE.
1349
1350   If the position upon start is 0, then the Ascii Boolean will be set.  This should be
1351   maintained and not changed for all operations with the same file.
1352
1353   @param[in]       Handle        SHELL_FILE_HANDLE to read from.
1354   @param[in, out]  Buffer        The pointer to buffer to read into.
1355   @param[in, out]  Size          The pointer to number of bytes in Buffer.
1356   @param[in]       Truncate      If the buffer is large enough, this has no effect.
1357                                  If the buffer is is too small and Truncate is TRUE,
1358                                  the line will be truncated.
1359                                  If the buffer is is too small and Truncate is FALSE,
1360                                  then no read will occur.
1361
1362   @param[in, out]  Ascii         Boolean value for indicating whether the file is
1363                                  Ascii (TRUE) or UCS2 (FALSE).
1364
1365   @retval EFI_SUCCESS           The operation was successful.  The line is stored in
1366                                 Buffer.
1367   @retval EFI_END_OF_FILE       There are no more lines in the file.
1368   @retval EFI_INVALID_PARAMETER Handle was NULL.
1369   @retval EFI_INVALID_PARAMETER Size was NULL.
1370   @retval EFI_BUFFER_TOO_SMALL  Size was not large enough to store the line.
1371                                 Size was updated to the minimum space required.
1372 **/
1373 EFI_STATUS
1374 EFIAPI
1375 ShellFileHandleReadLine (
1376   IN SHELL_FILE_HANDLE  Handle,
1377   IN OUT CHAR16         *Buffer,
1378   IN OUT UINTN          *Size,
1379   IN BOOLEAN            Truncate,
1380   IN OUT BOOLEAN        *Ascii
1381   );
1382
1383 /**
1384   Function to delete a file by name
1385
1386   @param[in]       FileName       Pointer to file name to delete.
1387
1388   @retval EFI_SUCCESS             the file was deleted sucessfully
1389   @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
1390                                   deleted
1391   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
1392   @retval EFI_NOT_FOUND           The specified file could not be found on the
1393                                   device or the file system could not be found
1394                                   on the device.
1395   @retval EFI_NO_MEDIA            The device has no medium.
1396   @retval EFI_MEDIA_CHANGED       The device has a different medium in it or the
1397                                   medium is no longer supported.
1398   @retval EFI_DEVICE_ERROR        The device reported an error.
1399   @retval EFI_VOLUME_CORRUPTED    The file system structures are corrupted.
1400   @retval EFI_WRITE_PROTECTED     The file or medium is write protected.
1401   @retval EFI_ACCESS_DENIED       The file was opened read only.
1402   @retval EFI_OUT_OF_RESOURCES    Not enough resources were available to open the
1403                                   file.
1404   @retval other                   The file failed to open
1405 **/
1406 EFI_STATUS
1407 EFIAPI
1408 ShellDeleteFileByName (
1409   IN CONST CHAR16  *FileName
1410   );
1411
1412 /**
1413   Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function.
1414
1415   @param[in] CommandToGetHelpOn  Pointer to a string containing the command name of help file to be printed.
1416   @param[in] SectionToGetHelpOn  Pointer to the section specifier(s).
1417   @param[in] PrintCommandText    If TRUE, prints the command followed by the help content, otherwise prints
1418                                  the help content only.
1419   @retval EFI_DEVICE_ERROR       The help data format was incorrect.
1420   @retval EFI_NOT_FOUND          The help data could not be found.
1421   @retval EFI_SUCCESS            The operation was successful.
1422 **/
1423 EFI_STATUS
1424 EFIAPI
1425 ShellPrintHelp (
1426   IN CONST CHAR16  *CommandToGetHelpOn,
1427   IN CONST CHAR16  *SectionToGetHelpOn,
1428   IN BOOLEAN       PrintCommandText
1429   );
1430
1431 #endif // __SHELL_LIB__