ShellPkg/Include/Library/FileHandleLib.h

   1 /** @file
   2   Provides interface to EFI_FILE_HANDLE functionality.
   3
   4 Copyright (c) 2006 - 2009, Intel Corporation
   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 #include <Uefi.h>
  16 #include <Library/UefiBootServicesTableLib.h>
  17 #include <Library/BaseLib.h>
  18 #include <Library/BaseMemoryLib.h>
  19 #include <Library/DebugLib.h>
  20 #include <Library/MemoryAllocationLib.h>
  21
  22 /**
  23   This function will retrieve the information about the file for the handle
  24   specified and store it in allocated pool memory.
  25
  26   This function allocates a buffer to store the file\92s information. It is the
  27   caller\92s responsibility to free the buffer
  28
  29   @param  FileHandle  The file handle of the file for which information is
  30   being requested.
  31
  32   @retval NULL information could not be retrieved.
  33
  34   @return the information about the file
  35 **/
  36 EFI_FILE_INFO*
  37 EFIAPI
  38 FileHandleGetInfo (
  39   IN EFI_FILE_HANDLE            FileHandle
  40   );
  41
  42 /**
  43   This function will set the information about the file for the opened handle
  44   specified.
  45
  46   @param  FileHandle            The file handle of the file for which information
  47   is being set
  48
  49   @param  FileInfo              The infotmation to set.
  50
  51   @retval EFI_SUCCESS           The information was set.
  52   @retval EFI_UNSUPPORTED The InformationType is not known.
  53   @retval EFI_NO_MEDIA          The device has no medium.
  54   @retval EFI_DEVICE_ERROR      The device reported an error.
  55   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
  56   @retval EFI_WRITE_PROTECTED   The file or medium is write protected.
  57   @retval EFI_ACCESS_DENIED     The file was opened read only.
  58   @retval EFI_VOLUME_FULL       The volume is full.
  59 **/
  60 EFI_STATUS
  61 EFIAPI
  62 FileHandleSetInfo (
  63   IN EFI_FILE_HANDLE            FileHandle,
  64   IN CONST EFI_FILE_INFO        *FileInfo
  65   );
  66
  67 /**
  68   This function reads information from an opened file.
  69
  70   If FileHandle is not a directory, the function reads the requested number of
  71   bytes from the file at the file\92s current position and returns them in Buffer.
  72   If the read goes beyond the end of the file, the read length is truncated to the
  73   end of the file. The file\92s current position is increased by the number of bytes
  74   returned.  If FileHandle is a directory, the function reads the directory entry
  75   at the file\92s current position and returns the entry in Buffer. If the Buffer
  76   is not large enough to hold the current directory entry, then
  77   EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated.
  78   BufferSize is set to be the size of the buffer needed to read the entry. On
  79   success, the current position is updated to the next directory entry. If there
  80   are no more directory entries, the read returns a zero-length buffer.
  81   EFI_FILE_INFO is the structure returned as the directory entry.
  82
  83   @param FileHandle             the opened file handle
  84   @param BufferSize             on input the size of buffer in bytes.  on return
  85                                 the number of bytes written.
  86   @param Buffer                 the buffer to put read data into.
  87
  88   @retval EFI_SUCCESS             Data was read.
  89   @retval EFI_NO_MEDIA          The device has no media.
  90   @retval EFI_DEVICE_ERROR      The device reported an error.
  91   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
  92   @retval EFI_BUFFER_TO_SMALL   Buffer is too small. ReadSize contains required
  93                                 size.
  94
  95 **/
  96 EFI_STATUS
  97 EFIAPI
  98 FileHandleRead(
  99   IN EFI_FILE_HANDLE            FileHandle,
 100   IN OUT UINTN                  *BufferSize,
 101   OUT VOID                      *Buffer
 102   );
 103
 104 /**
 105   Write data to a file.
 106
 107   This function writes the specified number of bytes to the file at the current
 108   file position. The current file position is advanced the actual number of bytes
 109   written, which is returned in BufferSize. Partial writes only occur when there
 110   has been a data error during the write attempt (such as \93volume space full\94).
 111   The file is automatically grown to hold the data if required. Direct writes to
 112   opened directories are not supported.
 113
 114   @param FileHandle           The opened file for writing
 115   @param BufferSize           on input the number of bytes in Buffer.  On output
 116                               the number of bytes written.
 117   @param Buffer               the buffer containing data to write is stored.
 118
 119  @retval EFI_SUCCESS            Data was written.
 120  @retval EFI_UNSUPPORTED            Writes to an open directory are not supported.
 121  @retval EFI_NO_MEDIA           The device has no media.
 122  @retval EFI_DEVICE_ERROR           The device reported an error.
 123  @retval EFI_VOLUME_CORRUPTED   The file system structures are corrupted.
 124  @retval EFI_WRITE_PROTECTED    The device is write-protected.
 125  @retval EFI_ACCESS_DENIED        The file was open for read only.
 126  @retval EFI_VOLUME_FULL            The volume is full.
 127 **/
 128 EFI_STATUS
 129 EFIAPI
 130 FileHandleWrite(
 131   IN EFI_FILE_HANDLE            FileHandle,
 132   IN OUT UINTN                  *BufferSize,
 133   IN VOID                       *Buffer
 134   );
 135
 136 /**
 137   Close an open file handle.
 138
 139   This function closes a specified file handle. All \93dirty\94 cached file data is
 140   flushed to the device, and the file is closed. In all cases the handle is
 141   closed.
 142
 143 @param FileHandle               the file handle to close.
 144
 145 @retval EFI_SUCCESS             the file handle was closed sucessfully.
 146 **/
 147 EFI_STATUS
 148 EFIAPI
 149 FileHandleClose (
 150   IN EFI_FILE_HANDLE            FileHandle
 151   );
 152
 153 /**
 154   Delete a file and close the handle
 155
 156   This function closes and deletes a file. In all cases the file handle is closed.
 157   If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is
 158   returned, but the handle is still closed.
 159
 160   @param FileHandle             the file handle to delete
 161
 162   @retval EFI_SUCCESS           the file was closed sucessfully
 163   @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
 164                                 deleted
 165   @retval INVALID_PARAMETER     One of the parameters has an invalid value.
 166 **/
 167 EFI_STATUS
 168 EFIAPI
 169 FileHandleDelete (
 170   IN EFI_FILE_HANDLE            FileHandle
 171   );
 172
 173 /**
 174   Set the current position in a file.
 175
 176   This function sets the current file position for the handle to the position
 177   supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only
 178   absolute positioning is supported, and seeking past the end of the file is
 179   allowed (a subsequent write would grow the file). Seeking to position
 180   0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file.
 181   If FileHandle is a directory, the only position that may be set is zero. This
 182   has the effect of starting the read process of the directory entries over.
 183
 184   @param FileHandle             The file handle on which the position is being set
 185   @param Position               Byte position from begining of file
 186
 187   @retval EFI_SUCCESS           Operation completed sucessfully.
 188   @retval EFI_UNSUPPORTED       the seek request for non-zero is not valid on
 189                                 directories.
 190   @retval INVALID_PARAMETER     One of the parameters has an invalid value.
 191 **/
 192 EFI_STATUS
 193 EFIAPI
 194 FileHandleSetPosition (
 195   IN EFI_FILE_HANDLE    FileHandle,
 196   IN UINT64             Position
 197   );
 198
 199 /**
 200   Gets a file's current position
 201
 202   This function retrieves the current file position for the file handle. For
 203   directories, the current file position has no meaning outside of the file
 204   system driver and as such the operation is not supported. An error is returned
 205   if FileHandle is a directory.
 206
 207   @param FileHandle             The open file handle on which to get the position.
 208   @param Position               Byte position from begining of file.
 209
 210   @retval EFI_SUCCESS           the operation completed sucessfully.
 211   @retval INVALID_PARAMETER     One of the parameters has an invalid value.
 212   @retval EFI_UNSUPPORTED       the request is not valid on directories.
 213 **/
 214 EFI_STATUS
 215 EFIAPI
 216 FileHandleGetPosition (
 217   IN EFI_FILE_HANDLE            FileHandle,
 218   OUT UINT64                    *Position
 219   );
 220 /**
 221   Flushes data on a file
 222
 223   This function flushes all modified data associated with a file to a device.
 224
 225   @param FileHandle             The file handle on which to flush data
 226
 227   @retval EFI_SUCCESS           The data was flushed.
 228   @retval EFI_NO_MEDIA          The device has no media.
 229   @retval EFI_DEVICE_ERROR      The device reported an error.
 230   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 231   @retval EFI_WRITE_PROTECTED   The file or medium is write protected.
 232   @retval EFI_ACCESS_DENIED     The file was opened for read only.
 233 **/
 234 EFI_STATUS
 235 EFIAPI
 236 FileHandleFlush (
 237   IN EFI_FILE_HANDLE            FileHandle
 238   );
 239
 240 /**
 241   function to determine if a given handle is a directory handle
 242
 243   if DirHandle is NULL then ASSERT()
 244
 245   open the file information on the DirHandle and verify that the Attribute
 246   includes EFI_FILE_DIRECTORY bit set.
 247
 248   @param DirHandle              Handle to open file
 249
 250   @retval EFI_SUCCESS           DirHandle is a directory
 251   @retval EFI_INVALID_PARAMETER DirHandle did not have EFI_FILE_INFO available
 252   @retval EFI_NOT_FOUND         DirHandle is not a directory
 253 **/
 254 EFI_STATUS
 255 EFIAPI
 256 FileHandleIsDirectory (
 257   IN EFI_FILE_HANDLE            DirHandle
 258   );
 259
 260 /**
 261   Retrieves the first file from a directory
 262
 263   This function opens a directory and gets the first file\92s info in the
 264   directory. Caller can use FileHandleFindNextFile() to get other files.  When
 265   complete the caller is responsible for calling FreePool() on *Buffer.
 266
 267   @param DirHandle              The file handle of the directory to search
 268   @param Buffer                 Pointer to pointer to buffer for file's information
 269
 270   @retval EFI_SUCCESS           Found the first file.
 271   @retval EFI_NOT_FOUND         Cannot find the directory.
 272   @retval EFI_NO_MEDIA          The device has no media.
 273   @retval EFI_DEVICE_ERROR      The device reported an error.
 274   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 275   @return Others                status of FileHandleGetInfo, FileHandleSetPosition,
 276                                 or FileHandleRead
 277 **/
 278 EFI_STATUS
 279 EFIAPI
 280 FileHandleFindFirstFile (
 281   IN EFI_FILE_HANDLE            DirHandle,
 282   OUT EFI_FILE_INFO             **Buffer
 283   );
 284 /**
 285   Retrieves the next file in a directory.
 286
 287   To use this function, caller must call the FileHandleFindFirstFile() to get the
 288   first file, and then use this function get other files. This function can be
 289   called for several times to get each file's information in the directory. If
 290   the call of FileHandleFindNextFile() got the last file in the directory, the next
 291   call of this function has no file to get. *NoFile will be set to TRUE and the
 292   Buffer memory will be automatically freed.
 293
 294   @param DirHandle              the file handle of the directory
 295   @param Buffer                             pointer to buffer for file's information
 296   @param NoFile                             pointer to boolean when last file is found
 297
 298   @retval EFI_SUCCESS           Found the next file, or reached last file
 299   @retval EFI_NO_MEDIA          The device has no media.
 300   @retval EFI_DEVICE_ERROR      The device reported an error.
 301   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 302 **/
 303 EFI_STATUS
 304 EFIAPI
 305 FileHandleFindNextFile(
 306   IN EFI_FILE_HANDLE             DirHandle,
 307   OUT EFI_FILE_INFO              *Buffer,
 308   OUT BOOLEAN                    *NoFile
 309   );
 310
 311 /**
 312   Retrieve the size of a file.
 313
 314   if FileHandle is NULL then ASSERT()
 315   if Size is NULL then ASSERT()
 316
 317   This function extracts the file size info from the FileHandle\92s EFI_FILE_INFO
 318   data.
 319
 320   @param FileHandle             file handle from which size is retrieved
 321   @param Size                   pointer to size
 322
 323   @retval EFI_SUCCESS           operation was completed sucessfully
 324   @retval EFI_DEVICE_ERROR      cannot access the file
 325 **/
 326 EFI_STATUS
 327 EFIAPI
 328 FileHandleGetSize (
 329   IN EFI_FILE_HANDLE            FileHandle,
 330   OUT UINT64                    *Size
 331   );