/*===========================================================================
 *
 * File:	DL_File.H
 * Author:	Dave Humphrey (uesp@m0use.net)
 * Created On:	Monday, May 07, 2001
 *
 * Contains file releated definitions for Dave's Library of common code.
 *
 *=========================================================================*/
#ifndef __DL_FILE_H
#define __DL_FILE_H


/*===========================================================================
 *
 * Begin Required Includes
 *
 *=========================================================================*/
  #include "dl_base.h"
  #include "dl_mem.h"
  #include "dl_log.h"
  #include "dl_err.h"
  #include "dl_chr.h"
  #include "dl_str.h"
/*===========================================================================
 *		End of Required Includes
 *=========================================================================*/


/*===========================================================================
 *
 * Begin Definitions
 *
 *=========================================================================*/

	/* Size of input/output buffer for the CopyFile() function */
  #if defined(__BCPLUSPLUS__)
    #define COPYFILE_BUFFERSIZE 1024u
  #elif defined(__TURBOC__)
    #define COPYFILE_BUFFERSIZE 60000u
  #else
    #define COPYFILE_BUFFERSIZE 60000u
  #endif

/*===========================================================================
 *		End of Definitions
 *=========================================================================*/


/*===========================================================================
 *
 * Begin ReadFile()/WriteFile() Mode Definitions
 *
 *=========================================================================*/
  #define FILE_BINARY FALSE
  #define FILE_TEXT   TRUE
/*===========================================================================
 *		End of ReadFile()/WriteFile() Mode Definitions
 *=========================================================================*/


/*===========================================================================
 *
 * Begin ReadLine() Return Type Definitions
 *
 *=========================================================================*/
  #define READLINE_ERROR (-1)
  #define READLINE_OK    (0)
  #define READLINE_MSL   (1)
  #define READLINE_EOF   (2)
 /*===========================================================================
 *		End of ReadLine() Return Type Definition
 *=========================================================================*/



/*===========================================================================
 *
 * Begin Function Prototypes
 *
 *=========================================================================*/

	/* Attempt to change directory to the given path */
  boolean ChangeDirectory (const char* pPath);

	/* Copy filename to a new string, changing it's extensions */
  char* ChangeExtension (char* pDestFilename, const char* pSourceFilename, 
		         const char* pNewExtension, const size_t MaxStringLength);

	/* Compare the extension with the given filename's extension */
  boolean CompareExtension (const char* pFilename, const char* pExtension);

  	/* Copy from the source to the destination file */
  boolean CopyOneFile (const char* pInputFile, const char* pOutputFile);
	
	/* Create a properly terminated path string */
  char* CreatePath (char* pNewPath, const char* pString, const size_t MaxStringLength);

	/* Copy the filename from a path to a string */
  char* ExtractFilename (char* pFilename, const char* pPath, const size_t MaxStringLength);

	/* Copy the path from a given string */
  char* ExtractPath (char* pPath, const char* pString, const size_t MaxStringLength);

	/* Checks to see if a file is available for reading */
  boolean FileExists (const char* pFilename);

	/* Return a pointer to the extension in a path */
  char* FindExtension (const char* pFilename);

	/* Return a pointer to the filename in a path */
  char* FindFilename (const char* pPath);

	/* Retrieve the size of a file in bytes */
  long    GetFileSize (const char* pFilename);
  long    GetFileSize (FILE* pFileHandle);
  boolean GetFileSize (long& FileSize, const char* pFilename);
  boolean GetFileSize (long& FileSize, FILE* pFileHandle);

	/* Returns TRUE if the given file has any extension */
  boolean HasExtension (const char* pFilename);

	/* Returns TRUE if the given filename contains a path */
  boolean HasPath (const char* pFilename);

	/* Returns TRUE if the given path is valid but does not change current path */
  boolean IsDirectory (const char* pPath);

  	/* Determines if a file can be written to */
  boolean IsFileWriteable (const char* pFilename);

	/* Returns TRUE if the given filename contains wildcard characters */
  boolean IsWildCard (const char* pFilename);
	
	/* Opens a file with fopen(), recording log and error information */
  FILE*   OpenFile (const char* pFilename, const char* pMode);
  boolean OpenFile (FILE** ppFileHandle, const char* pFilename, const char* pMode);

	/* Attempt to read in entire file to a newly allocated pointer */
  boolean ReadFile (char** pBuffer, size_t& BytesRead, const char* pFilename, const boolean TextMode = FILE_BINARY);

	/* Read all/part of a file to an existing buffer */
  boolean ReadFileBuffer (char** ppBuffer, size_t& BytesRead, const char* pFilename, 
		          const size_t MaxInputSize, const boolean TextMode = FILE_BINARY);

	/* Reads one line from the given file stream */
  int ReadLine (FILE* pFileHandle, char* pString = NULL, const size_t MaxStringLength = 1);

  	/* Read integers from a file stream */
  boolean read_int (FILE* pFileHandle, int& Value);
  boolean read_long (FILE* pFileHandle, long& Value);
  boolean read_short (FILE* pFileHandle, short& Value);
  boolean read_motlong (FILE* pFileHandle, long& Value);

	/* Removes any filename extension from the string */
  char* RemoveExtension (char* pFilename);

	/* Ensure the path string ends in the current path character */
  char* TerminatePath (char* pPath);

	/* Output a data buffer to a file */
  boolean WriteFile (const char* pBuffer, const size_t Size, const char* pFilename, const boolean TextMode = FILE_BINARY);

  	/* Write integers to a file stream */
  boolean write_short (FILE* pFileHandle, const short OutputValue);
  boolean write_int (FILE* pFileHandle, const int OutputValue);
  boolean write_long (FILE* pFileHandle, const long OutputValue);
  boolean write_motlong (FILE* pFileHandle, const long OutputValue);


/*===========================================================================
 *		End of Function Prototypes
 *=========================================================================*/


/*===========================================================================
 *
 * Begin Test Function Prototypes
 *
 * Prototypes for routines to test this module. Available only in DEBUG 
 * builds.
 *
 *=========================================================================*/
#if defined(_DEBUG)

	/* Maximum file size to use for Test_RWFile() */
  #if defined(__TURBOC__)
    #define TEST_RWFILE_MAXFILESIZE 65000u
  #else
    #define TEST_RWFILE_MAXFILESIZE 100000
  #endif
  	
	/* Helper function to create a random file of a given size */
  void Test_CreateRandomFile (const char* pFilename, const size_t Size, const boolean TextMode = FILE_BINARY);

	/* Helper function to compare two files */
  boolean Test_CompareFiles (const char* pFilename1, const char* pFilename2);

	/* Test routines */
  void Test_ChangeExtension (void);
  void Test_ChangeDirectory (void);
  void Test_CompareExtension (void);
  void Test_CopyFile (void);
  void Test_CreatePath (void);
  void Test_ExtractFilename (void);
  void Test_ExtractPath (void);
  void Test_FileExists (void);
  void Test_GetFileSize (void);
  void Test_HasExtension (void);
  void Test_HasPath (void);
  void Test_IsDirectory (void);
  void Test_IsFileWriteable (void);
  void Test_IsWildCard (void);
  void Test_ReadFile (void);
  void Test_ReadFileBuffer (void);
  void Test_read_int (void);
  void Test_read_long (void);
  void Test_read_motlong (void);
  void Test_read_short (void);
  void Test_ReadLine (void);
  void Text_RemoveExtension (void);
  void Test_RWFile (const size_t NumTests = 100);
  void Test_RWNumbers (const size_t NumTests = 1000);
  void Test_TerminatePath (void);
  void Test_WriteFile (void);
  void Test_DL_File (void);

#endif
/*===========================================================================
 *		End of Test Function Prototypes
 *=========================================================================*/


#endif
/*===========================================================================
 *		End of File DL_File.H
 *=========================================================================*/