From b0934ac4b0cfae7f537fcc7f2b1c9124e59fda52 Mon Sep 17 00:00:00 2001 From: darylm503 Date: Sat, 12 Nov 2011 00:35:11 +0000 Subject: ShellPkg: Update comments for functions to clarify buffer origin. Signed-off-by: darylm503 Reviewed-by: jljusten git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12687 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Library/UefiFileHandleLib/UefiFileHandleLib.c | 82 ++++++++++++---------- 1 file changed, 43 insertions(+), 39 deletions(-) (limited to 'ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c') diff --git a/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c b/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c index 116c78f38b..0e2f93debc 100644 --- a/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c +++ b/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c @@ -101,20 +101,20 @@ FileHandleGetInfo ( @param[in] FileInfo The information to set. - @retval EFI_SUCCESS The information was 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_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 EFI_FILE_HANDLE FileHandle, IN CONST EFI_FILE_INFO *FileInfo ) { @@ -198,14 +198,14 @@ FileHandleRead( 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. + @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 @@ -266,12 +266,12 @@ FileHandleClose ( @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. + @retval INVALID_PARAMETER One of the parameters has an invalid value. **/ EFI_STATUS EFIAPI FileHandleDelete ( - IN EFI_FILE_HANDLE FileHandle + IN EFI_FILE_HANDLE FileHandle ) { EFI_STATUS Status; @@ -308,8 +308,8 @@ FileHandleDelete ( EFI_STATUS EFIAPI FileHandleSetPosition ( - IN EFI_FILE_HANDLE FileHandle, - IN UINT64 Position + IN EFI_FILE_HANDLE FileHandle, + IN UINT64 Position ) { // @@ -441,15 +441,19 @@ FileHandleIsDirectory ( return (EFI_SUCCESS); } -/** - Retrieves the first file from a directory +/** Retrieve first entry from a directory. + + This function takes an open directory handle and gets information from the + first entry in the directory. A buffer is allocated to contain + the information and a pointer to the buffer is returned in *Buffer. The + caller can use FileHandleFindNextFile() to get subsequent directory entries. - 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. + The buffer will be freed by FileHandleFindNextFile() when the last directory + entry is read. Otherwise, the caller must free the buffer, using FreePool, + when finished with it. - @param DirHandle The file handle of the directory to search - @param Buffer Pointer to buffer for file's information + @param[in] DirHandle The file handle of the directory to search. + @param[out] Buffer The pointer to pointer to buffer for file's information. @retval EFI_SUCCESS Found the first file. @retval EFI_NOT_FOUND Cannot find the directory. @@ -512,19 +516,19 @@ FileHandleFindFirstFile ( } return (EFI_SUCCESS); } -/** - 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. +/** Retrieve next entries from a directory. + + To use this function, the caller must first call the FileHandleFindFirstFile() + function to get the first directory entry. Subsequent directory entries are + retrieved by using the FileHandleFindNextFile() function. This function can + be called several times to get each entry from the directory. If the call of + FileHandleFindNextFile() retrieved the last directory entry, the next call of + this function will set *NoFile to TRUE and free the buffer. - @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 + @param[in] DirHandle The file handle of the directory. + @param[out] Buffer The pointer to buffer for file's information. + @param[out] NoFile The 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. @@ -534,9 +538,9 @@ FileHandleFindFirstFile ( EFI_STATUS EFIAPI FileHandleFindNextFile( - IN EFI_FILE_HANDLE DirHandle, - OUT EFI_FILE_INFO *Buffer, - OUT BOOLEAN *NoFile + IN EFI_FILE_HANDLE DirHandle, + OUT EFI_FILE_INFO *Buffer, + OUT BOOLEAN *NoFile ) { EFI_STATUS Status; -- cgit v1.2.3