ShellPkg/Include/Library/ShellLib.h

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