ilEFSOpen(3X)

NAME

ilEFSOpen() − open a file and return an ilEFSFile object

SYNOPSIS

ilEFSFile
ilEFSOpen (

ilContext context,

char *fileName,

unsigned int openMode,

unsigned long searchOptions,

char *typeName,

void *pOptions);

DESCRIPTION

ilEFSOpen() opens a file, associates it with a file type, and returns a file object, which is passed to other EFS functions to access the file. This file is closed when you use ilDestroyObject() on it or when you use ilDestroyContext() on the associated context.

context is a context created by IL_CREATE_CONTEXT().

*fileName is a pointer to the file.

openMode determines how the file is opened. Use one of the following values:

IL_EFS_READ opens the file for read-only random access. Images can be read in any order from a multi-page file. Pipes starting with a read from the file can be re-executed; each execution reads the same image from the file.

IL_EFS_READ_SEQUENTIAL
opens the file for read-only sequential access. Images can only be read sequentially from the file. Pipes starting with a read from the file must not be executed more than once.

Use this mode when random access is not required, such as when converting from one file format to another.

IL_EFS_WRITE opens the file for write (replace) access.

searchOptions is a value used in combination with typeName. It can be one or more of these values: IL_EFS_READ_SEARCH, IL_EFS_BY_TYPE_NAME, IL_EFS_BY_EXTENSION, or IL_EFS_BY_CHECKING.

*typeName is used to determine the file type. ilEFSOpen() performs four steps in this order:

1) If searchOptions is set to IL_EFS_BY_TYPE_NAME, and typeName is not NULL, searches the list of file type handlers a match on that type name.

2) If searchOptions is set to IL_EFS_BY_EXTENSION, ilEFSOpen() extracts an extension from *fileName and searches the list of file type handlers for a matching extension. If *fileName has no extension, this step is omitted.

3) If searchOptions is set to IL_EFS_BY_CHECKING, and openMode is IL_EFS_READ or IL_EFS_READ_SEQUENTIAL, ilEFSOpen() calls each file type handler to open the file until a handler declares that the file is a valid instance of that file type.

4) If searchOptions is IL_EFS_READ_SEARCH, ilEFSOpen() performs steps 2 and 3. IL_EFS_READ_SEQUENTIAL is recommended for reading a file of unknown type.

If a match is found and openMode is set to IL_EFS_READ or IL_EFS_READ_SEQUENTIAL, ilEFSOpen() checks that the file type found is valid for the file.

pOptions is a value that must be NULL (0); this parameter is reserved for future use.

RETURN VALUE

Upon successful completion, ilEFSOpen() returns an ilEFSFile data structure.

ERRORS

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

EXAMPLE

The following example uses ilEFSOpen() to open an image file for reading.

ilContext context;

char filename[];

ilEFSFile inFile;
.
.
.

inFile = ilEFSOpen (context, argv[1], IL_EFS_READ_SEQUENTIAL,
IL_EFS_READ_SEARCH, (char *)NULL, NULL);

if (!infile)

return (context->error);

AUTHOR

ilEFSOpen() was developed by HP.

Museum

Related Articles