NAME

ilReadFileTags() − read TIFF file tags associated with a file image

SYNOPSIS

ilPtr
ilReadFileTags (

ilFileImage fileImage,

int nTags,

short *pTagNumbers,

ilFileTag **ppTags,

unsigned long mustBeZero);

DESCRIPTION

ilReadFileTags() returns a pointer to an array of ilFileTag structures for an element in one ilFileImage structure.  The returned ilPtr points to a block allocated by malloc().  When finished reading the tag data, the application should free the block by passing the returned ilPtr to free(). 

ilReadFileTags() 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(). 

fileImage identifies a file image descriptor returned by ilListFileImages(). 

nTags identifies the number of tags in the array of *pTagNumbers. 

*pTagNumbers identifies an array of tag numbers that correspond to values specified in the TIFF v5.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. 

**ppTags receives a pointer to an array of nTags pointers to ilFileTag structures, which is allocated using malloc().  The pointers are in the same order as defined by pTagNumbers.  Each pointer in the array is NULL if the corresponding tag was not found, or else it points to an ilFileTag structure contains the following:

number the tag number; the same as the corresponding entry in *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. 

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

RETURN VALUE

Upon successful completion, ilReadFileTags() returns a pointer to an allocated block of memory; the application should use free() to deallocate this block when it is no longer needed. If an error occurs, the function returns NULL. 

ERRORS

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

EXAMPLE

The following example reads the tags associated with the file image image. 

ilContext context;

ilFileImage image;

int nTags;

short tagNumbers[];

ilFileTag *pTags;

ilPtr tagData;
.
.
.

if (!(tagData = ilReadFileTags(image, ntags, tagNumbers, &pTags,0)
return(context->error);
.
.
.

free(tagData);

AUTHOR

ilReadFileTags() was developed by HP. 

SEE ALSO

ilListFileImages(3X), free(3X), malloc(3X). 

Using the Image Developer’s Kit.

Hewlett-Packard Company  —  Image Library: February, 1995