ShellPkg/Include/Library/ShellLib.h

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