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