Inheritance diagram

Collaboration diagram

Description

The SFXFile class is for creating a file, reading from file or writing to file, obtaining file information, and creating a temporary file.

Sample code for reading data from a file.

SFCError error;  // error value
SFXFile file;    // instance of SFXFile class
SFXAnsiStringStreamReader reader; // input stream for reading data from file
SFXAnsiString stringFromFile;     // string to be read from file
SFXAnsiString tempString;

// open file in ReadOnly mode
if ((error = file.OpenReadOnly(SFXPath("/dir1/data.txt"))) == SFERR_NO_ERROR) {

    // get input stream for reading data from file(buffer size = 1024)
    if ((error = file.GetStreamReader(1024, &reader)) == SFERR_NO_ERROR) {

        while (!reader.Ends()) { //  repeat until end of stream is reached

            // read data from file to input stream actually
            // up to 1024 bytes of data can be read since buffer size is specified
            if ((error = reader.Fetch()) != SFERR_NO_ERROR) {
                // if error occurs
                break; 
            }

            // read data from input stream to tempString
            if ((error = reader.ReadSFXAnsiString(&tempString))
                != SFERR_NO_ERROR) { 
                // if error occurs
                break;
            }

            // append tempString onto stringFromFile
            stringFromFile += tempString;
        }
        
        reader.Release();
    }
    file.Close();
}

Sample code for writing data to a file.

SFCError error;  // error value
SFXFile file;    // instance of SFXFile class 
SFXAnsiStringStreamWriter writer; // output stream for writing data to file
SFXAnsiString string("abcdefghijklmnopqrstuvwxyz");  // data to be written
ACharConstPtr p = string.GetBuffer();                // pointer to string
ACharConstPtr endOfString = p + string.GetLength();  // end of string

SInt32 bufferSize = 1024;

// open file in Read/Write mode
if ((error = file.OpenReadWrite(SFXPath("/dir1/data.txt")))
    == SFERR_NO_ERROR) {

    // get output stream for writing data to file
    if ((error = file.GetStreamWriter(bufferSize, &writer))
        == SFERR_NO_ERROR) {

        for (; p < endOfString; p += bufferSize) {

            // write size
            SInt32 size = (endOfString - p < bufferSize) ? endOfString - p : bufferSize;

            // write string to output stream
            if ((error = writer.Write(p, size)) != SFERR_NO_ERROR) {
                // if error occurs
                break; 
            }
            // write data from output stream to file actually 
            if ((error = writer.Flush()) != SFERR_NO_ERROR) { 
                // if error occurs
                break;
            }
        }
        writer.Release();
    }
    file.Close();
}

Reference

SFXDirectory | SFXPath | File Class

Member

Reference

SFXFile::SetCacheSize

Description

Close an opened file.

Reference

SFXFile::ScheduleRead

Description

Cancel the callback function and close the open file.

Example

SFXFile file;

...

file.Close();  // close file

Reference

SFXFile::Create | SFXFile::OpenReadOnly | SFXFile::OpenReadWrite

Return value

Description

If the force argument is set to true, create the directories which do not exist in the specified path.

Example

// create file forcedly
// create parent directory if not exist
SFXFile::Create(SFXPath("/dir1/data.txt"), true);

Reference

SFXFile::OpenReadOnly | SFXFile::OpenReadWrite

Return value

Example

UInt32 space;

SFXFile::DeviceFreeSpace(&space); // get free space of device

Reference

SFXFile::DeviceTotalSpace

Return value

Example

UInt32 space;

SFXFile::DeviceTotalSpace(&space); // get device capacity

Reference

SFXFile::DeviceFreeSpace

Return value

Example

Bool b;

// return value of Exists function is of SFCError type
// b: set by Exists function whether specifiled file exists or not

SFXFile::Exists(SFXPath("/dir1/data.txt"), &b);

if (b) {
    // when file exist
    ...

}

Reference

SFXFile::IsReadOnly | SFXFile::IsSystem

Reference

SFXFile::SetCacheSize

Return value

Example

SFXDate date;

// get creation date of file
SFXFile::GetCreateDate(SFXPath("/dir1/data.txt"), &date);

Description

Get the file interface (instance of SFBFile class) that is used internally.

Reference

SFBFile

Return value

Example

UInt32 size;

SFXFile::GetSize(SFXPath("/dir1/data.txt"), &size); // file size is stored in the size variable

Return value

Description

The buffer size of the input stream can be specified. Use the SFXBinaryStreamReader, SFXAnsiStringStreamReader, or SFXWideStringStreamReader class for the input stream properly according to the type of data to read.

Example

SFXFile file;
SFXAnsiStringStreamReader reader;
SFXAnsiString temp;
SFXAnsiString string;       // variable in which data read from file is stored
SFXPath path("/data.txt");  // file name

// open file in ReadOnly mode
if (file.OpenReadOnly(path) == SFERR_NO_ERROR) {
    // when success
    
    // get input stream for reading data from file
    file.GetStreamReader(1024, &reader);
    
    // repeat until end of file is reached
    while (!reader.Ends()) {
        if (reader.GetReadableSize() == 0) {
            // read data from file to input stream actually
            reader.Fetch();
        }
        // read data from input stream to temp
        reader >> temp;
        string += temp;
    }
    file.Close();  // close file
}

Reference

SFXFile::GetStreamWriter | SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader

Return value

Description

The buffer size of the output stream can be specified. Use the SFXBinaryStreamWriter, SFXAnsiStringStreamWriter, or SFXWideStringStreamWriter class for the output stream properly according to the written data type

Example

SFXFile file;
SFXAnsiStringStreamWriter writer;
SFXAnsiString string("abcdefg"); // string to write to file
SFXPath path("/data.txt");       // file name

// open file
if (file.OpenReadWrite(path) == SFERR_NO_ERROR) {
    // when success
    
    // get output stream for writing data to file
    file.GetStreamWriter(string.GetLength(), &writer);
    // write data from string to output stream
    writer << string;
    // write data from output stream to file actually
    writer.Flush();
    
    file.Close();  // close file
}

Reference

SFXFile::GetStreamReader | SFXBinaryStreamWriter | SFXAnsiStringStreamWriter | SFXWideStringStreamWriter

Return value

Description

The SFXFile::GetTemporaryPath function returns the temporary file path that does not duplicate existing ones.

	Note
	To get the permanent file which is not temporary one, use the SFXFile::GetUniquePath function.

	Note
	The SFXFile::GetTemporaryPath function internally calls the SFXFile::GetUniquePath function by specifying "sfx" as the prefix argument and "fle.tmp" as the suffix argument respectively.

Example

SFXPath dir("/");
SFXPath path;

if (SFXFile::GetTemporaryPath(path, &path) == SFERR_NO_ERROR) {
    // file path like "/sfx7182CBD4fle.tmp" will be created
    TRACE("%s", path.Get().GetCString());
}

Reference

SFXFile::GetUniquePath | SFXDirectory::GetTemporaryPath | SFXDirectory::GetUniquePath

Return value

Description

Since the file name is generated using a random number, this function might fail in case many files have already existed.

	Note
	If the file name generated using a random number has already existed, repeat to retry this operation up to 64 times. Nevertheless, in case the file path that does not duplicate existing ones can not be generated, this function will fail.

	Note
	To get the temporary file path which will be deleted soon, use the SFXFile::GetTemporaryPath function.

Example

SFXPath dir("/");
SFXPath path;

if (SFXFile::GetUniquePath(dir, "sfx", ".dat", &path) == SFERR_NO_ERROR) {
    // file path like "/sfx7182CBD4.dat" will be obtained
    TRACE("%s", path.Get().GetCString());
}

Reference

SFXFile::GetTemporaryPath | SFXDirectory::GetUniquePath | SFXDirectory::GetTemporaryPath

Return value

Example

Bool b;

// return value of isReadOnly function is of SFCError type
// b: set by isReadOnly function whether specifiled file is read only or not

SFXFile::IsReadOnly(SFXPath("/dir1/data.txt"), &b);

if (b) {
    // when file is read only
    ...
}

Reference

SFXFile::Exists | SFXFile::IsSystem

Return value

Reference

SFXFile::Exists | SFXFile::IsReadOnly

Return value

Example

SFXFile file;

// open file in read only mode
if (file.OpenReadOnly(SFXPath("/dir1/data.txt")) == SFERR_NO_ERROR) {
    
    ...
    
    // close file
    file.Close();
}

Reference

SFXFile::Create | SFXFile::OpenReadWrite

Return value

Example

SFXFile file;

// open file in read/write mode
if (file.OpenReadWrite(SFXPath("/dir1/data.txt")) == SFERR_NO_ERROR) {

    ...

    // close file
    file.Close();
}

Reference

SFXFile::Create | SFXFile::OpenReadOnly

Return value

Example

Copy a file (src.txt) to another file (dst.txt).

SFXFile fin;
SFXFile fout;
SFXBinaryStreamReader reader;
SFXBinaryStreamWriter writer;
SFXBuffer buffer;

// open input file in read only mode
if (fin.OpenReadOnly(SFXPath("/src.txt")) == SFERR_NO_ERROR) {
    // open output file in read/ write mode
    if (fout.OpenReadWrite(SFXPath("/dst.txt")) == SFERR_NO_ERROR) {
        
        fin.GetStreamReader(1024, &reader);    // get input stream for reading
        fout.GetStreamWriter(1024, &writer);   // get output stream for writing

        UInt08 c;
        
        // repeat until end of file is reached
        while (!reader.Ends()) { 
            buffer.SetSize(reader.GetReadableSize());
            reader.Fetch();       // read data from file to input stream
            reader.Read(&buffer); // read data from input stream to buffer
            writer.Write(buffer); // write data from buffer to output stream
            writer.Flush();       // write data from output stream to file
        }
        fout.Close();  // close output file
    }
    fin.Close();       // close input file
}

Reference

SFXFile::OpenReadOnly | SFXFile::OpenReadWrite | SFXFile::Seek | SFXFile::Write

Return value

Example

if (SFXFile::Remove(SFXPath("/dir/data.txt")) == SFERR_NO_ERROR) {
   ...
}

Return value

Example

Move data.txt from the dir1 directory to the dir2 directory.

if (SFXFile::Rename(SFXPath("/dir1/data.txt"), SFXPath("/dir2/data.txt"))
    == SFERR_NO_ERROR) {
    ...
}

Rename data.txt in dir1 directory to file.txt

if (SFXFile::Rename(SFXPath("/dir1/data.txt"), SFXPath("/dir1/file.txt"))
    == SFERR_NO_ERROR) {
    ...
}

Return value

Description

The SFXFile::ScheduleRead function is used to register the callback function in which the SFXFile::Read function is used to read data from file.

	Note
	When the return value of SFXFile::Read function is AEE_STREAM_WOULDBLOCK or there is still remaining data to read, register the callback function using the SFXFile::ScheduleRead function, and then schedule the SFXFile::Read function in the callback function again.

Example

class MyClass {
    SFXFile _file;
    Void Function(Void);
    CALLBACK_DECLARE_SFXFILE(_SFXFile_OnRead)
};

Void MyClass::Function(Void)
{
    SFXPath  path("/dir1/data.txt");
    
    // read file in read only mode
    if (_file.OpenReadOnly(path) == SFERR_NO_ERROR) {
        // schedule to read data from file
        _file.ScheduleRead(CALLBACK_FUNCTION(_SFXFile_OnRead));// register the callback function  
    }
}

// callback function
CALLBACK_IMPLEMENT_SFXFILE(MyClass, _SFXFile_OnRead, error)
{
    SFXBuffer buffer;
    UInt32 size;

    buffer.SetSize(32);  // allocate buffer for reading data from file

     size = buffer.GetSize();  
     // read data from file to buffer
     switch (_file.Read(buffer.GetBuffer(), &size)) {
         case SFERR_NO_ERROR:
             // display the read data
             buffer.SetSize(size + 1);
             buffer[buffer.GetSize() + 1] = '\0';
             TRACE("%s", SFXAnsiString(buffer).GetCString());
             // schedule to read data from file
             _file.ScheduleRead(CALLBACK_FUNCTION(_SFXFile_OnRead));  // register the callback function
             break;
         case EFILEEOF:
             _file.Close();  // close file
             break;
         case AEE_STREAM_WOULDBLOCK:
             // schedule to read data from file
             _file.ScheduleRead(CALLBACK_FUNCTION(_SFXFile_OnRead));  // register the callback function
             break;
        }
    return;
}

Reference

SFXFile::Cancel

Description

Return SFERR_UNSUPPORTED.

Return value

Description

To move the file pointer backward, set a negative value as moving amount to the distance argument.

When the file is opened in read only mode, if the position of file pointer after moved by this function is under the head of file or over the end of file, this operation will fail.

When the file is opened in read/write mode, if the position of file pointer after moved is over the end of file, the file will be expanded to that position. And if the position of file pointer after moved is under the head of file, this operation will fail.

Reference

SFXFile::SeekStart | SFXFile::SeekEnd | SFXFile::Tell

Return value

Description

To move the file pointer backward, set a negative value as moving amount to the distance argument.

When the file is opened in read only mode, if the position of file pointer after moved by this function is under the head of file or over the end of file, this operation will fail.

When the file is opened in read/write mode, if the position of file pointer after moved is over the end of file, the file will be expanded to that position. And if the position of file pointer after moved is under the head of file, this operation will fail.

Reference

SFXFile::Seek | SFXFile::SeekStart | SFXFile::Tell

Return value

Description

To move the file pointer backward, set a negative value as moving amount to the distance argument.

When the file is opened in read only mode, if the position of file pointer after moved by this function is under the head of file or over the end of file, this operation will fail.

When the file is opened in read/write mode, if the position of file pointer after moved is over the end of file, the file will be expanded to that position. And if the position of file pointer after moved is under the head of file, this operation will fail.

Reference

SFXFile::Seek | SFXFile::SeekEnd | SFXFile::Tell

Reference

SFXFile::GetCacheSize

Example

// truncate file at present position of file pointer
file.Truncate(file.Tell());

Reference

SFXFile::Seek | SFXFile::SeekStart | SFXFile::SeekEnd

Return value

Example

// truncate file at present position of file pointer
file.Truncate(file.Tell());

Reference

SFXFile::Seek | SFXFile::SeekStart | SFXFile::SeekEnd | SFXFile::Tell

Return value

Description

Write data to file without using the output stream.

Reference

SFXFile::OpenReadOnly | SFXFile::OpenReadWrite | SFXFile::Read SFXFile::Seek |