How to use OS Cooperative File Function Extended Environment layer

A class called OSFileFunc is made available at application level by including wefts.h (provided your system has been wrapped). This class has the interface described by OSFileFuncBase class. Some system dependant implementations may have peculiarities, so be also certain to ckeck:

• Wefts::OSFileFuncBase for generic template and description.
• Wefts::OSFileFuncWin for MS-Windows implementation.
• Wefts::OSFileFuncUnix for UNIX and unixlike implementation.

This is a typical example of OSFileFunc usage: a file copy routine.

// $Id: filecopy.cpp,v 1.2 2004/03/08 22:44:06 jonnymind Exp $
// filecopy.cpp - an introductory test
//
// This program is free software - GPL 2.0 license
// (C) Giancarlo Niccolai
//
// NOTE: this program is demonstrative and hence not compiled
//       in the make process of Wefts test suite.
//

#include <iostream>
#include <wefts.h>

using namespace Wefts;
using namespace std;

int main( int argc, char *argv[] )
{
   if ( argc != 3 ) {
      cout << "usage: filecopy <from> <to>" << endl;
      return 0;
   }
 
   // Theese are our files; we instantiate from OSFileFunc, which
   // incarnates the correct system specific implementation.
   OSFileFunc filein, fileout;
   
   if ( filein.open( argv[1] ) != CFF_DONE ) {
      cout << "Can't open file " << argv[1] << endl;
      cout << "Os error: " << filein.osError() << endl;
      return 1;
   }
   
   if ( fileout.create( argv[2] ) != CFF_DONE ) {
      filein.close();
      cout << "Can't create file " << argv[2] << endl;
      cout << "Os error: " << fileout.osError() << endl;
      return 1;
   }

   unsigned long desc1, desc2;
   // In Windows, they will be handles of some kind.
   // In Unix, they will be numbers.
   filein.getDescriptor( &desc1 );
   fileout.getDescriptor( &desc2 );
   cout << "Low level file descriptors: " << argv[1] << ": " << desc1 
         << "  " << argv[2] << ": " << desc2 << endl;
   
   char buf[1024];
   int len = filein.read( buf, 1024 );
   while ( len > 0 ) {
      if ( fileout.write( buf, len ) != len ) {
         cout << "Error while writing file: " << fileout.osError() << endl; 
         filein.close();
         return 1;
      }
         
      len = filein.read( buf, 1024 );
   }
   
   if ( len < 0 ) {
      cout << "Error while reading file: " << filein.osError() << endl; 
   }
   else {
      cout << "Copy complete." <<endl;
      filein.close();
   }
   
   fileout.close();
   return 0;
}

In the example, we used OSFileFunc::osError() to report the error condition, but COFFEE has also a multi-platform error condition generic status that informs the program about the severity and the kind of the encountered error. Also, we have opened and created the files with standard flags, but COFFEE provides multi-platform flags that can be use to write fully portable simple programs.

When things gets nastier, the application can retrieve the low level file descriptor (or handle) by passing an adequate type to the OSFileFunc::getDescriptor() method, and work on the returned value. This allows to use thread compliancy of the read/write (and open/create) COFFEE functions altogether with advanced features that may be accessed at system level. Also, it's possible to pass a descriptor opened with low level system function to the OSFileFunc using the setDescriptor(). This allows to use thread-safe and wefts compliant reads and writes on descriptors that are created in some special system dependant ways.

Todo:

Write a stream interface for OSFileFuncBase.

---