IL_EFS_TIFF_READ_TAGS(3X)

NAME

IL_EFS_TIFF_READ_TAGS − read TIFF tags associated with the current page (image) in a TIFF file opened via ilEFSOpen().

SYNOPSIS

ilEFSFileTypeInfo fileTypeInfo;

ilBool
(*fileTypeInfo.Escape) (

ilEFSFileType fileType,
IL_EFS_TIFF_READ_TAGS,

ilEFSTIFFReadTagsInfo
*pReadTagsInfo);

DESCRIPTION

IL_EFS_TIFF_READ_TAGS is a parameter for the (*fileTypeInfo.Escape) function for the TIFF file type. It allows you to read the values of tags associated with an image in a TIFF file and is intended for use with the Image library’s Extensible File Support (EFS) features.

(*fileTypeInfo.Escape)( ..., IL_EFS_TIFF_READ_TAGS, ... ) sets the elements of an array of pointers to point to ilFileTag structures for the current page (image), which is the next page to be read in a TIFF file. If no more pages are available from the file, an IL_ERROR_EFS_EOF error is declared. The ilPtr returned in pReadTagsInfo->tagData points to a block allocated by malloc(). When finished reading the tag data, the application should free the block by passing
pReadTagsInfo->tagData to free().

(*fileTypeInfo.Escape)( ..., IL_EFS_TIFF_READ_TAGS, ... ) can be used to read the values of tags associated with an image in a TIFF file. These tags can include user-defined values written with ilWriteFileImage() or
(*fileTypeInfo.Escape)( ..., IL_EFS_TIFF_WRITE_IMAGE_WITH_TAGS, ... ).

fileType is the type of the file.

pReadTagsInfo->file
is a file opened with an openMode of IL_EFS_READ or IL_EFS_READ_SEQUENTIAL.

pReadTagsInfo->nTags
identifies the number of tags in the array of pReadTagsInfo->pTagNumbers.

pReadTagsInfo->pTagNumbers
identifies an array of tag numbers that correspond to values specified in the TIFF v5.0 or v6.0 specification, or to private tag numbers. The ilfile.h include file defines some, but not all, of the tag numbers that may be read.

pReadTagsInfo->ppTags
identifies an array of pReadTagsInfo->nTags pointers to ilFileTag structures. The pointers are in the same order as defined by pReadTagsInfo->pTagNumbers. Each pointer in the array is set to NULL if the corresponding tag was not found, or else it is set to point to an ilFileTag structure that contains the following:

number the tag number; the same as the corresponding entry in
pReadTagsInfo->pTagNumbers.

type the data type of the value for the tag. The data types are:

IL_TAG_BYTE
each item is a byte.

IL_TAG_ASCII
each item is an ASCII character; the last item is a NULL (0).

IL_TAG_SHORT
each item is a short.

IL_TAG_LONG
each item is a long.

IL_TAG_RATIONAL
each item is two longs, representing the numerator and denominator of a fraction.

nItems the number of items for this tag value pItems points to a list of nItems items which give the value for the tag, depending on the data type described in type.

pReadTagsInfo->mustBeZero
identifies a value that must be zero; this parameter is reserved for future use.

pReadTagsInfo->tagData
receives a pointer to an allocated block of memory; the application should use free() to deallocate the block when it is no longer needed.

RETURN VALUE

Upon successful completion, (*fileTypeInfo.Escape)( ..., IL_EFS_TIFF_READ_TAGS, ... ) returns TRUE (a non-zero value). If an error occurs, the function returns FALSE (0).

ERRORS

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

EXAMPLE

The following example reads the TIFF tags associated with the current page in the file file if it is a TIFF file.

ilContext context;

ilEFSFile file;

ilEFSFileInfo fileInfo;

ilEFSFileTypeInfo fileTypeInfo;

short tagNumbers[] = { ... };

#define N_TAGS (sizeof(tagNumbers)/sizeof(short))

ilFileTag *pTags[N_TAGS];

ilEFSTIFFReadFileInfo
readFileInfo;

.
.
.

file = ilEFSOpen(context, ...);

ilEFSGetFileInfo(file, &fileInfo);

ilEFSGetFileTypeInfo(fileInfo.fileType, &fileTypeInfo);

if (strcmp(fileTypeInfo.name, "TIFF") == 0)

/* Here if fileTypeInfo.name equals "TIFF". */
if (fileTypeInfo.Escape != NULL) {

/* Here if escape function present. */
readFileInfo.file = file;
readFileInfo.nTags = N_TAGS;
readFileInfo.pTagNumbers = tagNumbers;
readFileInfo.ppTags = pTags;

if (!(*fileTypeInfo.Escape)(fileInfo.fileType,
IL_EFS_TIFF_READ_TAGS,
&readFileInfo))

return context->error;

.
.
.

free(readFileInfo.tagData);

}

AUTHOR

(*fileTypeInfo.Escape)() was developed by HP.

Museum

Related Articles