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
 715 /// Helper structure for no parameters (besides -? and -b)
 716 extern SHELL_PARAM_ITEM EmptyParamList[];
 717
 718 /// Helper structure for -sfo only (besides -? and -b)
 719 extern SHELL_PARAM_ITEM SfoParamList[];
 720
 721 /**
 722   Checks the command line arguments passed against the list of valid ones.
 723   Optionally removes NULL values first.
 724
 725   If no initialization is required, then return RETURN_SUCCESS.
 726
 727   @param[in] CheckList          The pointer to list of parameters to check.
 728   @param[out] CheckPackage      The package of checked values.
 729   @param[out] ProblemParam      Optional pointer to pointer to unicode string for
 730                                 the paramater that caused failure.
 731   @param[in] AutoPageBreak      Will automatically set PageBreakEnabled.
 732   @param[in] AlwaysAllowNumbers Will never fail for number based flags.
 733
 734   @retval EFI_SUCCESS           The operation completed sucessfully.
 735   @retval EFI_OUT_OF_RESOURCES  A memory allocation failed.
 736   @retval EFI_INVALID_PARAMETER A parameter was invalid.
 737   @retval EFI_VOLUME_CORRUPTED  The command line was corrupt.
 738   @retval EFI_DEVICE_ERROR      The commands contained 2 opposing arguments.  One
 739                                 of the command line arguments was returned in
 740                                 ProblemParam if provided.
 741   @retval EFI_NOT_FOUND         A argument required a value that was missing.
 742                                 The invalid command line argument was returned in
 743                                 ProblemParam if provided.
 744 **/
 745 EFI_STATUS
 746 EFIAPI
 747 ShellCommandLineParseEx (
 748   IN CONST SHELL_PARAM_ITEM     *CheckList,
 749   OUT LIST_ENTRY                **CheckPackage,
 750   OUT CHAR16                    **ProblemParam OPTIONAL,
 751   IN BOOLEAN                    AutoPageBreak,
 752   IN BOOLEAN                    AlwaysAllowNumbers
 753   );
 754
 755 /// Make it easy to upgrade from older versions of the shell library.
 756 #define ShellCommandLineParse(CheckList,CheckPackage,ProblemParam,AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE)
 757
 758 /**
 759   Frees shell variable list that was returned from ShellCommandLineParse.
 760
 761   This function will free all the memory that was used for the CheckPackage
 762   list of postprocessed shell arguments.
 763
 764   If CheckPackage is NULL, then return.
 765
 766   @param[in] CheckPackage       The list to de-allocate.
 767   **/
 768 VOID
 769 EFIAPI
 770 ShellCommandLineFreeVarList (
 771   IN LIST_ENTRY                 *CheckPackage
 772   );
 773
 774 /**
 775   Checks for presence of a flag parameter.
 776
 777   Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key.
 778
 779   If CheckPackage is NULL then return FALSE.
 780   If KeyString is NULL then ASSERT().
 781
 782   @param[in] CheckPackage       The package of parsed command line arguments.
 783   @param[in] KeyString          The Key of the command line argument to check for.
 784
 785   @retval TRUE                  The flag is on the command line.
 786   @retval FALSE                 The flag is not on the command line.
 787 **/
 788 BOOLEAN
 789 EFIAPI
 790 ShellCommandLineGetFlag (
 791   IN CONST LIST_ENTRY         * CONST CheckPackage,
 792   IN CONST CHAR16             * CONST KeyString
 793   );
 794
 795 /**
 796   Returns value from command line argument.
 797
 798   Value parameters are in the form of "-<Key> value" or "/<Key> value".
 799
 800   If CheckPackage is NULL, then return NULL.
 801
 802   @param[in] CheckPackage       The package of parsed command line arguments.
 803   @param[in] KeyString          The Key of the command line argument to check for.
 804
 805   @retval NULL                  The flag is not on the command line.
 806   @retval !=NULL                The pointer to unicode string of the value.
 807 **/
 808 CONST CHAR16*
 809 EFIAPI
 810 ShellCommandLineGetValue (
 811   IN CONST LIST_ENTRY              *CheckPackage,
 812   IN CHAR16                        *KeyString
 813   );
 814
 815 /**
 816   Returns raw value from command line argument.
 817
 818   Raw value parameters are in the form of "value" in a specific position in the list.
 819
 820   If CheckPackage is NULL, then return NULL.
 821
 822   @param[in] CheckPackage       The package of parsed command line arguments.
 823   @param[in] Position           The position of the value.
 824
 825   @retval NULL                  The flag is not on the command line.
 826   @retval !=NULL                The pointer to unicode string of the value.
 827 **/
 828 CONST CHAR16*
 829 EFIAPI
 830 ShellCommandLineGetRawValue (
 831   IN CONST LIST_ENTRY              * CONST CheckPackage,
 832   IN UINTN                         Position
 833   );
 834
 835 /**
 836   Returns the number of command line value parameters that were parsed.
 837
 838   This will not include flags.
 839
 840   @param[in] CheckPackage       The package of parsed command line arguments.
 841
 842   @retval (UINTN)-1             No parsing has occurred.
 843   @retval other                 The number of value parameters found.
 844 **/
 845 UINTN
 846 EFIAPI
 847 ShellCommandLineGetCount(
 848   IN CONST LIST_ENTRY              *CheckPackage
 849   );
 850
 851 /**
 852   Determines if a parameter is duplicated.
 853
 854   If Param is not NULL, then it will point to a callee-allocated string buffer
 855   with the parameter value, if a duplicate is found.
 856
 857   If CheckPackage is NULL, then ASSERT.
 858
 859   @param[in] CheckPackage       The package of parsed command line arguments.
 860   @param[out] Param             Upon finding one, a pointer to the duplicated parameter.
 861
 862   @retval EFI_SUCCESS           No parameters were duplicated.
 863   @retval EFI_DEVICE_ERROR      A duplicate was found.
 864   **/
 865 EFI_STATUS
 866 EFIAPI
 867 ShellCommandLineCheckDuplicate (
 868   IN CONST LIST_ENTRY              *CheckPackage,
 869   OUT CHAR16                       **Param
 870   );
 871
 872 /**
 873   This function causes the shell library to initialize itself.  If the shell library
 874   is already initialized it will de-initialize all the current protocol pointers and
 875   re-populate them again.
 876
 877   When the library is used with PcdShellLibAutoInitialize set to true this function
 878   will return EFI_SUCCESS and perform no actions.
 879
 880   This function is intended for internal access for shell commands only.
 881
 882   @retval EFI_SUCCESS   The initialization was complete sucessfully.
 883
 884 **/
 885 EFI_STATUS
 886 EFIAPI
 887 ShellInitialize (
 888   VOID
 889   );
 890
 891 /**
 892   Print at a specific location on the screen.
 893
 894   This function will move the cursor to a given screen location and print the specified string.
 895
 896   If -1 is specified for either the Row or Col the current screen location for BOTH
 897   will be used.
 898
 899   If either Row or Col is out of range for the current console, then ASSERT.
 900   If Format is NULL, then ASSERT.
 901
 902   In addition to the standard %-based flags as supported by UefiLib Print() this supports
 903   the following additional flags:
 904     %N       -   Set output attribute to normal
 905     %H       -   Set output attribute to highlight
 906     %E       -   Set output attribute to error
 907     %B       -   Set output attribute to blue color
 908     %V       -   Set output attribute to green color
 909
 910   Note: The background color is controlled by the shell command cls.
 911
 912   @param[in] Col        The column to print at.
 913   @param[in] Row        The row to print at.
 914   @param[in] Format     The format string.
 915   @param[in] ...        The variable argument list.
 916
 917   @return EFI_SUCCESS           The printing was successful.
 918   @return EFI_DEVICE_ERROR      The console device reported an error.
 919 **/
 920 EFI_STATUS
 921 EFIAPI
 922 ShellPrintEx(
 923   IN INT32                Col OPTIONAL,
 924   IN INT32                Row OPTIONAL,
 925   IN CONST CHAR16         *Format,
 926   ...
 927   );
 928
 929 /**
 930   Print at a specific location on the screen.
 931
 932   This function will move the cursor to a given screen location and print the specified string.
 933
 934   If -1 is specified for either the Row or Col the current screen location for BOTH
 935   will be used.
 936
 937   If either Row or Col is out of range for the current console, then ASSERT.
 938   If Format is NULL, then ASSERT.
 939
 940   In addition to the standard %-based flags as supported by UefiLib Print() this supports
 941   the following additional flags:
 942     %N       -   Set output attribute to normal.
 943     %H       -   Set output attribute to highlight.
 944     %E       -   Set output attribute to error.
 945     %B       -   Set output attribute to blue color.
 946     %V       -   Set output attribute to green color.
 947
 948   Note: The background color is controlled by the shell command cls.
 949
 950   @param[in] Col                The column to print at.
 951   @param[in] Row                The row to print at.
 952   @param[in] Language           The language of the string to retrieve.  If this parameter
 953                                 is NULL, then the current platform language is used.
 954   @param[in] HiiFormatStringId  The format string Id for getting from Hii.
 955   @param[in] HiiFormatHandle    The format string Handle for getting from Hii.
 956   @param[in] ...                The variable argument list.
 957
 958   @return EFI_SUCCESS           The printing was successful.
 959   @return EFI_DEVICE_ERROR      The console device reported an error.
 960 **/
 961 EFI_STATUS
 962 EFIAPI
 963 ShellPrintHiiEx(
 964   IN INT32                Col OPTIONAL,
 965   IN INT32                Row OPTIONAL,
 966   IN CONST CHAR8          *Language OPTIONAL,
 967   IN CONST EFI_STRING_ID  HiiFormatStringId,
 968   IN CONST EFI_HII_HANDLE HiiFormatHandle,
 969   ...
 970   );
 971
 972 /**
 973   Function to determine if a given filename represents a directory.
 974
 975   If DirName is NULL, then ASSERT.
 976
 977   @param[in] DirName      Path to directory to test.
 978
 979   @retval EFI_SUCCESS     The Path represents a directory.
 980   @retval EFI_NOT_FOUND   The Path does not represent a directory.
 981   @retval other           The path failed to open.
 982 **/
 983 EFI_STATUS
 984 EFIAPI
 985 ShellIsDirectory(
 986   IN CONST CHAR16 *DirName
 987   );
 988
 989 /**
 990   Function to determine if a given filename represents a file.
 991
 992   This will search the CWD only.
 993
 994   If Name is NULL, then ASSERT.
 995
 996   @param[in] Name         Path to file to test.
 997
 998   @retval EFI_SUCCESS     The Path represents a file.
 999   @retval EFI_NOT_FOUND   The Path does not represent a file.
1000   @retval other           The path failed to open.
1001 **/
1002 EFI_STATUS
1003 EFIAPI
1004 ShellIsFile(
1005   IN CONST CHAR16 *Name
1006   );
1007
1008 /**
1009   Function to determine if a given filename represents a file.
1010
1011   This will search the CWD and then the Path.
1012
1013   If Name is NULL, then ASSERT.
1014
1015   @param[in] Name         Path to file to test.
1016
1017   @retval EFI_SUCCESS     The Path represents a file.
1018   @retval EFI_NOT_FOUND   The Path does not represent a file.
1019   @retval other           The path failed to open.
1020 **/
1021 EFI_STATUS
1022 EFIAPI
1023 ShellIsFileInPath(
1024   IN CONST CHAR16 *Name
1025   );
1026
1027 /**
1028   Function to determine whether a string is decimal or hex representation of a number
1029   and return the number converted from the string.
1030
1031   Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
1032   result.  Use ShellConvertStringToUint64 instead.
1033
1034   @param[in] String   String representation of a number.
1035
1036   @return             The unsigned integer result of the conversion.
1037   @retval (UINTN)(-1) An error occured.
1038 **/
1039 UINTN
1040 EFIAPI
1041 ShellStrToUintn(
1042   IN CONST CHAR16 *String
1043   );
1044
1045 /**
1046   Function return the number converted from a hex representation of a number.
1047
1048   Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
1049   result.  Use ShellConvertStringToUint64 instead.
1050
1051   @param[in] String   String representation of a number.
1052
1053   @return             The unsigned integer result of the conversion.
1054   @retval (UINTN)(-1) An error occured.
1055 **/
1056 UINTN
1057 EFIAPI
1058 ShellHexStrToUintn(
1059   IN CONST CHAR16 *String
1060   );
1061
1062 /**
1063   Safely append with automatic string resizing given length of Destination and
1064   desired length of copy from Source.
1065
1066   Append the first D characters of Source to the end of Destination, where D is
1067   the lesser of Count and the StrLen() of Source. If appending those D characters
1068   will fit within Destination (whose Size is given as CurrentSize) and
1069   still leave room for a NULL terminator, then those characters are appended,
1070   starting at the original terminating NULL of Destination, and a new terminating
1071   NULL is appended.
1072
1073   If appending D characters onto Destination will result in a overflow of the size
1074   given in CurrentSize the string will be grown such that the copy can be performed
1075   and CurrentSize will be updated to the new size.
1076
1077   If Source is NULL, there is nothing to append, so return the current buffer in
1078   Destination.
1079
1080   If Destination is NULL, then ASSERT().
1081   If Destination's current length (including NULL terminator) is already more than
1082   CurrentSize, then ASSERT().
1083
1084   @param[in, out] Destination    The String to append onto.
1085   @param[in, out] CurrentSize    On call, the number of bytes in Destination.  On
1086                                  return, possibly the new size (still in bytes).  If NULL,
1087                                  then allocate whatever is needed.
1088   @param[in]      Source         The String to append from.
1089   @param[in]      Count          The maximum number of characters to append.  If 0, then
1090                                  all are appended.
1091
1092   @return                       The Destination after appending the Source.
1093 **/
1094 CHAR16*
1095 EFIAPI
1096 StrnCatGrow (
1097   IN OUT CHAR16           **Destination,
1098   IN OUT UINTN            *CurrentSize,
1099   IN     CONST CHAR16     *Source,
1100   IN     UINTN            Count
1101   );
1102
1103 /**
1104   This is a find and replace function.  Upon successful return the NewString is a copy of
1105   SourceString with each instance of FindTarget replaced with ReplaceWith.
1106
1107   If SourceString and NewString overlap the behavior is undefined.
1108
1109   If the string would grow bigger than NewSize it will halt and return error.
1110
1111   @param[in] SourceString              The string with source buffer.
1112   @param[in, out] NewString            The string with resultant buffer.
1113   @param[in] NewSize                   The size in bytes of NewString.
1114   @param[in] FindTarget                The string to look for.
1115   @param[in] ReplaceWith               The string to replace FindTarget with.
1116   @param[in] SkipPreCarrot             If TRUE will skip a FindTarget that has a '^'
1117                                        immediately before it.
1118   @param[in] ParameterReplacing        If TRUE will add "" around items with spaces.
1119
1120   @retval EFI_INVALID_PARAMETER       SourceString was NULL.
1121   @retval EFI_INVALID_PARAMETER       NewString was NULL.
1122   @retval EFI_INVALID_PARAMETER       FindTarget was NULL.
1123   @retval EFI_INVALID_PARAMETER       ReplaceWith was NULL.
1124   @retval EFI_INVALID_PARAMETER       FindTarget had length < 1.
1125   @retval EFI_INVALID_PARAMETER       SourceString had length < 1.
1126   @retval EFI_BUFFER_TOO_SMALL        NewSize was less than the minimum size to hold
1127                                       the new string (truncation occurred).
1128   @retval EFI_SUCCESS                 The string was successfully copied with replacement.
1129 **/
1130 EFI_STATUS
1131 EFIAPI
1132 ShellCopySearchAndReplace(
1133   IN CHAR16 CONST                     *SourceString,
1134   IN OUT CHAR16                       *NewString,
1135   IN UINTN                            NewSize,
1136   IN CONST CHAR16                     *FindTarget,
1137   IN CONST CHAR16                     *ReplaceWith,
1138   IN CONST BOOLEAN                    SkipPreCarrot,
1139   IN CONST BOOLEAN                    ParameterReplacing
1140   );
1141
1142 /**
1143   Check if a Unicode character is a hexadecimal character.
1144
1145   This internal function checks if a Unicode character is a
1146   numeric character.  The valid hexadecimal characters are
1147   L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
1148
1149
1150   @param  Char  The character to check against.
1151
1152   @retval TRUE  The Char is a hexadecmial character.
1153   @retval FALSE The Char is not a hexadecmial character.
1154
1155 **/
1156 BOOLEAN
1157 EFIAPI
1158 ShellIsHexaDecimalDigitCharacter (
1159   IN      CHAR16                    Char
1160   );
1161
1162 /**
1163   Check if a Unicode character is a decimal character.
1164
1165   This internal function checks if a Unicode character is a
1166   decimal character.  The valid characters are
1167   L'0' to L'9'.
1168
1169
1170   @param  Char  The character to check against.
1171
1172   @retval TRUE  The Char is a hexadecmial character.
1173   @retval FALSE The Char is not a hexadecmial character.
1174
1175 **/
1176 BOOLEAN
1177 EFIAPI
1178 ShellIsDecimalDigitCharacter (
1179   IN      CHAR16                    Char
1180   );
1181
1182 ///
1183 /// What type of answer is requested.
1184 ///
1185 typedef enum {
1186   ShellPromptResponseTypeYesNo,
1187   ShellPromptResponseTypeYesNoCancel,
1188   ShellPromptResponseTypeFreeform,
1189   ShellPromptResponseTypeQuitContinue,
1190   ShellPromptResponseTypeYesNoAllCancel,
1191   ShellPromptResponseTypeEnterContinue,
1192   ShellPromptResponseTypeAnyKeyContinue,
1193   ShellPromptResponseTypeMax
1194 } SHELL_PROMPT_REQUEST_TYPE;
1195
1196 ///
1197 /// What answer was given.
1198 ///
1199 typedef enum {
1200   ShellPromptResponseYes,
1201   ShellPromptResponseNo,
1202   ShellPromptResponseCancel,
1203   ShellPromptResponseQuit,
1204   ShellPromptResponseContinue,
1205   ShellPromptResponseAll,
1206   ShellPromptResponseMax
1207 } SHELL_PROMPT_RESPONSE;
1208
1209 /**
1210   Prompt the user and return the resultant answer to the requestor.
1211
1212   This function will display the requested question on the shell prompt and then
1213   wait for an appropriate answer to be input from the console.
1214
1215   If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue
1216   or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE.
1217
1218   If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type
1219   CHAR16*.
1220
1221   In either case *Response must be callee freed if Response was not NULL;
1222
1223   @param Type                     What type of question is asked.  This is used to filter the input
1224                                   to prevent invalid answers to question.
1225   @param Prompt                   The pointer to a string prompt used to request input.
1226   @param Response                 The pointer to Response, which will be populated upon return.
1227
1228   @retval EFI_SUCCESS             The operation was successful.
1229   @retval EFI_UNSUPPORTED         The operation is not supported as requested.
1230   @retval EFI_INVALID_PARAMETER   A parameter was invalid.
1231   @return other                   The operation failed.
1232 **/
1233 EFI_STATUS
1234 EFIAPI
1235 ShellPromptForResponse (
1236   IN SHELL_PROMPT_REQUEST_TYPE   Type,
1237   IN CHAR16         *Prompt OPTIONAL,
1238   IN OUT VOID       **Response OPTIONAL
1239   );
1240
1241 /**
1242   Prompt the user and return the resultant answer to the requestor.
1243
1244   This function is the same as ShellPromptForResponse, except that the prompt is
1245   automatically pulled from HII.
1246
1247   @param[in] Type What type of question is asked.  This is used to filter the input
1248                   to prevent invalid answers to question.
1249   @param[in] HiiFormatStringId   The format string Id for getting from Hii.
1250   @param[in] HiiFormatHandle     The format string Handle for getting from Hii.
1251   @param[in, out] Response       The pointer to Response, which will be populated upon return.
1252
1253   @retval EFI_SUCCESS The operation was sucessful.
1254   @return other       The operation failed.
1255
1256   @sa ShellPromptForResponse
1257 **/
1258 EFI_STATUS
1259 EFIAPI
1260 ShellPromptForResponseHii (
1261   IN SHELL_PROMPT_REQUEST_TYPE         Type,
1262   IN CONST EFI_STRING_ID  HiiFormatStringId,
1263   IN CONST EFI_HII_HANDLE HiiFormatHandle,
1264   IN OUT VOID             **Response
1265   );
1266
1267 /**
1268   Function to determin if an entire string is a valid number.
1269
1270   If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
1271
1272   @param[in] String       The string to evaluate.
1273   @param[in] ForceHex     TRUE - always assume hex.
1274   @param[in] StopAtSpace  TRUE to halt upon finding a space, FALSE to keep going.
1275
1276   @retval TRUE        It is all numeric (dec/hex) characters.
1277   @retval FALSE       There is a non-numeric character.
1278 **/
1279 BOOLEAN
1280 EFIAPI
1281 ShellIsHexOrDecimalNumber (
1282   IN CONST CHAR16   *String,
1283   IN CONST BOOLEAN  ForceHex,
1284   IN CONST BOOLEAN  StopAtSpace
1285   );
1286
1287 /**
1288   Function to verify and convert a string to its numerical 64 bit representation.
1289
1290   If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
1291
1292   @param[in] String       The string to evaluate.
1293   @param[out] Value       Upon a successful return the value of the conversion.
1294   @param[in] ForceHex     TRUE - always assume hex.
1295   @param[in] StopAtSpace  TRUE to halt upon finding a space, FALSE to
1296                           process the entire String.
1297
1298   @retval EFI_SUCCESS             The conversion was successful.
1299   @retval EFI_INVALID_PARAMETER   String contained an invalid character.
1300   @retval EFI_NOT_FOUND           String was a number, but Value was NULL.
1301 **/
1302 EFI_STATUS
1303 EFIAPI
1304 ShellConvertStringToUint64(
1305   IN CONST CHAR16   *String,
1306      OUT   UINT64   *Value,
1307   IN CONST BOOLEAN  ForceHex,
1308   IN CONST BOOLEAN  StopAtSpace
1309   );
1310
1311 /**
1312   Function to determine if a given filename exists.
1313
1314   @param[in] Name         Path to test.
1315
1316   @retval EFI_SUCCESS     The Path represents a file.
1317   @retval EFI_NOT_FOUND   The Path does not represent a file.
1318   @retval other           The path failed to open.
1319 **/
1320 EFI_STATUS
1321 EFIAPI
1322 ShellFileExists(
1323   IN CONST CHAR16 *Name
1324   );
1325
1326 /**
1327   Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned
1328   buffer.  The returned buffer must be callee freed.
1329
1330   If the position upon start is 0, then the Ascii Boolean will be set.  This should be
1331   maintained and not changed for all operations with the same file.
1332
1333   @param[in]       Handle        SHELL_FILE_HANDLE to read from.
1334   @param[in, out]  Ascii         Boolean value for indicating whether the file is
1335                                  Ascii (TRUE) or UCS2 (FALSE).
1336
1337   @return                        The line of text from the file.
1338
1339   @sa ShellFileHandleReadLine
1340 **/
1341 CHAR16*
1342 EFIAPI
1343 ShellFileHandleReturnLine(
1344   IN SHELL_FILE_HANDLE            Handle,
1345   IN OUT BOOLEAN                *Ascii
1346   );
1347
1348 /**
1349   Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE.
1350
1351   If the position upon start is 0, then the Ascii Boolean will be set.  This should be
1352   maintained and not changed for all operations with the same file.
1353
1354   @param[in]       Handle        SHELL_FILE_HANDLE to read from.
1355   @param[in, out]  Buffer        The pointer to buffer to read into.
1356   @param[in, out]  Size          The pointer to number of bytes in Buffer.
1357   @param[in]       Truncate      If the buffer is large enough, this has no effect.
1358                                  If the buffer is is too small and Truncate is TRUE,
1359                                  the line will be truncated.
1360                                  If the buffer is is too small and Truncate is FALSE,
1361                                  then no read will occur.
1362
1363   @param[in, out]  Ascii         Boolean value for indicating whether the file is
1364                                  Ascii (TRUE) or UCS2 (FALSE).
1365
1366   @retval EFI_SUCCESS           The operation was successful.  The line is stored in
1367                                 Buffer.
1368   @retval EFI_END_OF_FILE       There are no more lines in the file.
1369   @retval EFI_INVALID_PARAMETER Handle was NULL.
1370   @retval EFI_INVALID_PARAMETER Size was NULL.
1371   @retval EFI_BUFFER_TOO_SMALL  Size was not large enough to store the line.
1372                                 Size was updated to the minimum space required.
1373 **/
1374 EFI_STATUS
1375 EFIAPI
1376 ShellFileHandleReadLine(
1377   IN SHELL_FILE_HANDLE          Handle,
1378   IN OUT CHAR16                 *Buffer,
1379   IN OUT UINTN                  *Size,
1380   IN BOOLEAN                    Truncate,
1381   IN OUT BOOLEAN                *Ascii
1382   );
1383
1384 /**
1385   Function to delete a file by name
1386
1387   @param[in]       FileName       Pointer to file name to delete.
1388
1389   @retval EFI_SUCCESS             the file was deleted sucessfully
1390   @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
1391                                   deleted
1392   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
1393   @retval EFI_NOT_FOUND           The specified file could not be found on the
1394                                   device or the file system could not be found
1395                                   on the device.
1396   @retval EFI_NO_MEDIA            The device has no medium.
1397   @retval EFI_MEDIA_CHANGED       The device has a different medium in it or the
1398                                   medium is no longer supported.
1399   @retval EFI_DEVICE_ERROR        The device reported an error.
1400   @retval EFI_VOLUME_CORRUPTED    The file system structures are corrupted.
1401   @retval EFI_WRITE_PROTECTED     The file or medium is write protected.
1402   @retval EFI_ACCESS_DENIED       The file was opened read only.
1403   @retval EFI_OUT_OF_RESOURCES    Not enough resources were available to open the
1404                                   file.
1405   @retval other                   The file failed to open
1406 **/
1407 EFI_STATUS
1408 EFIAPI
1409 ShellDeleteFileByName(
1410   IN CONST CHAR16               *FileName
1411   );
1412
1413 /**
1414   Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function.
1415
1416   @param[in] CommandToGetHelpOn  Pointer to a string containing the command name of help file to be printed.
1417   @param[in] SectionToGetHelpOn  Pointer to the section specifier(s).
1418   @param[in] PrintCommandText    If TRUE, prints the command followed by the help content, otherwise prints
1419                                  the help content only.
1420   @retval EFI_DEVICE_ERROR       The help data format was incorrect.
1421   @retval EFI_NOT_FOUND          The help data could not be found.
1422   @retval EFI_SUCCESS            The operation was successful.
1423 **/
1424 EFI_STATUS
1425 EFIAPI
1426 ShellPrintHelp (
1427   IN CONST CHAR16     *CommandToGetHelpOn,
1428   IN CONST CHAR16     *SectionToGetHelpOn,
1429   IN BOOLEAN          PrintCommandText
1430   );
1431
1432 #endif // __SHELL_LIB__