updating comments mostly. also added some new lib functions.

[mirror_edk2.git] / ShellPkg / Include / Library / FileHandleLib.h

diff --git a/ShellPkg/Include/Library/FileHandleLib.h b/ShellPkg/Include/Library/FileHandleLib.h
index d86089f04662fc80dd4cb87c78483ef1209c325f..b265d85bb9bf790b06135753c8e08bb18c34466b 100644 (file)
--- a/ShellPkg/Include/Library/FileHandleLib.h
+++ b/ShellPkg/Include/Library/FileHandleLib.h
@@ -1,17 +1,26 @@
 /** @file\r
   Provides interface to EFI_FILE_HANDLE functionality.\r
 \r
-Copyright (c) 2009, Intel Corporation<BR>\r
-All rights reserved. This program and the accompanying materials\r
-are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution.  The full text of the license may be found at\r
-http://opensource.org/licenses/bsd-license.php\r
+  Copyright (c) 2009, Intel Corporation<BR>\r
+  All rights reserved. This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions of the BSD License\r
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
 \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
 **/\r
 \r
+#if !defined (_FILE_HANDLE_LIBRARY_HEADER_)\r
+#define _FILE_HANDLE_LIBRARY_HEADER_\r
+\r
+/// Tag for use in identifying UNICODE files.\r
+/// If the file is UNICODE the first 16 bits of the file will equal this value.\r
+enum {\r
+  UnicodeFileTag = 0xFEFF\r
+};\r
+\r
 /**\r
   This function will retrieve the information about the file for the handle \r
   specified and store it in allocated pool memory.\r
@@ -344,19 +353,23 @@ FileHandleGetFileName (
   );\r
 \r
 /**\r
-  Function to read a single line from a file. The \n is not included in the returned buffer.\r
+  Function to read a single line (up to but not including the \n) from a file.\r
 \r
-  @param[in]      Handle        FileHandle to read from.\r
-  @param[in,out]  Buffer        Pointer to buffer to read into\r
-  @param[in,out]  Size          Pointer to number of bytes in buffer\r
-  @param[in]      Truncate      If TRUE then allows for truncation of the line to fit.\r
-                                If FALSE will reset the position to the begining of the \r
+  If the position upon start is 0, then the Ascii Boolean will be set.  This should be \r
+  maintained and not changed for all operations with the same file.\r
+\r
+  @param[in]      Handle        FileHandle to read from\r
+  @param[in,out]  Buffer        pointer to buffer to read into\r
+  @param[in,out]  Size          pointer to number of bytes in buffer\r
+  @param[in]      Truncate      if TRUE then allows for truncation of the line to fit.\r
+                                if FALSE will reset the position to the begining of the \r
                                 line if the buffer is not large enough.\r
+  @param[in,out]  Ascii         Boolean value for indicating whether the file is \r
+                                Ascii (TRUE) or UCS2 (FALSE);\r
 \r
-  @retval EFI_SUCCESS           The operation was sucessful.  the line is stored in \r
-                                Buffer.  (Size was NOT updated)\r
+  @retval EFI_SUCCESS           the operation was sucessful.  the line is stored in \r
+                                Buffer.\r
   @retval EFI_INVALID_PARAMETER Handle was NULL.\r
-  @retval EFI_INVALID_PARAMETER Buffer was NULL.\r
   @retval EFI_INVALID_PARAMETER Size was NULL.\r
   @retval EFI_BUFFER_TOO_SMALL  Size was not enough space to store the line.  \r
                                 Size was updated to minimum space required.\r
@@ -368,7 +381,29 @@ FileHandleReadLine(
   IN EFI_FILE_HANDLE            Handle,\r
   IN OUT CHAR16                 *Buffer,\r
   IN OUT UINTN                  *Size,\r
-  IN BOOLEAN                    Truncate\r
+  IN BOOLEAN                    Truncate,\r
+  IN OUT BOOLEAN                *Ascii\r
+  );\r
+\r
+/**\r
+  Function to read a single line from a file. The \n is not included in the returned \r
+  buffer.  The returned buffer must be callee freed.\r
+\r
+  If the position upon start is 0, then the Ascii Boolean will be set.  This should be \r
+  maintained and not changed for all operations with the same file.\r
+\r
+  @param[in]      Handle        FileHandle to read from.\r
+  @param[in,out]  Ascii         Boolean value for indicating whether the file is Ascii (TRUE) or UCS2 (FALSE);\r
+\r
+  @return                       The line of text from the file.\r
+\r
+  @sa FileHandleReadLine\r
+**/\r
+CHAR16*\r
+EFIAPI\r
+FileHandleReturnLine(\r
+  IN EFI_FILE_HANDLE            Handle,\r
+  IN OUT BOOLEAN                *Ascii\r
   );\r
 \r
 /**\r
@@ -417,6 +452,8 @@ FileHandlePrintLine(
 \r
   This will NOT work on directories.\r
 \r
+  If Handle is NULL, then ASSERT.\r
+\r
   @param[in] Handle     the file handle\r
 \r
   @retval TRUE          the position is at the end of the file\r
@@ -427,3 +464,6 @@ EFIAPI
 FileHandleEof(\r
   IN EFI_FILE_HANDLE Handle\r
   );\r
+\r
+#endif //_FILE_HANDLE_LIBRARY_HEADER_\r
+\r