[[TOC]]

= CFile =

CFile is a C++ class that is provided to simplify 825 file operations. CFile is a wrapper class around the standard C library FILE object. CFile also provides some useful features such as baud rate setting for the 825 serial ports.

== Constructors ==

{{{
CFile(void);
CFile(const string& strFilename);
CFile(const char* pszfilename);
}}}
These constructors just create a CFile object without opening a file.
{{{
CFile(const string& strFilename, const string& strMode);
CFile(const string& strFilename, const char* pszMode);
CFile(const char* pszFilename, const string& strMode);
CFile(const char* pszFilename, const char* pszMode);
}}}
These constructors construct the file object and attempt to open the file.


==== Parameters ====
 * strFilename - filename
 * pszFilename - filename
 * strMode - mode
 * pszMode - mode

==== Examples ====

{{{
CFile fileLog("/mnt/fl1/log.txt", "a");
if(fileLog.IsOpen())
{
     fileLog.Print("Gross %s Tare %s Net %s\r\n", FormatGrossWt(1).c_str(), FormatTareWt(1).c_str(), FormatNetWt(1).c_str()); 
     fileLog.Close();
}
}}}

{{{
CFile fileLog("/mnt/fl1/log.txt");
}}}
This contructs the object to open later.

== Member Functions ==

=== Open ===
Opens a specified file, or using the filename already stored in the object.

{{{
bool Open(const string& strFilename, const string& strMode);
bool Open(const string& strFilename, const char* pszMode);
bool Open(const char* pszFilename, const string& strMode);
bool Open(const char* pszFilename, const char* pszMode);
bool Open(const char* pszMode);
}}}

==== Parameters ====
 * strFilename - filename
 * pszFilename - filename
 * strMode - mode
 * pszMode - mode

==== Return Value ====

Returns true if successful or false if unsuccessful.

==== Remarks ====

==== Example ====

{{{
CFile file;
if(file.Open("/tmp/tmpfile", "w") == false)
{
    DisplayText(0, 0, "Error writing temporary file");
}

}}}

=== Close ===
Closes the file
{{{
void Close(void);
}}}

==== Parameters ====

Function does not accept any parameters

==== Retrun Value ====
 
Function does not return any result.

==== Remarks ====

For serial ports it may be necessary to provide some delay to allow all of the buffered data to be sent out of the port before closing the port.

==== Example ====

{{{
CFile file("/dev/ttyS1", "w");
file.Print("This is a test\r\n");
SleepSeconds(1);
file.Close();
}}}

=== SetSerial ===
Set the baud rate, number of data bits, parity, and number of stop bits for serial ports.
{{{
bool SetSerial(baud_index baud, data_bit_index = data8, parity_index = parityNone, stop_bit_index = stopOne);
}}}

==== Parameters ====
 * baud_index
 * data_bit_index
 * parity_index
 * stop_bit_index

==== Return Value ====

Returns true if successful, false if not successful.

==== Remarks ====

==== Examples ====

{{{
CFile file("/dev/ttyS1", "w");
if(file.IsOpen())
{
   file.SetSerial(CFile::baud9600, CFile::data7, CFile::parityEven, CFile::stopOne);
}
}}}

{{{
CFile file("/dev/ttyS1", "w");
if(file.IsOpen())
{
   file.SetSerial(CFile::baud19200);
}
}}}

=== ReadLine ===
Reads a text file a line at a time.
{{{
bool ReadLine(std::string& strLine);
}}}

==== Parameters ====

 * strLine - string reference to return line read

==== Return Value ====

Returns true if line read, false if end of file

==== Remarks ====

==== Example ====

{{{
CFile file("/mnt/nand/apps/test/config.txt", "r");
if(file.IsOpen())
{
   string strLine;
   while(file.ReadLine(strLine) == true)
   {
       if(strLine.substr(0, 7) == "Setting")
       {
           // TODO Parse the settings line
       }
   }
   file.Close();
}
}}}

=== DeleteFile ===
Deletes a file
{{{
static bool DeleteFile(const string& strFilename);
static bool DeleteFile(const char* pszFilename);

bool DeleteFile(void);
}}}
==== Parameters ====
 * strFilename - string filename to delete
 * pszFilename - pointer to null terminated character array filename to delete

==== Return value ====
Returns true if successful, false if not successful.

==== Remarks ====

Versions of this fuctions that accept a filename are static so they do not require an CFile object.

==== Examples ====

{{{
string str = "/tmp/tmpfile";
CFile::DeleteFile(str);
}}}

{{{
if(CFile::DeleteFile("/tmp/tmpfile") == false)
{
   DisplayText(0, 0, "Delete file error");
}
}}}

{{{
CFile file("/tmp/tmpfile", "w");
if(file.IsOpen())
{
   file.Print("This will not exist very long\r\n");
   SleepSeconds(1);
   file.Close();
   SleepSeconds(1);
   file.DeleteFile();
}
}}}

=== IsReady ===
Check the state of the serial CTS input
{{{
bool IsReady(void);
}}}
==== Parameters ==== 

Function does not accept any parameters.

==== Return Value ====

Function returns true if CTS is active, false if CTS is inactive.

==== Remarks ====

IsReady() will return false if the CTS line is unconnected. Printers or other devices must be wired correctly for applications to be able to use this function to determine their readiness. '''The main board COM3 is not currently supported by this function.'''

==== Example ====

{{{
CFile fileLogOutput("/dev/ttyS1", "w");
if(fileLogOutput.IsOpen())
{
   fileLogOutput.SetRTS(true);
   if(fileLogOutput.IsReady() == false)
   {
      DisplayText(0, 0, "Printer offline, or disconnected");
   }
}
}}}


=== SetRTS ===
Set the state of the serial RTS output

{{{
bool SetRTS(bool bRTSOn = true);
}}}

==== Parameters ==== 

 * bRTSOn - true to turn on RTS output, false to turn off RTS output

==== Return Value ====

Returns true if successfully set RTS state, false otherwise.

==== Remarks ====

==== Example ====

{{{
CFile fileLogOutput("/dev/ttyS1", "w");
fileLogOutput.SetRTS(true);
}}}



=== GetFile ===

{{{
FILE* GetFile(void);
}}}

=== Print ===
Outputs text which may include format specifiers. For each format specifier an additional parameter must be provided.
{{{
void Print(const string& strFormat, ...);
void Print(const char* pszFormat, ...);
void Print(const string& strFormat, va_list& args);
void Print(const char* pszFormat, va_list& args);
}}}

==== Parameters ====

 * strFormat - string to output, may include format specifiers such as C printf statements
 * pszFormat - pointer to null-terminated string to output, may include format specifiers
 * ... - variable list of arguments that should match up with format specifiers
 * args - variable list of aguments structure

==== Return Value ====

Function does not return a value.

==== Remarks ====

==== Examples ====
{{{
string str = "Hello World\r\n";
file.Print(str);
}}}

{{{
int n = 5;
string str = "ABC";
file.Print("Number: %d String %s\r\n", n, str.c_str());
}}}

{{{
// This is a function to log update data to two devices
// g_fileLog1, and g_fileLog2 are globals that should already have been opened before this function is called.
void LogOutput(const char* fmt, ...)
{
   va_list args;
   va_start(args, fmt);

   g_fileLog1.Print(fmt, args);
   g_fileLog2.Print(fmt, args);

   va_end(args);
}

}}}

=== SetNonBlocking ===

{{{
void SetNonBlocking(void);
}}}


=== Read ===

{{{
bool Read(void * ptr, size_t size);
}}}

=== Write ===

{{{
bool Write(void * buf, size_t size);
}}}

=== GetBytesRead ===

{{{
size_t GetBytesRead(void);
}}}

=== GetbytesWritten ===

{{{
size_t GetBytesWritten(void);
}}}

=== Seek ===

{{{
bool Seek(long int offset, long int origin = SEEK_SET);
}}}