ilEFSAddFileType(3X)

NAME

ilEFSAddFileType() − add support for a file type to the context and return an ilEFSFileType() data structure.

SYNOPSIS

ilEFSFileType
ilEFSAddFileType (

ilContext context,

ilEFSFileTypeInfo *pInfo,

void *pOptions);

DESCRIPTION

ilEFSAddFileType() adds support for a new file type to the context. This function is unnecessary for simply using EFS on existing file types. ilEFSAddFileType is for those who want to extend the Image Library capability by writing a file type handler.

ilEFSAddFileType() returns an ilEFSFileType data structure. This object is freed when you use ilDestroyObject() on it or when you use ilDestroyContext() on the associated context.

context is a context created by IL_CREATE_CONTEXT(). All functions are passed a parameter of the type ilEFSFile or ilEFSFileType and can reference the context through that parameter.

*pInfo is a structure that defines the file type to be added. See ilEFSGetFileInfo(3X) for a description of the fields in ilEFSFileTypeInfo. In that structure, reserved is reserved for future use and must be zero (0). The entire ilEFSFileTypeInfo structure must be zeroed, for example by using bzero(), before it is filled in.

checkOrder in ilEFSFileTypeInfo should be set to zero (0) to disable the IL_EFS_BY_CHECKING searchOptions mode of the ilEFSOpen() function. This may be done if practically any file could be a valid instance of this file type. Otherwise, checkOrder should be a number from 1 to 100. (File types with higher checkOrder are searched first.) A high value should be used for commonly occurring files which can be validated with some certainty. 100 should be reserved exclusively for TIFF files. Low values should be used for uncommon file types and for files, such as text files, that cannot be validated with much reliability.

For more information, refer to the checkOrder field description in the ilEFSGetFileTypeInfo(3X) man page.

Bits not defined in bit set fields are reserved for future use and must be set to zero (0).

*pOptions is reserved for future use and must be NULL (0).

After adding the file type, the caller may set the pPrivate field in the returned file type object to point to private data. This data is freed when the file type is destroyed, or it may be freed by the Destroy() function described subsequently in this man page.

The following sections describe the functions in *pInfo. (All functions must report error codes in fileType->context->error and return a NULL pointer.) Open() and Close() must be supplied if any bits are set in pInfo->openModes. Seek() must be supplied if the bit specified in IL_EFS_READ, is set in pInfo->openModes. ReadImage() and GetPageInfo() must be supplied if the bits specified in IL_EFS_READ or IL_EFS_READ_SEQUENTIAL (1<<IL_EFS_READ or 1<<IL_EFS_READ_SEQUENTIAL) are set in pInfo->openModes. WriteImage() must be supplied if the bit specified in IL_EFS_WRITE is set in pInfo->openModes. Destroy() and Escape() are optional. Functions not supplied must be set to NULL (0).

ilPtr
(*Open) (

ilEFSFileType fileType,

char *fileName,

unsigned int openMode,

unsigned long *pNPages);

Open() opens the file with the supplied name and initializes it. If an error occurs, Open() must declare an IL_ERROR_EFS_OPEN error.

If Open() succeeds, it must return a non-NULL pointer to private data, allocated from malloc(). The IL will then create an ilEFSFile object and set pPrivate in the object to the returned private pointer. When ReadImage(), WriteImage() or Close() are called, they are passed a pointer to the ilEFSFile object; pPrivate in the object is the pointer returned by Open(). Note that Close() is not called if Open() declares an error by returning NULL.

fileType is the file object to which this function belongs. If an error is declared, the error code must be set into fileType->context->error and Open() must return NULL.

*fileName is the name of the file to be opened.

openMode is read mode, ( IL_EFS_READ_SEQUENTIAL or IL_EFS_READ ) or write mode ( IL_EFS_WRITE ). openMode is always one of the modes supported by this file type, as listed in ilEFSFileTypeInfo.openModes.

If a read openMode is used, Open() must open the file for read access. If the file is not found, Open() must declare an IL_ERROR_EFS_OPEN error. If the file exists, Open() must determine if the file is a valid file for this file type by reading and validating headers. If the file is not valid for this file type, Open() must close the file and declare an IL_ERROR_EFS_NOT_MINE error. If the file contains no supported images, Open() must close the file and declare an IL_ERROR_EFS_EMPTY_FILE error.

*pNPages must be the set to the number of pages, if that number is known and a read openMode is used; *pNPages must be zero (0) if the page count is unknown or if openMode is IL_EFS_WRITE.

ilBool
(*Seek) (

ilEFSFile file,

unsigned long page);

Seek() positions the file to the page supplied. It will not be called if the file was not opened with an openMode of IL_EFS_READ, or if the file type does not support multi-page reads (ilEFSFileTypeInfo.attributes & IL_EFS_MULTI_PAGE_READS).

file is the name of the file.

page is the next page to read in the file.

For full details on these parameters, see ilEFSSeek().

ilBool
(*GetPageInfo) (

ilEFSFile file,

ilEFSPageInfo *pInfo);

GetPageInfo() returns the same information on the current page as returned by ilEFSGetPageInfo(). GetPageInfo() will not be called if the file was not opened with an openMode of IL_EFS_READ or IL_EFS_READ_SEQUENTIAL.

file is the name of the file.

*pInfo is information about the current page.

ilBool
(*ReadImage) (

ilPipe pipe,

ilEFSFile file,

unsigned int readMode,

unsigned long width,

unsigned long height);

ReadImage() adds a producer to the pipe to read the next image from the file. See ilAddPipeElement(3X) for how to add an element to a pipe. ReadImage() will not be called if the file was not opened with an openMode of IL_EFS_READ or IL_EFS_READ_SEQUENTIAL.

pipe is a pipe created by ilCreatePipe().

file is the file to be read.

readMode is either IL_EFS_READ_MAIN or IL_EFS_READ_MASK for file types that support mask images. For all other file types, readMode is IL_EFS_READ_MAIN.

ReadImage() must return IL_ERROR_EFS_READ_MODE if readMode is IL_EFS_READ_MASK and the current page has no mask. If a mask image is read, ReadImage() must produce it in a format compatible with WriteImage(). For details on this type of format, see the WriteImage() section on maskImage.

width, height
are the image width and height. It they are not zero and the page is scaleable, ReadImage() must produce an image of exactly that size. If the aspect ratio of width to height is not exactly right, an image of a larger size should be generated and ilCrop() should then be used to crop the image to the requested size.

For best performance, read the file into the pipe in strips. Use ilRecommendedStripHeight() to obtain the optimal strip height, supplying the size and description of the image to be read. If it is not feasible to read the image from the file in strips, the image should be read as one big strip; in this case, the IL will pass strips to elements further down the pipe.

If successful, ReadImage() must return TRUE; otherwise, it must return FALSE.

To use ReadImage() successfully, use both the preceding text and, for details on the ReadImage() parameters and behavior, see ilEFSReadImage(), which functions identically.

ilBool
(*WriteImage) (

ilPipe pipe,

ilEFSFile file,

unsigned long xRes,

unsigned long yRes,

ilClientImage maskImage);

WriteImage() adds a consumer to the pipe to write the pipe image to the file. See ilAddPipeElement() for details on adding an element to a pipe. The parameters to and behavior of WriteImage() are as described for ilEFSWriteImage(). WriteImage() will not be called if the file was not opened with an openMode of IL_EFS_WRITE.

If necessary, call ilConvert() to convert the current pipe image to the nearest format supported by this type of file. For example, if the file format supports only 8 bit IL_PALETTE images, convert it to that format to avoid returning an error. Note that ilConvert() returns an error if the conversion is not possible.

pipe is a pipe created by ilCreatePipe().

file is the file to be written.

xRes, yRes are the X and Y resolution of the image being written, in dots per inch (dpi) times two (2).

maskImage is either the client image, which is a mask to the pipe image to be written, or NULL meaning no mask image is to be written. maskImage will not be NULL only if the file type supports writing of mask images (that is, when ilEFS the expression (ilEFSFileTypeInfo.attributes & IL_EFS_MASK_WRITES) is non-zero. If not NULL, maskImage is guaranteed to be as described for ilEFSWriteImage(): a single sample, bit-per-pixel, uncompressed image the size of the pipe image with a rowBitAlign of 32, which means each scan line is an integral number of longwords on a longword boundary.

All write buffers should be flushed when the image is finished being written, for example, in the Cleanup() function of ilAddPipeElement().

If successful WriteImage() must return TRUE otherwise, it must return FALSE.

ilBool
(*Close) (

ilEFSFile file );

Close() is called before the file is destroyed. It must close the associated file and free any associated resources. It need not free the file private data (file->pPrivate); that data is automatically freed by the Image Library when the file is destroyed unless pPrivate is NULL. Close() must set pPrivate to NULL (0) if it does not want the private data freed. For example, it may have already freed the data.

Close() will not be called until all pipes containing a ReadImage() or WriteImage() element on this file have been destroyed. This assumes that ReadImage() and WriteImage() call ilDestroyObject() with the file in their Destroy() functions for ilAddPipeElement().

Close() is not called if the Open() for this file was not successful; that is, if it returned NULL.

ilBool
(*Destroy) (

ilEFSFileType fileType );

Destroy() is an optional function that is called (if not NULL) before the file type is destroyed. It should free any associated resources. It need not free the file private data (fileType->pPrivate) ; that data is automatically freed when the file type is destroyed unless pPrivate is NULL. Destroy() must set pPrivate to NULL (0) if it does not want the private data freed. For example, it may have already freed it.

Destroy() will not be called until all associated open files are closed. Unlike ReadImage() and WriteImage(), no call to ilDestroyObject() should be made; reference counting of the file type is handled within the IL.

If successful, Destroy() must return TRUE; otherwise, it must return FALSE.

RETURN VALUE

Upon successful completion, ilEFSAddFileType() returns an ilEFSFileType data structure.

ERRORS

If the call fails, context->error receives a non-zero error code.

Functions which implement EFS for a file type must follow IL error conventions. Each function should return either TRUE ( 1 ) or a pointer if the function succeeds; otherwise, it must set context->error to an IL error code listed in ilerrors.h and return FALSE ( 0 ) or NULL.

IL functions follow this convention, so if an IL function is called this requirement is satisfied. context->error is set to IL_OK (0) to indicate success before each file type function is called, so the function need only set context->error if an error occurs.

Only one of the following error codes may be placed in context->error by functions which implement EFS:

IL_ERROR_MALLOC
Returned by any function on malloc() failure

IL_ERROR_EFS_IO
Returned by any function on an I/O error

IL_ERROR_EFS_OPEN
Returned by Open() if the file cannot be opened

IL_ERROR_EFS_NOT_MINE
Returned by Open() if the file is not a valid instance of the identified the file type

IL_ERROR_EFS_OPEN_MODE
Returned by Open() if the file is valid but the identified openMode is not supported.

IL_ERROR_EFS_EMPTY_FILE
Returned by Open() if the file is valid but contains no images.

IL_ERROR_EFS_EOF
Returned by ReadImage() if positioned at EOF.

IL_ERROR_EFS_READ_MODE
Returned by ReadImage() if readMode is IL_EFS_READ_MASK and the current page has no mask.

IL_ERROR_EFS_FORMAT_ERROR
Returned by any function if invalid data is found in the file, but the file appears to be a valid instance of the file type.

IL_ERROR_EFS_UNSUPPORTED
Returned by any function if the file contains valid data not supported by the file type handler.

IL_ERROR_EFS_PRIVATE
Returned by any function to declare a the file type-specific error. The private error code should be set into context->errorInfo.

AUTHOR

ilEFSAddFileType() was developed by HP.

Museum

Related Articles

ilEFSAddFileType(3X)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

AUTHOR

SEE ALSO