| /** @file | |
| Provides interface to EFI_FILE_HANDLE functionality. | |
| Copyright (c) 2009-2010, Intel Corporation. All rights reserved.<BR> | |
| This program and the accompanying materials | |
| are licensed and made available under the terms and conditions of the BSD License | |
| which accompanies this distribution. The full text of the license may be found at | |
| http://opensource.org/licenses/bsd-license.php | |
| THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, | |
| WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. | |
| **/ | |
| #if !defined (_FILE_HANDLE_LIBRARY_HEADER_) | |
| #define _FILE_HANDLE_LIBRARY_HEADER_ | |
| /// Tag for use in identifying UNICODE files. | |
| /// If the file is UNICODE the first 16 bits of the file will equal this value. | |
| enum { | |
| UnicodeFileTag = 0xFEFF | |
| }; | |
| /** | |
| This function will retrieve the information about the file for the handle | |
| specified and store it in allocated pool memory. | |
| This function allocates a buffer to store the file's information. It is the | |
| caller's responsibility to free the buffer. | |
| @param FileHandle The file handle of the file for which information is | |
| being requested. | |
| @retval NULL information could not be retrieved. | |
| @retval !NULL the information about the file | |
| **/ | |
| EFI_FILE_INFO* | |
| EFIAPI | |
| FileHandleGetInfo ( | |
| IN EFI_FILE_HANDLE FileHandle | |
| ); | |
| /** | |
| This function will set the information about the file for the opened handle | |
| specified. | |
| @param FileHandle The file handle of the file for which information | |
| is being set. | |
| @param FileInfo The information to set. | |
| @retval EFI_SUCCESS The information was set. | |
| @retval EFI_INVALID_PARAMETER A Parameter was out of range or invalid. | |
| @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. | |
| @retval EFI_NO_MEDIA The device has no medium. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. | |
| @retval EFI_WRITE_PROTECTED The file or medium is write protected. | |
| @retval EFI_ACCESS_DENIED The file was opened read only. | |
| @retval EFI_VOLUME_FULL The volume is full. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleSetInfo ( | |
| IN EFI_FILE_HANDLE FileHandle, | |
| IN CONST EFI_FILE_INFO *FileInfo | |
| ); | |
| /** | |
| This function reads information from an opened file. | |
| If FileHandle is not a directory, the function reads the requested number of | |
| bytes from the file at the file's current position and returns them in Buffer. | |
| If the read goes beyond the end of the file, the read length is truncated to the | |
| end of the file. The file's current position is increased by the number of bytes | |
| returned. If FileHandle is a directory, the function reads the directory entry | |
| at the file's current position and returns the entry in Buffer. If the Buffer | |
| is not large enough to hold the current directory entry, then | |
| EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated. | |
| BufferSize is set to be the size of the buffer needed to read the entry. On | |
| success, the current position is updated to the next directory entry. If there | |
| are no more directory entries, the read returns a zero-length buffer. | |
| EFI_FILE_INFO is the structure returned as the directory entry. | |
| @param FileHandle The opened file handle. | |
| @param BufferSize On input the size of buffer in bytes. On return | |
| the number of bytes written. | |
| @param Buffer The buffer to put read data into. | |
| @retval EFI_SUCCESS Data was read. | |
| @retval EFI_NO_MEDIA The device has no media. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. | |
| @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required | |
| size. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleRead( | |
| IN EFI_FILE_HANDLE FileHandle, | |
| IN OUT UINTN *BufferSize, | |
| OUT VOID *Buffer | |
| ); | |
| /** | |
| Write data to a file. | |
| This function writes the specified number of bytes to the file at the current | |
| file position. The current file position is advanced the actual number of bytes | |
| written, which is returned in BufferSize. Partial writes only occur when there | |
| has been a data error during the write attempt (such as "volume space full"). | |
| The file is automatically grown to hold the data if required. Direct writes to | |
| opened directories are not supported. | |
| @param FileHandle The opened file for writing | |
| @param BufferSize On input the number of bytes in Buffer. On output | |
| the number of bytes written. | |
| @param Buffer The buffer containing data to write is stored. | |
| @retval EFI_SUCCESS Data was written. | |
| @retval EFI_UNSUPPORTED Writes to an open directory are not supported. | |
| @retval EFI_NO_MEDIA The device has no media. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. | |
| @retval EFI_WRITE_PROTECTED The device is write-protected. | |
| @retval EFI_ACCESS_DENIED The file was open for read only. | |
| @retval EFI_VOLUME_FULL The volume is full. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleWrite( | |
| IN EFI_FILE_HANDLE FileHandle, | |
| IN OUT UINTN *BufferSize, | |
| IN VOID *Buffer | |
| ); | |
| /** | |
| Close an open file handle. | |
| This function closes a specified file handle. All "dirty" cached file data is | |
| flushed to the device, and the file is closed. In all cases the handle is | |
| closed. | |
| @param FileHandle The file handle to close. | |
| @retval EFI_SUCCESS The file handle was closed sucessfully. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleClose ( | |
| IN EFI_FILE_HANDLE FileHandle | |
| ); | |
| /** | |
| Delete a file and close the handle. | |
| This function closes and deletes a file. In all cases the file handle is closed. | |
| If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is | |
| returned, but the handle is still closed. | |
| @param FileHandle The file handle to delete. | |
| @retval EFI_SUCCESS The file was closed sucessfully. | |
| @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not | |
| deleted | |
| @retval INVALID_PARAMETER One of the parameters has an invalid value. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleDelete ( | |
| IN EFI_FILE_HANDLE FileHandle | |
| ); | |
| /** | |
| Set the current position in a file. | |
| This function sets the current file position for the handle to the position | |
| supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only | |
| absolute positioning is supported, and seeking past the end of the file is | |
| allowed (a subsequent write would grow the file). Seeking to position | |
| 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file. | |
| If FileHandle is a directory, the only position that may be set is zero. This | |
| has the effect of starting the read process of the directory entries over. | |
| @param FileHandle The file handle on which the position is being set | |
| @param Position Byte position from begining of file | |
| @retval EFI_SUCCESS Operation completed sucessfully. | |
| @retval EFI_UNSUPPORTED the seek request for non-zero is not valid on | |
| directories. | |
| @retval INVALID_PARAMETER One of the parameters has an invalid value. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleSetPosition ( | |
| IN EFI_FILE_HANDLE FileHandle, | |
| IN UINT64 Position | |
| ); | |
| /** | |
| Gets a file's current position. | |
| This function retrieves the current file position for the file handle. For | |
| directories, the current file position has no meaning outside of the file | |
| system driver and as such the operation is not supported. An error is returned | |
| if FileHandle is a directory. | |
| @param FileHandle The open file handle on which to get the position. | |
| @param Position Byte position from begining of file. | |
| @retval EFI_SUCCESS the operation completed sucessfully. | |
| @retval INVALID_PARAMETER One of the parameters has an invalid value. | |
| @retval EFI_UNSUPPORTED the request is not valid on directories. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleGetPosition ( | |
| IN EFI_FILE_HANDLE FileHandle, | |
| OUT UINT64 *Position | |
| ); | |
| /** | |
| Flushes data on a file. | |
| This function flushes all modified data associated with a file to a device. | |
| @param FileHandle The file handle on which to flush data. | |
| @retval EFI_SUCCESS The data was flushed. | |
| @retval EFI_NO_MEDIA The device has no media. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. | |
| @retval EFI_WRITE_PROTECTED The file or medium is write protected. | |
| @retval EFI_ACCESS_DENIED The file was opened for read only. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleFlush ( | |
| IN EFI_FILE_HANDLE FileHandle | |
| ); | |
| /** | |
| Function to determine if a given handle is a directory handle. | |
| If DirHandle is NULL then ASSERT(). | |
| Open the file information on the DirHandle and verify that the Attribute | |
| includes EFI_FILE_DIRECTORY bit set. | |
| @param DirHandle Handle to open file. | |
| @retval EFI_SUCCESS DirHandle is a directory | |
| @retval EFI_INVALID_PARAMETER DirHandle did not have EFI_FILE_INFO available | |
| @retval EFI_NOT_FOUND DirHandle is not a directory | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleIsDirectory ( | |
| IN EFI_FILE_HANDLE DirHandle | |
| ); | |
| /** | |
| Retrieves the first file from a directory. | |
| This function opens a directory and gets the first file's info in the | |
| directory. Caller can use FileHandleFindNextFile() to get other files. When | |
| complete the caller is responsible for calling FreePool() on *Buffer. | |
| @param DirHandle The file handle of the directory to search | |
| @param Buffer Pointer to pointer to buffer for file's information | |
| @retval EFI_SUCCESS Found the first file. | |
| @retval EFI_NOT_FOUND Cannot find the directory. | |
| @retval EFI_NO_MEDIA The device has no media. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. | |
| @return Others status of FileHandleGetInfo, FileHandleSetPosition, | |
| or FileHandleRead | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleFindFirstFile ( | |
| IN EFI_FILE_HANDLE DirHandle, | |
| OUT EFI_FILE_INFO **Buffer | |
| ); | |
| /** | |
| Retrieves the next file in a directory. | |
| To use this function, caller must call the FileHandleFindFirstFile() to get the | |
| first file, and then use this function get other files. This function can be | |
| called for several times to get each file's information in the directory. If | |
| the call of FileHandleFindNextFile() got the last file in the directory, the next | |
| call of this function has no file to get. *NoFile will be set to TRUE and the | |
| Buffer memory will be automatically freed. | |
| @param DirHandle the file handle of the directory | |
| @param Buffer pointer to buffer for file's information | |
| @param NoFile pointer to boolean when last file is found | |
| @retval EFI_SUCCESS Found the next file, or reached last file | |
| @retval EFI_NO_MEDIA The device has no media. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleFindNextFile( | |
| IN EFI_FILE_HANDLE DirHandle, | |
| OUT EFI_FILE_INFO *Buffer, | |
| OUT BOOLEAN *NoFile | |
| ); | |
| /** | |
| Retrieve the size of a file. | |
| If FileHandle is NULL then ASSERT() | |
| If Size is NULL then ASSERT() | |
| This function extracts the file size info from the FileHandle's EFI_FILE_INFO | |
| data. | |
| @param FileHandle The file handle from which size is retrieved. | |
| @param Size pointer to size. | |
| @retval EFI_SUCCESS operation was completed sucessfully | |
| @retval EFI_DEVICE_ERROR cannot access the file | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleGetSize ( | |
| IN EFI_FILE_HANDLE FileHandle, | |
| OUT UINT64 *Size | |
| ); | |
| /** | |
| Function to get a full filename given a EFI_FILE_HANDLE somewhere lower on the | |
| directory 'stack'. | |
| @param[in] Handle Handle to the Directory or File to create path to. | |
| @param[out] FullFileName Pointer to pointer to generated full file name. It | |
| is the responsibility of the caller to free this memory | |
| with a call to FreePool(). | |
| @retval EFI_SUCCESS the operation was sucessful and the FullFileName is valid. | |
| @retval EFI_INVALID_PARAMETER Handle was NULL. | |
| @retval EFI_INVALID_PARAMETER FullFileName was NULL. | |
| @retval EFI_OUT_OF_MEMORY a memory allocation failed. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleGetFileName ( | |
| IN CONST EFI_FILE_HANDLE Handle, | |
| OUT CHAR16 **FullFileName | |
| ); | |
| /** | |
| Function to read a single line (up to but not including the \n) from a file. | |
| If the position upon start is 0, then the Ascii Boolean will be set. This should be | |
| maintained and not changed for all operations with the same file. | |
| @param[in] Handle FileHandle to read from | |
| @param[in,out] Buffer pointer to buffer to read into | |
| @param[in,out] Size pointer to number of bytes in buffer | |
| @param[in] Truncate if TRUE then allows for truncation of the line to fit. | |
| if FALSE will reset the position to the begining of the | |
| line if the buffer is not large enough. | |
| @param[in,out] Ascii Boolean value for indicating whether the file is | |
| Ascii (TRUE) or UCS2 (FALSE); | |
| @retval EFI_SUCCESS the operation was sucessful. the line is stored in | |
| Buffer. | |
| @retval EFI_INVALID_PARAMETER Handle was NULL. | |
| @retval EFI_INVALID_PARAMETER Size was NULL. | |
| @retval EFI_BUFFER_TOO_SMALL Size was not enough space to store the line. | |
| Size was updated to minimum space required. | |
| @sa FileHandleRead | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleReadLine( | |
| IN EFI_FILE_HANDLE Handle, | |
| IN OUT CHAR16 *Buffer, | |
| IN OUT UINTN *Size, | |
| IN BOOLEAN Truncate, | |
| IN OUT BOOLEAN *Ascii | |
| ); | |
| /** | |
| Function to read a single line from a file. The \n is not included in the returned | |
| buffer. The returned buffer must be callee freed. | |
| If the position upon start is 0, then the Ascii Boolean will be set. This should be | |
| maintained and not changed for all operations with the same file. | |
| @param[in] Handle FileHandle to read from. | |
| @param[in,out] Ascii Boolean value for indicating whether the file is Ascii (TRUE) or UCS2 (FALSE); | |
| @return The line of text from the file. | |
| @sa FileHandleReadLine | |
| **/ | |
| CHAR16* | |
| EFIAPI | |
| FileHandleReturnLine( | |
| IN EFI_FILE_HANDLE Handle, | |
| IN OUT BOOLEAN *Ascii | |
| ); | |
| /** | |
| Function to write a line of unicode text to a file. | |
| If Handle is NULL, ASSERT. | |
| @param[in] Handle FileHandle to write to | |
| @param[in] Buffer Buffer to write, if NULL the function will | |
| take no action and return EFI_SUCCESS. | |
| @retval EFI_SUCCESS the data was written. | |
| @retval other failure. | |
| @sa FileHandleWrite | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandleWriteLine( | |
| IN EFI_FILE_HANDLE Handle, | |
| IN CHAR16 *Buffer | |
| ); | |
| /** | |
| function to take a formatted argument and print it to a file. | |
| @param[in] Handle the file handle for the file to write to | |
| @param[in] Format the format argument (see printlib for format specifier) | |
| @param[in] ... the variable arguments for the format | |
| @retval EFI_SUCCESS the operation was sucessful | |
| @return other a return value from FileHandleWriteLine | |
| @sa FileHandleWriteLine | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FileHandlePrintLine( | |
| IN EFI_FILE_HANDLE Handle, | |
| IN CONST CHAR16 *Format, | |
| ... | |
| ); | |
| /** | |
| Function to determine if a FILE_HANDLE is at the end of the file. | |
| This will NOT work on directories. | |
| If Handle is NULL, then ASSERT. | |
| @param[in] Handle the file handle | |
| @retval TRUE the position is at the end of the file | |
| @retval FALSE the position is not at the end of the file | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| FileHandleEof( | |
| IN EFI_FILE_HANDLE Handle | |
| ); | |
| #endif //_FILE_HANDLE_LIBRARY_HEADER_ | |