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