You can specify a file by a filename, a file descriptor, or both. If both are specified, the file descriptor is used to open the file. In this case, the filename is stored for use with error messages and the iflFile::getfileName() method.

The iflFile::open() method is defined as follows:

iflFile* open(fileDesc, filename, mode, format, status);

where fileDesc is the file descriptor.

The name of the file, filename, can be followed by an index to specify sub-images using the following syntax:

filename:index

For more information about changing the index after a file is open, see “Functions that Manipulate the Image Index”.

The mode argument specifies the read-write permissions set on the file. The two valid mode are read-only, O_RDONLY, and read-write, O_RDWR.

The format argument specifies the file format for the opened file. If you set this argument to NULL, the usual implementation, the file format is deduced from the file's contents, in particular, its magic number. You can, however, use the format argument to specify a file format.

The status argument is set to an error value if the open() method fails. If you have not implemented error messages, you should set this argument to NULL. If the method fails, the return value of the method is NULL.

If the open() method succeeds, an iflFile* pointer is returned to a derived class of iflFile, such as iflTIFFFile. The object created with open() can then be manipulated by the methods in the derived class. It is the application's responsibility to deallocate the object using the iflFile::close() method, for example,

newFileObject->close();

The iflFITFile file format uses two constructors to open a file. The first constructor uses just the filename to open the file, the second uses the file descriptor:

static iflFile* open(const char* filename, int mode = O_RDONLY,     iflStatus* status = NULL);
static iflFile* open(int fileDesc, const char* filename, 
    int mode = O_RDONLY, iflFormat* format = NULL, 
    iflStatus* status = NULL);

Example E-1 shows how ilFITFile.c++ implements opening a file.

iflStatus iflFITFile::openFile()
{
    int fd_opened_here = 0;
    iflStatus status;

    if (fd < 0) {
        assert(filename != NULL);
        fd = (iflStatus)::open(filename, accessmode);
        if (fd < 0)
            return iflStatusEncode(iflOPENFAILED, iflSubDomainUNIX, ::oserror());
        fd_opened_here = 1;
    }

    needHeader = 0;     // must be initialized for destructor!
    dataWritten = 1;    // so extensions can't be reserved

    // read the header
    if ((status = readHeader()) != iflOKAY) {
        if (fd_opened_here) {
            (void)::close(fd);
            fd = -1;
        }
        return status;
    }

    // fill in other info
    compression = iflNoCompression;
    calcPageParams();

    return iflOKAY;
}

You can create a new file by specifying many of the same values you used in the open() method. You can create a new file using a filename, a file descriptor, or both. If both are specified, the file descriptor is used to create the file and the filename is stored for use with error messages and the iflFile::getfileName() method.

The iflFile::create() method is defined as follows:

iflFile* create(fileDesc, filename, source, config, format, status);

All of the arguments in the create() method have the same mean as those described for the open() method. Only the source and config arguments are different.

The config argument is a structure defined in iflFileConfig that specifies a wide range of file characteristics, including the file's

If any of these characteristics are not given, the source argument is used to define them. If the source value is not defined, the characteristics default to the preferred values for the file format.

The source argument points at an iflFile object. If any of the file's characteristics are not defined in the config structure, the characteristics are set to be the same as those of the source object.

If the create() method succeeds, an iflFile pointer is returned to a derived class of iflFile, such as iflFITFile. If the method fails, the method returns NULL and you can use the status argument to set an error value.

Example E-2 shows how ilFITFile.c++ implements creating a file.

iflStatus iflFITFile::createFile()
{
    // validate the c page size
    if (pageSize.c == 0)
        pageSize.c = order==iflSeparate? 1:size.c;
    else if (order != iflSeparate && pageSize.c != size.c)
        return iflStatusEncode(iflBADPARAMS);

    if (fd < 0) {
        assert(filename != NULL);
        fd = ::open(filename, accessmode|O_CREAT|O_TRUNC, 0666);
        if (fd < 0)
            return iflStatusEncode(iflOPENFAILED, iflSubDomainUNIX, ::oserror());
    } else {
        (void)::ftruncate(fd, (off_t)0);
    }

    dataOffset = userOffset = sizeof(FIThead02);

    // flag the header/data as not written
    needHeader = 1;
    dataWritten = 0;

    calcPageParams();

    scaleMinValue = iflDataMin(dtype);
    scaleMaxValue = iflDataMax(dtype);

    return iflOKAY;
}

Whether you open or create a new file object, you must write a destructor that terminates it. This destructor needs to:

You use the iflFile::close() member function to close files, defined as follows:

iflStatus close(int flags = 0);

where flags can be set to IFL_CLOSE_DISCARD which means that iflFile::flush() is not automatically called so that buffered file data is not flushed when the file object is closed.

The close() method performs the following tasks:

The close() method automatically calls the iflFile::flush() and iflFile::closeFile() methods to carry out these tasks. Even if any of these three methods returns an error, the above tasks are performed.

---

Note: The file descriptor is closed even if it is opened prior to the original iflFile::open() or iflFile::create() call. To keep a file descriptor open, use dup() on the file descriptor before closing the file and then pass the duplicated file descriptor to an open() or create() method.

---

The following code shows how you might implement a destructor for a file format:

iflFileFormat::~iflFileFormat() {FileFormat->close();}

Example E-3 shows how ilFITFile.c++ implements closing a file.

iflStatus iflFITFile::closeFile()
{
    assert(fd >= 0);

    if (::close(fd) != 0)
        return iflStatusEncode(iflCLOSEFAILED, iflSubDomainUNIX, ::oserror());

    return iflOKAY;
}

iflStatus
iflFITFile::flush()
{
    // update the header if necessary
    if (needHeader) {
        iflStatus status = writeHeader();
        if (status != iflOKAY) return status;
        needHeader = 0;
    }
    return iflOKAY;
}

iflFile::parseFileName() is a static class member function. It is used to parse a file name for IFL. IFL file names have the following syntax:

<name-of-file>[#<format-name>][:<sub-image-index>]
    [%<format-specific-args>]

This function is called automatically by the iflFile::open() member function. It is defined as follows:

static char* parseFileName(const char* fullname, 
    char** formatName=NULL, int* index=NULL, char** formatArgs=NULL);

The return value is the actual filename and must be deleted by the user. The sub-image index can be returned using index if it is non-NULL. If an index is not present in the filename, -1 is returned. The format name can be returned using formatName if it is non-NULL. If no format name is present in the filename, NULL is returned. The format-specific argument string can be returned using formatArgs if it is non-NULL. If format-specific arguments are not present in the filename. NULL is returned.

In addition to providing functions that open and close files, you need to override getPage(), setPage(), getTile(), and getPage() to read and write image data in your file format. These functions are declared as follows:

virtual iflStatus getPage(void* data, int x, int y, int z, int c,
                     int nx, int ny, int nz, int nc);
virtual iflStatus setPage(const void* data, int x, int y, int z, int c,
                     int nx, int ny, int nz, int nc);
iflStatus getTile(int x, int y, int z, int nx, int ny, int nz,
                     void *data, const iflConfig* config=NULL);
iflStatus setTile(int x, int y, int z, int nx, int ny, int nz,
                     const void *data, const iflConfig* config=NULL);

The data argument for getPage() is a pointer to an already allocated, page-sized buffer into which data is read. This buffer must be large enough to hold a page of data. For setPage(), data is a pointer to a page-sized chunk of memory that contains data that will be written to disk. These functions are described in greater detail in the following sections.

These member functions are used by an IFL application to read image data from an image file into memory, or to write image data from memory to an image file.

Standard practice is to use getTile(), setTile() functions. They enable reading and writing of arbitrary rectangular regions, tiles, with an arbitrary datatype, dimension ordering, and orientation.

Optimized applications may use the lower-level getPage(), setPage() functions. The specified regions in these function are the file's natural pages.

Using setTile()

This member function writes an arbitrary rectangular region from a memory buffer into the image file. The portions of the memory buffer corresponding to area outside the boundaries of the source file image are ignored.

The arguments x, y, z, nx, ny, nz specify the origin and size of the target tile within the destination image file, in the orientation indicated in the config parameter. The data argument specifies the address of the memory buffer containing the data to be written. The config argument describes the configuration of the memory buffer. Its orientation affects the interpretation of x, y, z, nx, ny, nz.

A successful call to setTile() returns iflOKAY. If an error occurs, an iflStatus error value is returned describing the error. In an error condition, the buffer's contents are undefined.

---

Note: setTile() may make calls to the subclass's getPage() and setPage() functions in order to write a tile that is not aligned with the file's pages.

---

Using getPage()

This virtual member function reads a page of image data from the image file. The data argument specifies the address of the memory buffer into which the data should be placed. The arguments x, y, z, nx, ny, nz specify the origin and size of the desired page within the source image file. The caller must guarantee that nx, ny, nz are the image's page size and that x, y, z are a multiple of the page size. No checking is done by the function.

A successful call to getPage() returns iflOKAY. If an error occurs, an iflStatus error value is returned describing the error. In an error condition, the buffer's contents are undefined.

---

Note: If the caller makes multiple, concurrent calls to getPage() or setPage(), it needs to set i/o callbacks.

---

getPage() is required to surround code that must be executed atomically by calls to beginFileIO().

iflStatus
iflFITFile::getPage(void* data, int x, int y, int z, int c, int,int,int,int)
{
    iflStatus returnval = iflOKAY;
    beginFileIO();
    lseek (fd, pageOffset(x,y,z,c), SEEK_SET);
    int sts = read(fd, data, pageSizeBytes);
    if (sts == -1)
        returnval = iflStatusEncode(iflREADFAILED, iflSubDomainUNIX, ::oserror());
    endFileIO();

    return returnval;
}

iflStatus
iflFITFile::setPage(const void* data, int x,int y,int z,int c,int,int,int,int)
{
    iflStatus returnval = iflOKAY;
    beginFileIO();
    lseek (fd, pageOffset(x,y,z,c), SEEK_SET);
    int sts = write(fd, data, pageSizeBytes);
    if (sts == -1)
        returnval = iflStatusEncode(iflWRITEFAILED, iflSubDomainUNIX, ::oserror());
    endFileIO();

    dataWritten = 1;

    return returnval;
}

An image file can contain more than one image, depending on the file format. For example, the TIFF and GIF formats allow a file to contain any number of unrelated images, and the Kodak Photo CD Image Pac (PCD) and JFIF formats allow access to multiple resolutions of the same image. You can use image operations and queries on each image in a file by using an iflFile object's current image index.

The functions you can use to manipulate an image index are

The application can change the index by calling the object's setCurrentImg() method. The current index and total number of images in the file can be queried by calling the getCurrentImg() or getNumImg() method, respectively. The initial index may also be set by specifying an index with the filename argument to iflFile::open().

---

Note: These operations are meaningful even if the file format does not support multiple images per file. In that case, getNumImgs() returns 1, getCurrentImg() returns 0, and setCurrentImg(i) will succeed only if i == 0.

---

The following sections describe these functions in greater detail.

virtual int getNumImgs();

virtual int getCurrentImg();

virtual iflStatus setCurrentImg(int i);

If an image file has write permissions and the file format supports the addition of images, an application can use appendImg() to append an image to an image file. When the function succeeds, the new image in the file is given an index number and the index marker is updated to that of the added image.

The function is defined as follows:

virtual iflStatus appendImg(iflFile* source, iflFileConfig* fc=NULL);

The dimensions, datatype, dimensionorder, colormodel, compression, and pagedims parameters specified in the iflFileConfig structure are treated the same as in the create() static member function.

If the operation is successful, the function returns iflOKAY. If the operation fails, an ifl error is returned using the iflError() mechanism. and the file's contents and the object's current index will be in an unknown state.

A derived class must define all of the following pure virtual functions found in iflFormat:

Defining all of these functions fully characterizes the derived file format. newfileobj() tells iflFile::open() how to create an iflFile object in the derived format.

Each image file format subclass must declare a single static object of its derived type. Because the base class constructor is invoked automatically when the DSO is opened (because of the static object declaration) the derived format is placed on the global format list as part of its initialization. The following code shows you a sample declaration:

static iflFITFormat theFITformat;

If you install ifl_dev.sw.gifts, you can check the source code provided in /usr/share/src/ifl for examples of deriving from iflFormat.

This section describes all of the virtual functions listed in “Deriving Subclasses”.

The following section shows you a code excerpt that defines all of these virtual functions.

Example E-6 shows an excerpt from iflFITFile.c++ that demonstrates how the virtual functions in iflFormat are defined.

class iflFITFormat : public iflFormat {
public:

    iflFITFormat() : iflFormat(“FIT”) {} 
    int typeIsSupported(iflDataType) { return 1; }
    int orderIsSupported(iflOrder) { return 1; }
    int orientationIsSupported(iflOrientation) { return 1; }
    int colorModelIsSupported(iflColorModel) { return 1; }
    int compressionIsSupported(iflCompression cmp)
        { return cmp == iflNoCompression; }
    int sizeIsSupported(int,int,int,int, iflOrientation)
        { return 1;}
    int pagingIsSupported() { return 1; }
    int pageSizeIsSupported(int,int,int,int, int,int,int,int,         iflOrientation)
        { return 1; }
    int randomAccessReadIsSupported() { return 1; }
    int randomAccessWriteIsSupported() { return 1; }
    virtual iflDataType getPreferredType() { return iflUChar; }
    virtual iflOrder getPreferredOrder() { return iflInterleaved; }
    iflOrientation getPreferredOrientation() 
        { return iflLowerLeftOrigin; }
    virtual iflColorModel getPreferredColorModel(int nc)
        { return nc == 0? iflRGB : iflColorModelFromChans(nc); }
    virtual iflCompression getPreferredCompression()
        { return iflNoCompression; }
    void getPreferredPageSize(int, int, int, int sc,
        int& pWidth, int& pHeight, int& pz, int& pc, iflOrientation)
        { pWidth = 128; pHeight = 128; pz = 1; pc = sc; }
    iflFile* newfileobj() { return new iflFITFile; }
};
// This static object declaration causes the file format to be 
// automatically registered when the DSO containing this code is 
// dlopen'ed.

static iflFITFormat theFITformat;

To add support for a new image file format, you create a Dynamic Shared Object (DSO) that implements the format and adds an entry in the IFL file format database. IFL uses a text database file to determine what file formats IFL can use. The database is normally located in the file, usr/lib/ifl/ifl_database, but this location may be changed using the IFL_DATABASE environment variable.

You can add your own file formats to the database manually by using the following procedure: