Using CWriteFaxFile

The first phase in storing a fax is to use CWriteFaxFile::OpenL() to create and open the fax file. In the following fragment it is assumed that the CWriteFaxFile object has already been created.

// Create err variable and descriptors for panic and file name text
TInt err; 
_LIT(KFaxFileName, "c:\\test.fax");
_LIT(KPanicOpeningWriteFile,"Opening write file);

// create and open fax file. Panic if there is an error
TRAP(err,writeFaxFile->OpenL(KFaxFileName,64)); 
if (err!=KErrNone)
    User::Panic(KPanicOpeningWriteFile,err);

The code fragment above creates and opens the fax file test.fax. The OpenL() function is invoked under a trap harness, and the thread has been set up to panic if it leaves. The function takes the new fax name and number of scan lines in a band as arguments. The preferred number of scan lines in a band is 64 — the optimal number for fax viewing.

The OpenL() function also allocates memory for the CWriteFaxPages member variable, which is used to actually add pages to the store.

Adding a page involves defining the type of encoding to use, adding each of its scan lines, and then saving the page compression, resolution and sender ID information.

CWriteFaxPages::StartPage() is called first, to define the fax resolution and compression to be used to store the page. In the fragment below, the resolution is set as normal and the compression is set as Modified Huffman. It is not strictly necessary to call StartPage() in this case, because these settings are the same as the default encoding format and resolution.

//set the resolution as normal, and the encoding as MH 
iWriteFaxPages->StartPage(EFaxNormal, EModifiedHuffman);

The page’s scan lines are then individually added to the store. In the fragment below, the for loop adds numberLines scan lines to the page. The encoding format used for storage is the one that was specified in the previous call to StartPage(). AddScanLineL() can leave, so it is invoked in a trap harness.

// create scan line write buffer and set its size
TBuf8<216> scanlineWrite; 
scanlineWrite.SetLength(216);
//create panic descriptor for adding a scanline
_LIT(KPanicAddScanLine,"Adding scanline");
// create iteration variables
TInt row, numberLines;

// iterate through the scan lines, adding them to the page
for (row=0; row<numberLines; row++) 
    {
    scanlineWrite[0] = TUint8(row); 
        // create test scan line — for which the first byte is the current line number 
    // add test scan line. Panic if there is an error adding line
    TRAP(err,writeFaxFile->iWriteFaxPages->AddScanLineL(scanlineWrite)); 
    if (err!=KErrNone)    
        User::Panic(KPanicAddScanLine,err); 
    }

After adding the last scan line, the EndPage() function is called to add the page specific information to the file: e.g. encoding format, resolution, and sender information. The function can leave, and is hence called under a trap harness.

// create panic descriptor for end page
_LIT(KPanicEndingPage,"Ending page"); 

// call EndPageL() under a trap harness. Panic if error saving page information
TRAP(err,writeFaxFile->iWriteFaxPages->EndPageL(EFaxFine,senderId));
if (err!=KErrNone)
    User::Panic(KPanicEndingPage,err);

After each page has been added, it is important to commit it to the store — using the function WriteFaxFile::CommitL(). This ensures that the current page is safely stored in the fax file, so that it is not lost even if an out of memory error occurs as the next page is being added..

// create panic descriptor for commit page
_LIT(KPanicCommittingPages,"Committing pages"); 

// call CommitL() under a trap harness. Panic if error commiting page
TRAP(err,writeFaxFile->CommitL());
if (err!=KErrNone)
    User::Panic(KPanicCommittingPages,err);

Once again, the function can leave, and is hence invoked from within a trap harness.

When the last page has been added and committed the fax file should be closed. This is done using the CWriteFaxFile::Close() function.

// close the file
writeFaxFile->Close();    

Fax file storage can be aborted at any time using CWriteFaxFile::AbortWrite(). The function first aborts the storing operation, and then deletes the file. It can be called at any point prior to closing the file.

writeFaxFile->AbortWrite();