Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 1 | /** @file |
| 2 | Provides interface to EFI_FILE_HANDLE functionality. |
| 3 | |
| 4 | Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> |
| 5 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 6 | |
| 7 | **/ |
| 8 | |
| 9 | #ifndef _FILE_HANDLE_LIBRARY_HEADER_ |
| 10 | #define _FILE_HANDLE_LIBRARY_HEADER_ |
| 11 | |
| 12 | #include <Protocol/SimpleFileSystem.h> |
| 13 | #include <Guid/FileInfo.h> |
| 14 | |
| 15 | /// The tag for use in identifying UNICODE files. |
| 16 | /// If the file is UNICODE, the first 16 bits of the file will equal this value. |
| 17 | extern CONST UINT16 gUnicodeFileTag; |
| 18 | |
| 19 | /** |
| 20 | This function retrieves information about the file for the handle |
| 21 | specified and stores it in the allocated pool memory. |
| 22 | |
| 23 | This function allocates a buffer to store the file's information. It is the |
| 24 | caller's responsibility to free the buffer. |
| 25 | |
| 26 | @param[in] FileHandle The file handle of the file for which information is |
| 27 | being requested. |
| 28 | |
| 29 | @retval NULL Information could not be retrieved. |
| 30 | @retval !NULL The information about the file. |
| 31 | **/ |
| 32 | EFI_FILE_INFO * |
| 33 | EFIAPI |
| 34 | FileHandleGetInfo ( |
| 35 | IN EFI_FILE_HANDLE FileHandle |
| 36 | ); |
| 37 | |
| 38 | /** |
| 39 | This function sets the information about the file for the opened handle |
| 40 | specified. |
| 41 | |
| 42 | @param[in] FileHandle The file handle of the file for which information |
| 43 | is being set. |
| 44 | |
| 45 | @param[in] FileInfo The information to set. |
| 46 | |
| 47 | @retval EFI_SUCCESS The information was set. |
| 48 | @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. |
| 49 | @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. |
| 50 | @retval EFI_NO_MEDIA The device has no medium. |
| 51 | @retval EFI_DEVICE_ERROR The device reported an error. |
| 52 | @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. |
| 53 | @retval EFI_WRITE_PROTECTED The file or medium is write protected. |
| 54 | @retval EFI_ACCESS_DENIED The file was opened read only. |
| 55 | @retval EFI_VOLUME_FULL The volume is full. |
| 56 | **/ |
| 57 | EFI_STATUS |
| 58 | EFIAPI |
| 59 | FileHandleSetInfo ( |
| 60 | IN EFI_FILE_HANDLE FileHandle, |
| 61 | IN CONST EFI_FILE_INFO *FileInfo |
| 62 | ); |
| 63 | |
| 64 | /** |
| 65 | This function reads information from an opened file. |
| 66 | |
| 67 | If FileHandle is not a directory, the function reads the requested number of |
| 68 | bytes from the file at the file's current position and returns them in Buffer. |
| 69 | If the read goes beyond the end of the file, the read length is truncated to the |
| 70 | end of the file. The file's current position is increased by the number of bytes |
| 71 | returned. If FileHandle is a directory, the function reads the directory entry |
| 72 | at the file's current position and returns the entry in Buffer. If the Buffer |
| 73 | is not large enough to hold the current directory entry, then |
| 74 | EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated. |
| 75 | BufferSize is set to be the size of the buffer needed to read the entry. On |
| 76 | success, the current position is updated to the next directory entry. If there |
| 77 | are no more directory entries, the read returns a zero-length buffer. |
| 78 | EFI_FILE_INFO is the structure returned as the directory entry. |
| 79 | |
| 80 | @param[in] FileHandle The opened file handle. |
| 81 | @param[in, out] BufferSize On input, the size of buffer in bytes. On return, |
| 82 | the number of bytes written. |
| 83 | @param[out] Buffer The buffer to put read data into. |
| 84 | |
| 85 | @retval EFI_SUCCESS Data was read. |
| 86 | @retval EFI_NO_MEDIA The device has no media. |
| 87 | @retval EFI_DEVICE_ERROR The device reported an error. |
| 88 | @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. |
| 89 | @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required |
| 90 | size. |
| 91 | |
| 92 | **/ |
| 93 | EFI_STATUS |
| 94 | EFIAPI |
| 95 | FileHandleRead ( |
| 96 | IN EFI_FILE_HANDLE FileHandle, |
| 97 | IN OUT UINTN *BufferSize, |
| 98 | OUT VOID *Buffer |
| 99 | ); |
| 100 | |
| 101 | /** |
| 102 | Write data to a file. |
| 103 | |
| 104 | This function writes the specified number of bytes to the file at the current |
| 105 | file position. The current file position is advanced the actual number of bytes |
| 106 | written, which is returned in BufferSize. Partial writes only occur when there |
| 107 | has been a data error during the write attempt (such as "volume space full"). |
| 108 | The file is automatically grown to hold the data if required. Direct writes to |
| 109 | opened directories are not supported. |
| 110 | |
| 111 | @param[in] FileHandle The opened file for writing. |
| 112 | @param[in, out] BufferSize On input, the number of bytes in Buffer. On output, |
| 113 | the number of bytes written. |
| 114 | @param[in] Buffer The buffer containing data to write is stored. |
| 115 | |
| 116 | @retval EFI_SUCCESS Data was written. |
| 117 | @retval EFI_UNSUPPORTED Writes to an open directory are not supported. |
| 118 | @retval EFI_NO_MEDIA The device has no media. |
| 119 | @retval EFI_DEVICE_ERROR The device reported an error. |
| 120 | @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. |
| 121 | @retval EFI_WRITE_PROTECTED The device is write-protected. |
| 122 | @retval EFI_ACCESS_DENIED The file was opened for read only. |
| 123 | @retval EFI_VOLUME_FULL The volume is full. |
| 124 | **/ |
| 125 | EFI_STATUS |
| 126 | EFIAPI |
| 127 | FileHandleWrite ( |
| 128 | IN EFI_FILE_HANDLE FileHandle, |
| 129 | IN OUT UINTN *BufferSize, |
| 130 | IN VOID *Buffer |
| 131 | ); |
| 132 | |
| 133 | /** |
| 134 | Close an open file handle. |
| 135 | |
| 136 | This function closes a specified file handle. All "dirty" cached file data is |
| 137 | flushed to the device, and the file is closed. In all cases the handle is |
| 138 | closed. |
| 139 | |
| 140 | @param[in] FileHandle The file handle to close. |
| 141 | |
| 142 | @retval EFI_SUCCESS The file handle was closed successfully. |
| 143 | **/ |
| 144 | EFI_STATUS |
| 145 | EFIAPI |
| 146 | FileHandleClose ( |
| 147 | IN EFI_FILE_HANDLE FileHandle |
| 148 | ); |
| 149 | |
| 150 | /** |
| 151 | Delete a file and close the handle. |
| 152 | |
| 153 | This function closes and deletes a file. In all cases the file handle is closed. |
| 154 | If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is |
| 155 | returned, but the handle is still closed. |
| 156 | |
| 157 | @param[in] FileHandle The file handle to delete. |
| 158 | |
| 159 | @retval EFI_SUCCESS The file was closed successfully. |
| 160 | @retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not |
| 161 | deleted. |
| 162 | @retval INVALID_PARAMETER One of the parameters has an invalid value. |
| 163 | **/ |
| 164 | EFI_STATUS |
| 165 | EFIAPI |
| 166 | FileHandleDelete ( |
| 167 | IN EFI_FILE_HANDLE FileHandle |
| 168 | ); |
| 169 | |
| 170 | /** |
| 171 | Set the current position in a file. |
| 172 | |
| 173 | This function sets the current file position for the handle to the position |
| 174 | supplied. With the exception of moving to position 0xFFFFFFFFFFFFFFFF, only |
| 175 | absolute positioning is supported, and moving past the end of the file is |
| 176 | allowed (a subsequent write would grow the file). Moving to position |
| 177 | 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file. |
| 178 | If FileHandle is a directory, the only position that may be set is zero. This |
| 179 | has the effect of starting the read process of the directory entries over again. |
| 180 | |
| 181 | @param[in] FileHandle The file handle on which the position is being set. |
| 182 | @param[in] Position The byte position from the beginning of the file. |
| 183 | |
| 184 | @retval EFI_SUCCESS The operation completed successfully. |
| 185 | @retval EFI_UNSUPPORTED The request for non-zero is not valid on |
| 186 | directories. |
| 187 | @retval INVALID_PARAMETER One of the parameters has an invalid value. |
| 188 | **/ |
| 189 | EFI_STATUS |
| 190 | EFIAPI |
| 191 | FileHandleSetPosition ( |
| 192 | IN EFI_FILE_HANDLE FileHandle, |
| 193 | IN UINT64 Position |
| 194 | ); |
| 195 | |
| 196 | /** |
| 197 | Gets a file's current position. |
| 198 | |
| 199 | This function retrieves the current file position for the file handle. For |
| 200 | directories, the current file position has no meaning outside of the file |
| 201 | system driver. As such, the operation is not supported. An error is returned |
| 202 | if FileHandle is a directory. |
| 203 | |
| 204 | @param[in] FileHandle The open file handle on which to get the position. |
| 205 | @param[out] Position The byte position from beginning of file. |
| 206 | |
| 207 | @retval EFI_SUCCESS The operation completed successfully. |
| 208 | @retval INVALID_PARAMETER One of the parameters has an invalid value. |
| 209 | @retval EFI_UNSUPPORTED The request is not valid on directories. |
| 210 | **/ |
| 211 | EFI_STATUS |
| 212 | EFIAPI |
| 213 | FileHandleGetPosition ( |
| 214 | IN EFI_FILE_HANDLE FileHandle, |
| 215 | OUT UINT64 *Position |
| 216 | ); |
| 217 | |
| 218 | /** |
| 219 | Flushes data on a file. |
| 220 | |
| 221 | This function flushes all modified data associated with a file to a device. |
| 222 | |
| 223 | @param[in] FileHandle The file handle on which to flush data. |
| 224 | |
| 225 | @retval EFI_SUCCESS The data was flushed. |
| 226 | @retval EFI_NO_MEDIA The device has no media. |
| 227 | @retval EFI_DEVICE_ERROR The device reported an error. |
| 228 | @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. |
| 229 | @retval EFI_WRITE_PROTECTED The file or medium is write protected. |
| 230 | @retval EFI_ACCESS_DENIED The file was opened for read only. |
| 231 | **/ |
| 232 | EFI_STATUS |
| 233 | EFIAPI |
| 234 | FileHandleFlush ( |
| 235 | IN EFI_FILE_HANDLE FileHandle |
| 236 | ); |
| 237 | |
| 238 | /** |
| 239 | Function to determine if a given handle is a directory handle. |
| 240 | |
| 241 | Open the file information on the DirHandle and verify that the Attribute |
| 242 | includes EFI_FILE_DIRECTORY bit set. |
| 243 | |
| 244 | @param[in] DirHandle Handle to open file. |
| 245 | |
| 246 | @retval EFI_SUCCESS DirHandle is a directory. |
| 247 | @retval EFI_INVALID_PARAMETER DirHandle is NULL. |
| 248 | The file information returns from FileHandleGetInfo is NULL. |
| 249 | @retval EFI_NOT_FOUND DirHandle is not a directory. |
| 250 | **/ |
| 251 | EFI_STATUS |
| 252 | EFIAPI |
| 253 | FileHandleIsDirectory ( |
| 254 | IN EFI_FILE_HANDLE DirHandle |
| 255 | ); |
| 256 | |
| 257 | /** Retrieve first entry from a directory. |
| 258 | |
| 259 | This function takes an open directory handle and gets information from the |
| 260 | first entry in the directory. A buffer is allocated to contain |
| 261 | the information and a pointer to the buffer is returned in *Buffer. The |
| 262 | caller can use FileHandleFindNextFile() to get subsequent directory entries. |
| 263 | |
| 264 | The buffer will be freed by FileHandleFindNextFile() when the last directory |
| 265 | entry is read. Otherwise, the caller must free the buffer, using FreePool, |
| 266 | when finished with it. |
| 267 | |
| 268 | @param[in] DirHandle The file handle of the directory to search. |
| 269 | @param[out] Buffer The pointer to pointer to buffer for file's information. |
| 270 | |
| 271 | @retval EFI_SUCCESS Found the first file. |
| 272 | @retval EFI_NOT_FOUND Cannot find the directory. |
| 273 | @retval EFI_NO_MEDIA The device has no media. |
| 274 | @retval EFI_DEVICE_ERROR The device reported an error. |
| 275 | @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. |
| 276 | @return Others The status of FileHandleGetInfo, FileHandleSetPosition, |
| 277 | or FileHandleRead. |
| 278 | **/ |
| 279 | EFI_STATUS |
| 280 | EFIAPI |
| 281 | FileHandleFindFirstFile ( |
| 282 | IN EFI_FILE_HANDLE DirHandle, |
| 283 | OUT EFI_FILE_INFO **Buffer |
| 284 | ); |
| 285 | |
| 286 | /** Retrieve next entries from a directory. |
| 287 | |
| 288 | To use this function, the caller must first call the FileHandleFindFirstFile() |
| 289 | function to get the first directory entry. Subsequent directory entries are |
| 290 | retrieved by using the FileHandleFindNextFile() function. This function can |
| 291 | be called several times to get each entry from the directory. If the call of |
| 292 | FileHandleFindNextFile() retrieved the last directory entry, the next call of |
| 293 | this function will set *NoFile to TRUE and free the buffer. |
| 294 | |
| 295 | @param[in] DirHandle The file handle of the directory. |
| 296 | @param[out] Buffer The pointer to buffer for file's information. |
| 297 | @param[out] NoFile The pointer to boolean when last file is found. |
| 298 | |
| 299 | @retval EFI_SUCCESS Found the next file, or reached last file. |
| 300 | @retval EFI_NO_MEDIA The device has no media. |
| 301 | @retval EFI_DEVICE_ERROR The device reported an error. |
| 302 | @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. |
| 303 | **/ |
| 304 | EFI_STATUS |
| 305 | EFIAPI |
| 306 | FileHandleFindNextFile ( |
| 307 | IN EFI_FILE_HANDLE DirHandle, |
| 308 | OUT EFI_FILE_INFO *Buffer, |
| 309 | OUT BOOLEAN *NoFile |
| 310 | ); |
| 311 | |
| 312 | /** |
| 313 | Retrieve the size of a file. |
| 314 | |
| 315 | This function extracts the file size info from the FileHandle's EFI_FILE_INFO |
| 316 | data. |
| 317 | |
| 318 | @param[in] FileHandle The file handle from which size is retrieved. |
| 319 | @param[out] Size The pointer to size. |
| 320 | |
| 321 | @retval EFI_SUCCESS Operation was completed successfully. |
| 322 | @retval EFI_DEVICE_ERROR Cannot access the file. |
| 323 | @retval EFI_INVALID_PARAMETER FileHandle is NULL. |
| 324 | Size is NULL. |
| 325 | **/ |
| 326 | EFI_STATUS |
| 327 | EFIAPI |
| 328 | FileHandleGetSize ( |
| 329 | IN EFI_FILE_HANDLE FileHandle, |
| 330 | OUT UINT64 *Size |
| 331 | ); |
| 332 | |
| 333 | /** |
| 334 | Set the size of a file. |
| 335 | |
| 336 | This function changes the file size info from the FileHandle's EFI_FILE_INFO |
| 337 | data. |
| 338 | |
| 339 | @param[in] FileHandle The file handle whose size is to be changed. |
| 340 | @param[in] Size The new size. |
| 341 | |
| 342 | @retval EFI_SUCCESS The operation completed successfully. |
| 343 | @retval EFI_DEVICE_ERROR Cannot access the file. |
| 344 | @retval EFI_INVALID_PARAMETER FileHandle is NULL. |
| 345 | **/ |
| 346 | EFI_STATUS |
| 347 | EFIAPI |
| 348 | FileHandleSetSize ( |
| 349 | IN EFI_FILE_HANDLE FileHandle, |
| 350 | IN UINT64 Size |
| 351 | ); |
| 352 | |
| 353 | /** |
| 354 | Function to get a full filename given a EFI_FILE_HANDLE somewhere lower on the |
| 355 | directory 'stack'. If the file is a directory, then append the '\' char at the |
| 356 | end of name string. If it's not a directory, then the last '\' should not be |
| 357 | added. |
| 358 | |
| 359 | @param[in] Handle Handle to the Directory or File to create path to. |
| 360 | @param[out] FullFileName Pointer to pointer to generated full file name. It |
| 361 | is the responsibility of the caller to free this memory |
| 362 | with a call to FreePool(). |
| 363 | @retval EFI_SUCCESS The operation was successful and FullFileName is valid. |
| 364 | @retval EFI_INVALID_PARAMETER Handle was NULL. |
| 365 | @retval EFI_INVALID_PARAMETER FullFileName was NULL. |
| 366 | @retval EFI_OUT_OF_MEMORY A memory allocation failed. |
| 367 | **/ |
| 368 | EFI_STATUS |
| 369 | EFIAPI |
| 370 | FileHandleGetFileName ( |
| 371 | IN CONST EFI_FILE_HANDLE Handle, |
| 372 | OUT CHAR16 **FullFileName |
| 373 | ); |
| 374 | |
| 375 | /** |
| 376 | Function to read a single line (up to but not including the \n) from a file. |
| 377 | |
| 378 | If the position upon start is 0, then the Ascii Boolean will be set. This should be |
| 379 | maintained and not changed for all operations with the same file. |
| 380 | The function will not return the \r and \n character in buffer. When an empty line is |
| 381 | read a CHAR_NULL character will be returned in buffer. |
| 382 | |
| 383 | @param[in] Handle FileHandle to read from. |
| 384 | @param[in, out] Buffer The pointer to buffer to read into. |
| 385 | @param[in, out] Size The pointer to number of bytes in Buffer. |
| 386 | @param[in] Truncate If the buffer is large enough, this has no effect. |
| 387 | If the buffer is is too small and Truncate is TRUE, |
| 388 | the line will be truncated. |
| 389 | If the buffer is is too small and Truncate is FALSE, |
| 390 | then no read will occur. |
| 391 | |
| 392 | @param[in, out] Ascii Boolean value for indicating whether the file is |
| 393 | Ascii (TRUE) or UCS2 (FALSE). |
| 394 | |
| 395 | @retval EFI_SUCCESS The operation was successful. The line is stored in |
| 396 | Buffer. |
| 397 | @retval EFI_INVALID_PARAMETER Handle was NULL. |
| 398 | @retval EFI_INVALID_PARAMETER Size was NULL. |
| 399 | @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line. |
| 400 | Size was updated to the minimum space required. |
| 401 | @sa FileHandleRead |
| 402 | **/ |
| 403 | EFI_STATUS |
| 404 | EFIAPI |
| 405 | FileHandleReadLine ( |
| 406 | IN EFI_FILE_HANDLE Handle, |
| 407 | IN OUT CHAR16 *Buffer, |
| 408 | IN OUT UINTN *Size, |
| 409 | IN BOOLEAN Truncate, |
| 410 | IN OUT BOOLEAN *Ascii |
| 411 | ); |
| 412 | |
| 413 | /** |
| 414 | Function to read a single line from a file. The \n is not included in the returned |
| 415 | buffer. The returned buffer must be callee freed. |
| 416 | |
| 417 | If the position upon start is 0, then the Ascii Boolean will be set. This should be |
| 418 | maintained and not changed for all operations with the same file. |
| 419 | |
| 420 | @param[in] Handle FileHandle to read from. |
| 421 | @param[in, out] Ascii Boolean value for indicating whether the file is |
| 422 | Ascii (TRUE) or UCS2 (FALSE). |
| 423 | |
| 424 | @return The line of text from the file. |
| 425 | |
| 426 | @sa FileHandleReadLine |
| 427 | **/ |
| 428 | CHAR16 * |
| 429 | EFIAPI |
| 430 | FileHandleReturnLine ( |
| 431 | IN EFI_FILE_HANDLE Handle, |
| 432 | IN OUT BOOLEAN *Ascii |
| 433 | ); |
| 434 | |
| 435 | /** |
| 436 | Function to write a line of text to a file. |
| 437 | |
| 438 | If the file is a Unicode file (with UNICODE file tag) then write the unicode |
| 439 | text. |
| 440 | If the file is an ASCII file then write the ASCII text. |
| 441 | If the size of file is zero (without file tag at the beginning) then write |
| 442 | ASCII text as default. |
| 443 | |
| 444 | @param[in] Handle FileHandle to write to. |
| 445 | @param[in] Buffer Buffer to write, if NULL the function will |
| 446 | take no action and return EFI_SUCCESS. |
| 447 | |
| 448 | @retval EFI_SUCCESS The data was written. |
| 449 | Buffer is NULL. |
| 450 | @retval EFI_INVALID_PARAMETER Handle is NULL. |
| 451 | @retval EFI_OUT_OF_RESOURCES Unable to allocate temporary space for ASCII |
| 452 | string due to out of resources. |
| 453 | |
| 454 | @sa FileHandleWrite |
| 455 | **/ |
| 456 | EFI_STATUS |
| 457 | EFIAPI |
| 458 | FileHandleWriteLine ( |
| 459 | IN EFI_FILE_HANDLE Handle, |
| 460 | IN CHAR16 *Buffer |
| 461 | ); |
| 462 | |
| 463 | /** |
| 464 | Function to take a formatted argument and print it to a file. |
| 465 | |
| 466 | @param[in] Handle The file handle for the file to write to. |
| 467 | @param[in] Format The format argument (see printlib for the format specifier). |
| 468 | @param[in] ... The variable arguments for the format. |
| 469 | |
| 470 | @retval EFI_SUCCESS The operation was successful. |
| 471 | @retval other A return value from FileHandleWriteLine. |
| 472 | |
| 473 | @sa FileHandleWriteLine |
| 474 | **/ |
| 475 | EFI_STATUS |
| 476 | EFIAPI |
| 477 | FileHandlePrintLine ( |
| 478 | IN EFI_FILE_HANDLE Handle, |
| 479 | IN CONST CHAR16 *Format, |
| 480 | ... |
| 481 | ); |
| 482 | |
| 483 | /** |
| 484 | Function to determine if a FILE_HANDLE is at the end of the file. |
| 485 | |
| 486 | This will NOT work on directories. |
| 487 | |
| 488 | If Handle is NULL, then ASSERT(). |
| 489 | |
| 490 | @param[in] Handle The file handle. |
| 491 | |
| 492 | @retval TRUE The position is at the end of the file. |
| 493 | @retval FALSE The position is not at the end of the file. |
| 494 | **/ |
| 495 | BOOLEAN |
| 496 | EFIAPI |
| 497 | FileHandleEof ( |
| 498 | IN EFI_FILE_HANDLE Handle |
| 499 | ); |
| 500 | |
| 501 | #endif //_FILE_HANDLE_LIBRARY_HEADER_ |