updating comments mostly. also added some new lib functions.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@9710 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 57 insertions, 17 deletions

diff --git a/ShellPkg/Include/Library/FileHandleLib.h b/ShellPkg/Include/Library/FileHandleLib.h
index d86089f046..b265d85bb9 100644
--- a/ShellPkg/Include/Library/FileHandleLib.h
+++ b/ShellPkg/Include/Library/FileHandleLib.h
@@ -1,17 +1,26 @@
 /** @file

   Provides interface to EFI_FILE_HANDLE functionality.

 

-Copyright (c) 2009, Intel Corporation<BR>

-All rights reserved. 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

+  Copyright (c) 2009, Intel Corporation<BR>

+  All rights reserved. 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.

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

 **/

 

+#if !defined (_FILE_HANDLE_LIBRARY_HEADER_)

+#define _FILE_HANDLE_LIBRARY_HEADER_

+

+/// Tag for use in identifying UNICODE files.

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

+enum {

+  UnicodeFileTag = 0xFEFF

+};

+

 /**

   This function will retrieve the information about the file for the handle 

   specified and store it in allocated pool memory.

@@ -344,19 +353,23 @@ FileHandleGetFileName (
   );

 

 /**

-  Function to read a single line from a file. The \n is not included in the returned buffer.

+  Function to read a single line (up to but not including the \n) from a file.

 

-  @param[in]      Handle        FileHandle to read from.

-  @param[in,out]  Buffer        Pointer to buffer to read into

-  @param[in,out]  Size          Pointer to number of bytes in buffer

-  @param[in]      Truncate      If TRUE then allows for truncation of the line to fit.

-                                If FALSE will reset the position to the begining of the 

+  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        pointer to buffer to read into

+  @param[in,out]  Size          pointer to number of bytes in buffer

+  @param[in]      Truncate      if TRUE then allows for truncation of the line to fit.

+                                if FALSE will reset the position to the begining of the 

                                 line if the buffer is not large enough.

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

+                                Ascii (TRUE) or UCS2 (FALSE);

 

-  @retval EFI_SUCCESS           The operation was sucessful.  the line is stored in 

-                                Buffer.  (Size was NOT updated)

+  @retval EFI_SUCCESS           the operation was sucessful.  the line is stored in 

+                                Buffer.

   @retval EFI_INVALID_PARAMETER Handle was NULL.

-  @retval EFI_INVALID_PARAMETER Buffer was NULL.

   @retval EFI_INVALID_PARAMETER Size was NULL.

   @retval EFI_BUFFER_TOO_SMALL  Size was not enough space to store the line.  

                                 Size was updated to minimum space required.

@@ -368,7 +381,29 @@ FileHandleReadLine(
   IN EFI_FILE_HANDLE            Handle,

   IN OUT CHAR16                 *Buffer,

   IN OUT UINTN                  *Size,

-  IN BOOLEAN                    Truncate

+  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

   );

 

 /**

@@ -417,6 +452,8 @@ FileHandlePrintLine(
 

   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

@@ -427,3 +464,6 @@ EFIAPI
 FileHandleEof(

   IN EFI_FILE_HANDLE Handle

   );

+

+#endif //_FILE_HANDLE_LIBRARY_HEADER_

+