ShellPkg/Include/Library/ShellLib.h

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