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<BR>
   5   All rights reserved. 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   EnvironmentVariables and Status are only supported for UEFI Shell 2.0 (or later).
 506   Output is only supported for pre-UEFI Shell 2.0
 507
 508   @param[in] ImageHandle          Parent image that is starting the operation.
 509   @param[in] CommandLine          Pointer to null terminated command line.
 510   @param[in] Output               True to display debug output.  False to hide it.
 511   @param[in] EnvironmentVariables Optional pointer to array of environment variables
 512                                   in the form "x=y".  If NULL current set is used.
 513   @param[out] Status              The status of the run command line.
 514
 515   @retval EFI_SUCCESS             The operation completed sucessfully.  Status
 516                                   contains the status code returned.
 517   @retval EFI_INVALID_PARAMETER   A parameter contains an invalid value.
 518   @retval EFI_OUT_OF_RESOURCES    Out of resources.
 519   @retval EFI_UNSUPPORTED         The operation is not allowed.
 520 **/
 521 EFI_STATUS
 522 EFIAPI
 523 ShellExecute (
 524   IN EFI_HANDLE                 *ParentHandle,
 525   IN CHAR16                     *CommandLine,
 526   IN BOOLEAN                    Output,
 527   IN CHAR16                     **EnvironmentVariables,
 528   OUT EFI_STATUS                *Status
 529   );
 530
 531 /**
 532   Retreives the current directory path.
 533
 534   If the DeviceName is NULL, it returns the current device's current directory
 535   name. If the DeviceName is not NULL, it returns the current directory name
 536   on specified drive.
 537
 538   @param[in] DeviceName         The name of the file system to get directory on.
 539
 540   @retval NULL                  The directory does not exist.
 541   @retval != NULL               The directory.
 542 **/
 543 CONST CHAR16*
 544 EFIAPI
 545 ShellGetCurrentDir (
 546   IN CHAR16                     *DeviceName OPTIONAL
 547   );
 548
 549 /**
 550   Sets (enabled or disabled) the page break mode.
 551
 552   When page break mode is enabled the screen will stop scrolling
 553   and wait for operator input before scrolling a subsequent screen.
 554
 555   @param[in] CurrentState       TRUE to enable and FALSE to disable.
 556 **/
 557 VOID
 558 EFIAPI
 559 ShellSetPageBreakMode (
 560   IN BOOLEAN                    CurrentState
 561   );
 562
 563 /**
 564   Opens a group of files based on a path.
 565
 566   This function uses the Arg to open all the matching files. Each matched
 567   file has a SHELL_FILE_ARG structure to record the file information. These
 568   structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG
 569   structures from ListHead to access each file. This function supports wildcards
 570   and will process '?' and '*' as such.  The list must be freed with a call to
 571   ShellCloseFileMetaArg().
 572
 573   If you are NOT appending to an existing list *ListHead must be NULL.  If
 574   *ListHead is NULL then it must be callee freed.
 575
 576   @param[in] Arg                Pointer to path string.
 577   @param[in] OpenMode           Mode to open files with.
 578   @param[in] ListHead           Head of linked list of results.
 579
 580   @retval EFI_SUCCESS           The operation was sucessful and the list head
 581                                 contains the list of opened files.
 582   @retval != EFI_SUCCESS        The operation failed.
 583
 584   @sa InternalShellConvertFileListType
 585 **/
 586 EFI_STATUS
 587 EFIAPI
 588 ShellOpenFileMetaArg (
 589   IN CHAR16                     *Arg,
 590   IN UINT64                     OpenMode,
 591   IN OUT EFI_SHELL_FILE_INFO    **ListHead
 592   );
 593
 594 /**
 595   Free the linked list returned from ShellOpenFileMetaArg.
 596
 597   @param[in] ListHead           The pointer to free.
 598
 599   @retval EFI_SUCCESS           The operation was sucessful.
 600   @retval EFI_INVALID_PARAMETER A parameter was invalid.
 601 **/
 602 EFI_STATUS
 603 EFIAPI
 604 ShellCloseFileMetaArg (
 605   IN OUT EFI_SHELL_FILE_INFO    **ListHead
 606   );
 607
 608 /**
 609   Find a file by searching the CWD and then the path.
 610
 611   If FileName is NULL, then ASSERT.
 612
 613   If the return value is not NULL then the memory must be caller freed.
 614
 615   @param[in] FileName           Filename string.
 616
 617   @retval NULL                  The file was not found.
 618   @retval !NULL                 The path to the file.
 619 **/
 620 CHAR16 *
 621 EFIAPI
 622 ShellFindFilePath (
 623   IN CONST CHAR16 *FileName
 624   );
 625
 626 /**
 627   Find a file by searching the CWD and then the path with a variable set of file
 628   extensions.  If the file is not found it will append each extension in the list
 629   in the order provided and return the first one that is successful.
 630
 631   If FileName is NULL, then ASSERT.
 632   If FileExtension is NULL, then behavior is identical to ShellFindFilePath.
 633
 634   If the return value is not NULL then the memory must be caller freed.
 635
 636   @param[in] FileName           Filename string.
 637   @param[in] FileExtension      Semi-colon delimeted list of possible extensions.
 638
 639   @retval NULL                  The file was not found.
 640   @retval !NULL                 The path to the file.
 641 **/
 642 CHAR16 *
 643 EFIAPI
 644 ShellFindFilePathEx (
 645   IN CONST CHAR16 *FileName,
 646   IN CONST CHAR16 *FileExtension
 647   );
 648
 649 typedef enum {
 650   TypeFlag  = 0,    ///< A flag that is present or not present only (IE "-a").
 651   TypeValue,        ///< A flag that has some data following it with a space (IE "-a 1").
 652   TypePosition,     ///< Some data that did not follow a parameter (IE "filename.txt").
 653   TypeStart,        ///< A flag that has variable value appended to the end (IE "-ad", "-afd", "-adf", etc...).
 654   TypeDoubleValue,  ///< A flag that has 2 space seperated value data following it (IE "-a 1 2").
 655   TypeMaxValue,     ///< A flag followed by all the command line data before the next flag.
 656   TypeMax,
 657 } ParamType;
 658
 659 typedef struct {
 660   CHAR16      *Name;
 661   ParamType   Type;
 662 } SHELL_PARAM_ITEM;
 663
 664
 665 /// Helper structure for no parameters (besides -? and -b)
 666 extern SHELL_PARAM_ITEM EmptyParamList[];
 667
 668 /**
 669   Checks the command line arguments passed against the list of valid ones.
 670   Optionally removes NULL values first.
 671
 672   If no initialization is required, then return RETURN_SUCCESS.
 673
 674   @param[in] CheckList          Pointer to list of parameters to check.
 675   @param[out] CheckPackage      Package of checked values.
 676   @param[out] ProblemParam      Optional pointer to pointer to unicode string for
 677                                 the paramater that caused failure.
 678   @param[in] AutoPageBreak      Will automatically set PageBreakEnabled.
 679   @param[in] AlwaysAllowNumbers Will never fail for number based flags.
 680
 681   @retval EFI_SUCCESS           The operation completed sucessfully.
 682   @retval EFI_OUT_OF_RESOURCES  A memory allocation failed.
 683   @retval EFI_INVALID_PARAMETER A parameter was invalid.
 684   @retval EFI_VOLUME_CORRUPTED  The command line was corrupt.  An argument was
 685                                 duplicated.  The duplicated command line argument
 686                                 was returned in ProblemParam if provided.
 687   @retval EFI_DEVICE_ERROR      The commands contained 2 opposing arguments.  One
 688                                 of the command line arguments was returned in
 689                                 ProblemParam if provided.
 690   @retval EFI_NOT_FOUND         A argument required a value that was missing.
 691                                 The invalid command line argument was returned in
 692                                 ProblemParam if provided.
 693 **/
 694 EFI_STATUS
 695 EFIAPI
 696 ShellCommandLineParseEx (
 697   IN CONST SHELL_PARAM_ITEM     *CheckList,
 698   OUT LIST_ENTRY                **CheckPackage,
 699   OUT CHAR16                    **ProblemParam OPTIONAL,
 700   IN BOOLEAN                    AutoPageBreak,
 701   IN BOOLEAN                    AlwaysAllowNumbers
 702   );
 703
 704 /// Make it easy to upgrade from older versions of the shell library.
 705 #define ShellCommandLineParse(CheckList,CheckPackage,ProblemParam,AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE)
 706
 707 /**
 708   Frees shell variable list that was returned from ShellCommandLineParse.
 709
 710   This function will free all the memory that was used for the CheckPackage
 711   list of postprocessed shell arguments.
 712
 713   If CheckPackage is NULL, then return.
 714
 715   @param[in] CheckPackage       The list to de-allocate.
 716   **/
 717 VOID
 718 EFIAPI
 719 ShellCommandLineFreeVarList (
 720   IN LIST_ENTRY                 *CheckPackage
 721   );
 722
 723 /**
 724   Checks for presence of a flag parameter.
 725
 726   Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key.
 727
 728   If CheckPackage is NULL then return FALSE.
 729   If KeyString is NULL then ASSERT().
 730
 731   @param[in] CheckPackage       The package of parsed command line arguments.
 732   @param[in] KeyString          The Key of the command line argument to check for.
 733
 734   @retval TRUE                  The flag is on the command line.
 735   @retval FALSE                 The flag is not on the command line.
 736   **/
 737 BOOLEAN
 738 EFIAPI
 739 ShellCommandLineGetFlag (
 740   IN CONST LIST_ENTRY              *CheckPackage,
 741   IN CHAR16                        *KeyString
 742   );
 743
 744 /**
 745   Returns value from command line argument.
 746
 747   Value parameters are in the form of "-<Key> value" or "/<Key> value".
 748
 749   If CheckPackage is NULL, then return NULL.
 750
 751   @param[in] CheckPackage       The package of parsed command line arguments.
 752   @param[in] KeyString          The Key of the command line argument to check for.
 753
 754   @retval NULL                  The flag is not on the command line.
 755   @retval !=NULL                Pointer to unicode string of the value.
 756   **/
 757 CONST CHAR16*
 758 EFIAPI
 759 ShellCommandLineGetValue (
 760   IN CONST LIST_ENTRY              *CheckPackage,
 761   IN CHAR16                        *KeyString
 762   );
 763
 764 /**
 765   Returns raw value from command line argument.
 766
 767   Raw value parameters are in the form of "value" in a specific position in the list.
 768
 769   If CheckPackage is NULL, then return NULL.
 770
 771   @param[in] CheckPackage       The package of parsed command line arguments.
 772   @param[in] Position           The position of the value.
 773
 774   @retval NULL                  The flag is not on the command line.
 775   @retval !=NULL                Pointer to unicode string of the value.
 776   **/
 777 CONST CHAR16*
 778 EFIAPI
 779 ShellCommandLineGetRawValue (
 780   IN CONST LIST_ENTRY              *CheckPackage,
 781   IN UINT32                        Position
 782   );
 783
 784 /**
 785   Returns the number of command line value parameters that were parsed.
 786
 787   This will not include flags.
 788
 789   @retval (UINTN)-1     No parsing has ocurred.
 790   @return               The number of value parameters found.
 791 **/
 792 UINTN
 793 EFIAPI
 794 ShellCommandLineGetCount(
 795   VOID
 796   );
 797
 798 /**
 799   Determins if a parameter is duplicated.
 800
 801   If Param is not NULL then it will point to a callee allocated string buffer
 802   with the parameter value if a duplicate is found.
 803
 804   If CheckPackage is NULL, then ASSERT.
 805
 806   @param[in] CheckPackage       The package of parsed command line arguments.
 807   @param[out] Param             Upon finding one, a pointer to the duplicated parameter.
 808
 809   @retval EFI_SUCCESS           No parameters were duplicated.
 810   @retval EFI_DEVICE_ERROR      A duplicate was found.
 811   **/
 812 EFI_STATUS
 813 EFIAPI
 814 ShellCommandLineCheckDuplicate (
 815   IN CONST LIST_ENTRY              *CheckPackage,
 816   OUT CHAR16                       **Param
 817   );
 818
 819 /**
 820   This function causes the shell library to initialize itself.  If the shell library
 821   is already initialized it will de-initialize all the current protocol poitners and
 822   re-populate them again.
 823
 824   When the library is used with PcdShellLibAutoInitialize set to true this function
 825   will return EFI_SUCCESS and perform no actions.
 826
 827   This function is intended for internal access for shell commands only.
 828
 829   @retval EFI_SUCCESS   the initialization was complete sucessfully
 830
 831 **/
 832 EFI_STATUS
 833 EFIAPI
 834 ShellInitialize (
 835   VOID
 836   );
 837
 838 /**
 839   Print at a specific location on the screen.
 840
 841   This function will move the cursor to a given screen location and print the specified string.
 842
 843   If -1 is specified for either the Row or Col the current screen location for BOTH
 844   will be used.
 845
 846   If either Row or Col is out of range for the current console, then ASSERT.
 847   If Format is NULL, then ASSERT.
 848
 849   In addition to the standard %-based flags as supported by UefiLib Print() this supports
 850   the following additional flags:
 851     %N       -   Set output attribute to normal
 852     %H       -   Set output attribute to highlight
 853     %E       -   Set output attribute to error
 854     %B       -   Set output attribute to blue color
 855     %V       -   Set output attribute to green color
 856
 857   Note: The background color is controlled by the shell command cls.
 858
 859   @param[in] Row        The row to print at.
 860   @param[in] Col        The column to print at.
 861   @param[in] Format     The format string.
 862
 863   @return The number of characters printed to the screen.
 864 **/
 865
 866 UINTN
 867 EFIAPI
 868 ShellPrintEx(
 869   IN INT32                Col OPTIONAL,
 870   IN INT32                Row OPTIONAL,
 871   IN CONST CHAR16         *Format,
 872   ...
 873   );
 874
 875 /**
 876   Print at a specific location on the screen.
 877
 878   This function will move the cursor to a given screen location and print the specified string.
 879
 880   If -1 is specified for either the Row or Col the current screen location for BOTH
 881   will be used.
 882
 883   If either Row or Col is out of range for the current console, then ASSERT.
 884   If Format is NULL, then ASSERT.
 885
 886   In addition to the standard %-based flags as supported by UefiLib Print() this supports
 887   the following additional flags:
 888     %N       -   Set output attribute to normal.
 889     %H       -   Set output attribute to highlight.
 890     %E       -   Set output attribute to error.
 891     %B       -   Set output attribute to blue color.
 892     %V       -   Set output attribute to green color.
 893
 894   Note: The background color is controlled by the shell command cls.
 895
 896   @param[in] Row                The row to print at.
 897   @param[in] Col                The column to print at.
 898   @param[in] HiiFormatStringId  The format string Id for getting from Hii.
 899   @param[in] HiiFormatHandle    The format string Handle for getting from Hii.
 900
 901   @return the number of characters printed to the screen.
 902 **/
 903 UINTN
 904 EFIAPI
 905 ShellPrintHiiEx(
 906   IN INT32                Col OPTIONAL,
 907   IN INT32                Row OPTIONAL,
 908   IN CONST EFI_STRING_ID  HiiFormatStringId,
 909   IN CONST EFI_HANDLE     HiiFormatHandle,
 910   ...
 911   );
 912
 913 /**
 914   Function to determine if a given filename represents a directory.
 915
 916   If DirName is NULL, then ASSERT.
 917
 918   @param[in] DirName      Path to directory to test.
 919
 920   @retval EFI_SUCCESS     The Path represents a directory.
 921   @retval EFI_NOT_FOUND   The Path does not represent a directory.
 922   @retval other           The path failed to open.
 923 **/
 924 EFI_STATUS
 925 EFIAPI
 926 ShellIsDirectory(
 927   IN CONST CHAR16 *DirName
 928   );
 929
 930 /**
 931   Function to determine if a given filename represents a file.
 932
 933   This will search the CWD only.
 934
 935   If Name is NULL, then ASSERT.
 936
 937   @param[in] Name         Path to file to test.
 938
 939   @retval EFI_SUCCESS     The Path represents a file.
 940   @retval EFI_NOT_FOUND   The Path does not represent a file.
 941   @retval other           The path failed to open.
 942 **/
 943 EFI_STATUS
 944 EFIAPI
 945 ShellIsFile(
 946   IN CONST CHAR16 *Name
 947   );
 948
 949 /**
 950   Function to determine if a given filename represents a file.
 951
 952   This will search the CWD and then the Path.
 953
 954   If Name is NULL, then ASSERT.
 955
 956   @param[in] Name         Path to file to test.
 957
 958   @retval EFI_SUCCESS     The Path represents a file.
 959   @retval EFI_NOT_FOUND   The Path does not represent a file.
 960   @retval other           The path failed to open.
 961 **/
 962 EFI_STATUS
 963 EFIAPI
 964 ShellIsFileInPath(
 965   IN CONST CHAR16 *Name
 966   );
 967
 968 /**
 969   Function to determine whether a string is decimal or hex representation of a number
 970   and return the number converted from the string.
 971
 972   @param[in] String   String representation of a number
 973
 974   @return             The unsigned integer result of the conversion.
 975 **/
 976 UINTN
 977 EFIAPI
 978 ShellStrToUintn(
 979   IN CONST CHAR16 *String
 980   );
 981
 982 /**
 983   Safely append with automatic string resizing given length of Destination and
 984   desired length of copy from Source.
 985
 986   Append the first D characters of Source to the end of Destination, where D is
 987   the lesser of Count and the StrLen() of Source. If appending those D characters
 988   will fit within Destination (whose Size is given as CurrentSize) and
 989   still leave room for a null terminator, then those characters are appended,
 990   starting at the original terminating null of Destination, and a new terminating
 991   null is appended.
 992
 993   If appending D characters onto Destination will result in a overflow of the size
 994   given in CurrentSize the string will be grown such that the copy can be performed
 995   and CurrentSize will be updated to the new size.
 996
 997   If Source is NULL, there is nothing to append, just return the current buffer in
 998   Destination.
 999
1000   If Destination is NULL, then ASSERT().
1001   If Destination's current length (including NULL terminator) is already more than
1002   CurrentSize, then ASSERT().
1003
1004   @param[in,out] Destination    The String to append onto.
1005   @param[in,out] CurrentSize    On call the number of bytes in Destination.  On
1006                                 return possibly the new size (still in bytes).  If NULL
1007                                 then allocate whatever is needed.
1008   @param[in]     Source         The String to append from.
1009   @param[in]     Count          Maximum number of characters to append.  If 0 then
1010                                 all are appended.
1011
1012   @return                       The Destination after apending the Source.
1013 **/
1014 CHAR16*
1015 EFIAPI
1016 StrnCatGrow (
1017   IN OUT CHAR16           **Destination,
1018   IN OUT UINTN            *CurrentSize,
1019   IN     CONST CHAR16     *Source,
1020   IN     UINTN            Count
1021   );
1022
1023 /**
1024   This is a find and replace function.  Upon successful return the NewString is a copy of
1025   SourceString with each instance of FindTarget replaced with ReplaceWith.
1026
1027   If SourceString and NewString overlap the behavior is undefined.
1028
1029   If the string would grow bigger than NewSize it will halt and return error.
1030
1031   @param[in] SourceString             String with source buffer.
1032   @param[in,out] NewString            String with resultant buffer.
1033   @param[in] NewSize                  Size in bytes of NewString.
1034   @param[in] FindTarget               String to look for.
1035   @param[in] ReplaceWith              String to replace FindTarget with.
1036   @param[in] SkipPreCarrot            If TRUE will skip a FindTarget that has a '^'
1037                                       immediately before it.
1038
1039   @retval EFI_INVALID_PARAMETER       SourceString was NULL.
1040   @retval EFI_INVALID_PARAMETER       NewString was NULL.
1041   @retval EFI_INVALID_PARAMETER       FindTarget was NULL.
1042   @retval EFI_INVALID_PARAMETER       ReplaceWith was NULL.
1043   @retval EFI_INVALID_PARAMETER       FindTarget had length < 1.
1044   @retval EFI_INVALID_PARAMETER       SourceString had length < 1.
1045   @retval EFI_BUFFER_TOO_SMALL        NewSize was less than the minimum size to hold
1046                                       the new string (truncation occurred).
1047   @retval EFI_SUCCESS                 The string was sucessfully copied with replacement.
1048 **/
1049
1050 EFI_STATUS
1051 EFIAPI
1052 ShellCopySearchAndReplace2(
1053   IN CHAR16 CONST                     *SourceString,
1054   IN CHAR16                           *NewString,
1055   IN UINTN                            NewSize,
1056   IN CONST CHAR16                     *FindTarget,
1057   IN CONST CHAR16                     *ReplaceWith,
1058   IN CONST BOOLEAN                    SkipPreCarrot
1059   );
1060
1061 ///
1062 /// make upgrades easier from old version
1063 ///
1064 #define ShellLibCopySearchAndReplace(a,b,c,d,e) ShellCopySearchAndReplace2(a,b,c,d,e,FALSE)
1065
1066 /**
1067   Check if a Unicode character is a hexadecimal character.
1068
1069   This internal function checks if a Unicode character is a
1070   decimal character.  The valid hexadecimal character is
1071   L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
1072
1073   @param[in]  Char  The character to check.
1074
1075   @retval TRUE      The Char is a hexadecmial character.
1076   @retval FALSE     The Char is not a hexadecmial character.
1077
1078 **/
1079 BOOLEAN
1080 EFIAPI
1081 ShellIsHexaDecimalDigitCharacter (
1082   IN      CHAR16                    Char
1083   );
1084
1085 #endif // __SHELL_LIB__