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