diff options
author | darylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-11-12 00:35:11 +0000 |
---|---|---|
committer | darylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-11-12 00:35:11 +0000 |
commit | b0934ac4b0cfae7f537fcc7f2b1c9124e59fda52 (patch) | |
tree | 382212d856e9546d7a41256a5c129de7832c7ab0 /ShellPkg/Library/UefiFileHandleLib | |
parent | 031acf6336e92392966825b05600e4da1c24c655 (diff) | |
download | edk2-platforms-b0934ac4b0cfae7f537fcc7f2b1c9124e59fda52.tar.xz |
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
Diffstat (limited to 'ShellPkg/Library/UefiFileHandleLib')
-rw-r--r-- | ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c | 82 |
1 files changed, 43 insertions, 39 deletions
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;
|