MdeModulePkg, MdePkg, NetworkPkg, OvmfPkg, PerformancePkg, ShellPkg: Library Migration.

Move libraries from ShellPkg into MdeModulePkg and MdePkg.

The following libraries are being migrated out of ShellPkg in order to make
their functionality more widely available.
  • PathLib:        Incorporate into MdePkg/Library/BaseLib
  • FileHandleLib:  MdePkg/Library/UefiFileHandleLib
  • BaseSortLib:    MdeModulePkg/Library/BaseSortLib
  • UefiSortLib:    MdeModulePkg/Library/UefiSortLib

Diffs showing file changes are in the attached file, LibMigration.patch.
A description of the changes follows:

  • Move ShellPkg/Include/Library/FileHandleLib.h to MdePkg/Include/Library/FileHandleLib.h
  • Move ShellPkg/Include/Library/SortLib.h to MdeModulePkg/Include/Library/SortLib.h
  • Move ShellPkg/Library/BaseSortLib to MdeModulePkg/Library/BaseSortLib
  • Move ShellPkg/Library/UefiSortLib to MdeModulePkg/Library/UefiSortLib
  • Move ShellPkg/Library/BasePathLib/BasePathLib.c to MdePkg/Library/BaseLib/FilePaths.c
  • Merge ShellPkg/Include/Library/PathLib.h into MdePkg/Include/Library/BaseLib.h
  • Delete  ShellPkg/Library/BasePathLib; Includes BasePathLib.c and BasePathLib.inf

  • NetworkPkg/NetworkPkg.dsc
  • PerformancePkg.dsc
  • OvmfPkg/OvmfPkgX64.dsc
  • OvmfPkg/OvmfPkgIa32X64.dsc
  • OvmfPkg/OvmfPkgIa32.dsc
    o Update SortLib and FileHandleLib library classes to point to the new library locations.
    o Remove PathLib library class and make sure that BaseLib is described.

  • MdeModulePkg/MdeModulePkg.dec
    o Add SortLib library class

  • MdePkg/MdePkg.dec
    o Add FileHandleLib library class
    o Add PcdUefiFileHandleLibPrintBufferSize PCD

  • MdePkg/Library/BaseLib/BaseLib.inf
    o Add FilePaths.c to [Sources]

  • MdePkg/Include/Library/BaseLib.h
    o Update file description to include "file path functions"

  • ShellPkg/ShellPkg.dsc
    o Change PACKAGE_GUID to { C1014BB7-4092-43D4-984F-0738EB424DBF }
    o Update PACKAGE_VERSION to 1.0
    o Update SortLib and FileHandleLib library classes to point to the new library locations.
    o Remove PathLib library class and make sure that BaseLib is described.
    o Remove ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.inf from [Components]

  • ShellPkg/ShellPkg.dec
    o Update PLATFORM_VERSION to 1.0
    o Remove declarations of the FileHandleLib, SortLib, and PathLib Library Classes
    o Update comment for the PcdShellPrintBufferSize PCD.

  • ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.inf
  • ShellPkg/Application/Shell/Shell.inf
    o Remove PathLib from [LibraryClasses]

  • ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.h
  • ShellPkg/Application/Shell/Shell.h
    o Remove #include <Library/PathLib.h>

  • ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
    o Add PathLib to [LibraryClasses]

  • ShellPkg/Library/UefiShellLevel1CommandsLib/If.c
    o Remove #include <Library/PathLib.h>

  • ShellPkg/Application/ShellSortTestApp/ShellSortTestApp.inf
    o Add MdeModulePkg/MdeModulePkg.dec to [Packages]

  • MdeModulePkg/Library/BaseSortLib/BaseSortLib.inf
  • MdeModulePkg/Library/UefiSortLib/UefiSortLib.inf
    o Replace ShellPkg.dec with MdeModulePkg.dec in [Packages]

  • MdeModulePkg/Library/UefiSortLib/UefiSortLib.c
    o Remove #include <ShellBase.h>
    o Define USL_FREE_NON_NULL() to replace SHELL_FREE_NON_NULL()

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Daryl McDaniel <daryl.mcdaniel@intel.com>
Reviewed-by: Jaben Carsey <jaben.carsey@intel.com>
Reviewed-by: Erik Bjorge <erik.c.bjorge@intel.com>


git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@16601 6f19259b-4bc3-4df7-8a09-765794883524

2 files changed, 545 insertions, 10 deletions

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index bd3f9cfc60..750f82e8f7 100644
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -1,8 +1,8 @@
 /** @file

   Provides string functions, linked list functions, math functions, synchronization

-  functions, and CPU architecture-specific functions.

+  functions, file path functions, and CPU architecture-specific functions.

 

-Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR>

+Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>

 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>

 This program and the accompanying materials

 are licensed and made available under the terms and conditions of the BSD License

@@ -484,7 +484,7 @@ AsciiStrnCatS (
 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Copies one Null-terminated Unicode string to another Null-terminated Unicode

   string and returns the new Unicode string.

@@ -517,7 +517,7 @@ StrCpy (
 

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Copies up to a specified length from one Null-terminated Unicode string to 

   another Null-terminated Unicode string and returns the new Unicode string.

@@ -686,7 +686,7 @@ StrnCmp (
 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Concatenates one Null-terminated Unicode string to another Null-terminated

   Unicode string, and returns the concatenated Unicode string.

@@ -728,7 +728,7 @@ StrCat (
 

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Concatenates up to a specified length one Null-terminated Unicode to the end 

   of another Null-terminated Unicode string, and returns the concatenated 

@@ -1016,7 +1016,7 @@ UnicodeStrToAsciiStr (
 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Copies one Null-terminated ASCII string to another Null-terminated ASCII

   string and returns the new ASCII string.

@@ -1047,7 +1047,7 @@ AsciiStrCpy (
 

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Copies up to a specified length one Null-terminated ASCII string to another 

   Null-terminated ASCII string and returns the new ASCII string.

@@ -1245,7 +1245,7 @@ AsciiStrnCmp (
 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Concatenates one Null-terminated ASCII string to another Null-terminated

   ASCII string, and returns the concatenated ASCII string.

@@ -1282,7 +1282,7 @@ AsciiStrCat (
 

 

 /**

-  [ATTENTION] This function will be deprecated for security reason.

+  [ATTENTION] This function is deprecated for security reason.

 

   Concatenates up to a specified length one Null-terminated ASCII string to 

   the end of another Null-terminated ASCII string, and returns the 

@@ -1591,6 +1591,43 @@ BcdToDecimal8 (
   IN      UINT8                     Value

   );

 

+//

+//  File Path Manipulation Functions

+//

+

+/**

+  Removes the last directory or file entry in a path by changing the last

+  L'\' to a CHAR_NULL.

+

+  @param[in, out] Path    The pointer to the path to modify.

+

+  @retval FALSE     Nothing was found to remove.

+  @retval TRUE      A directory or file was removed.

+**/

+BOOLEAN

+EFIAPI

+PathRemoveLastItem(

+  IN OUT CHAR16 *Path

+  );

+

+/**

+  Function to clean up paths.

+    - Single periods in the path are removed.

+    - Double periods in the path are removed along with a single parent directory.

+    - Forward slashes L'/' are converted to backward slashes L'\'.

+

+  This will be done inline and the existing buffer may be larger than required

+  upon completion.

+

+  @param[in] Path       The pointer to the string containing the path.

+

+  @return       Returns Path, otherwise returns NULL to indicate that an error has occured.

+**/

+CHAR16*

+EFIAPI

+PathCleanUpDirectories(

+  IN CHAR16 *Path

+);

 

 //

 // Linked List Functions and Macros

diff --git a/MdePkg/Include/Library/FileHandleLib.h b/MdePkg/Include/Library/FileHandleLib.h
new file mode 100644
index 0000000000..123cc8c58f
--- /dev/null
+++ b/MdePkg/Include/Library/FileHandleLib.h
@@ -0,0 +1,498 @@
+/** @file

+  Provides interface to EFI_FILE_HANDLE functionality.

+

+  Copyright (c) 2009 - 2014, 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.

+

+**/

+

+#ifndef _FILE_HANDLE_LIBRARY_HEADER_

+#define _FILE_HANDLE_LIBRARY_HEADER_

+

+#include <Protocol/SimpleFileSystem.h>

+

+/// The tag for use in identifying UNICODE files.

+/// If the file is UNICODE, the first 16 bits of the file will equal this value.

+extern CONST UINT16 gUnicodeFileTag;

+

+/**

+  This function retrieves information about the file for the handle

+  specified and stores it in the 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[in] 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 sets the information about the file for the opened handle

+  specified.

+

+  @param[in]  FileHandle        The file handle of the file for which information

+                                is being set.

+

+  @param[in]  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[in] FileHandle          The opened file handle.

+  @param[in, out] BufferSize     On input, the size of buffer in bytes.  On return,

+                                 the number of bytes written.

+  @param[out] 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[in] FileHandle          The opened file for writing.

+  @param[in, out] BufferSize     On input, the number of bytes in Buffer.  On output,

+                                 the number of bytes written.

+  @param[in] 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 opened 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[in] FileHandle           The file handle to close.

+

+  @retval EFI_SUCCESS             The file handle was closed successfully.

+**/

+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[in] FileHandle             The file handle to delete.

+

+  @retval EFI_SUCCESS               The file was closed successfully.

+  @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 moving to position 0xFFFFFFFFFFFFFFFF, only

+  absolute positioning is supported, and moving past the end of the file is

+  allowed (a subsequent write would grow the file). Moving 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 again.

+

+  @param[in] FileHandle         The file handle on which the position is being set.

+  @param[in] Position           The byte position from the begining of the file.

+

+  @retval EFI_SUCCESS           The operation completed sucessfully.

+  @retval EFI_UNSUPPORTED       The 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. As such, the operation is not supported. An error is returned

+  if FileHandle is a directory.

+

+  @param[in] FileHandle         The open file handle on which to get the position.

+  @param[out] Position          The byte position from begining of file.

+

+  @retval EFI_SUCCESS           The operation completed successfully.

+  @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[in] 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[in] DirHandle          The handle to open the 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

+  );

+

+/** 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.

+

+  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[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.

+  @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                The status of FileHandleGetInfo, FileHandleSetPosition,

+                                or FileHandleRead.

+**/

+EFI_STATUS

+EFIAPI

+FileHandleFindFirstFile (

+  IN EFI_FILE_HANDLE            DirHandle,

+  OUT EFI_FILE_INFO             **Buffer

+  );

+

+/** 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[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.

+  @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[in] FileHandle         The file handle from which size is retrieved.

+  @param[out] Size              The pointer to size.

+

+  @retval EFI_SUCCESS           The operation completed successfully.

+  @retval EFI_DEVICE_ERROR      Cannot access the file.

+**/

+EFI_STATUS

+EFIAPI

+FileHandleGetSize (

+  IN EFI_FILE_HANDLE            FileHandle,

+  OUT UINT64                    *Size

+  );

+

+/**

+  Set the size of a file.

+

+  If FileHandle is NULL then ASSERT().

+

+  This function changes the file size info from the FileHandle's EFI_FILE_INFO

+  data.

+

+  @param[in] FileHandle         The file handle whose size is to be changed.

+  @param[in] Size               The new size.

+

+  @retval EFI_SUCCESS           The operation completed successfully.

+  @retval EFI_DEVICE_ERROR      Cannot access the file.

+**/

+EFI_STATUS

+EFIAPI

+FileHandleSetSize (

+  IN EFI_FILE_HANDLE            FileHandle,

+  IN 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 successful and 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        The pointer to buffer to read into.

+  @param[in, out]  Size          The pointer to number of bytes in Buffer.

+  @param[in]       Truncate      If the buffer is large enough, this has no effect.

+                                 If the buffer is is too small and Truncate is TRUE,

+                                 the line will be truncated.

+                                 If the buffer is is too small and Truncate is FALSE,

+                                 then no read will occur.

+

+  @param[in, out]  Ascii         Boolean value for indicating whether the file is

+                                 Ascii (TRUE) or UCS2 (FALSE).

+

+  @retval EFI_SUCCESS           The operation was successful.  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 large enough to store the line.

+                                Size was updated to the 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 the format specifier).

+  @param[in] ...      The variable arguments for the format.

+

+  @retval EFI_SUCCESS The operation was successful.

+  @retval 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_

+