PSTReadImageHeader(3) Impressario PSTReadImageHeader(3)NAME
PSTReadImageHeader, PSTWriteImageHeader - read/write printing specific
STIFF image header
SYNOPSIS
#include <stdio.h>
#include <printstiff.h>
int PSTReadImageHeader(STStream *st, PSTImageHeader *hd);
int PSTWriteImageHeader(STStream *st, PSTImageHeader *hd,
int last);
DESCRIPTION
These functions are similar to the generic libstiff functions
STReadImageHeader and STWriteImageHeader. They differ only in the amount
of header information. The printing specific image header functions
PSTReadImageHeader and PSTWriteImageHeader use an image header structure
that is a superset of the STImageHeader structure. The printing specific
header contains additional printing specific information such as image
resolution.
Refer to the manual page for STReadImageHeader(3) for information
regarding the role of the image header in a STIFF stream.
PSTReadImageHeader reads the image header information from the stream
specified by st and places the information in the image header structure
specified by hd. st must point to a STIFF stream open for reading.
Following a successful call to PSTReadImageHeader, the function STRead
can be called to read the actual image data. The amount of image data
available can be found in the PSTImageHeader structure. In addition,
following a successful call to PSTReadImageHeader the TIFF tag list read
from the STIFF stream can be queried using the STGetTag function. Note
that PSTReadImageHeader can be used to read a generic STIFF image header.
If the additional information required for the printing specific header
is not found in the stream, default values are placed in the
PSTImageHeader fields for which information was not found in the STIFF
stream as follows:
PSTImageHeader field Default Value
___________________________________________
resUnit PST_RES_UNIT_INCH
xRes 0
yRes 0
thresholding PST_THRESHOLD_NONE
compression PST_COMPRESSION_NONE
dataTime "" (empty string)
hostComputer "" (empty string)
software "" (empty string)
docName "" (empty string)
Page 1
PSTReadImageHeader(3) Impressario PSTReadImageHeader(3)
pageNumbers 0, 0
targetPrinter "" (empty string)
driverOptions "" (empty string)
After all the last image has been read from a STIFF stream, the next call
to PSTReadImageHeader will return -1, and STerrno will be set to STEEOF
(see below).
PSTWriteImageHeader writes a printing specific image header to the STIFF
stream specified by st. Before a call to PSTWriteImageHeader any caller
specific TIFF tags should be added to the output tag list using the
STAddTag function. Following a successful call to PSTWriteImageHeader the
actual image data can be written to the stream using STWrite. The amount
of image data that must be written to the stream is specified in the
PSTImageHeader structure.
Make sure that all fields of the PSTImageHeader structure passed to
PSTWriteImageHeader contain reasonable values; otherwise, garbage will be
written into the STIFF stream.
Note that following a successful call to PSTWriteImageHeader the output
TIFF tag list is cleared. A STIFF stream written using
PSTWriteImageHeader can be read using the generic libstiff image header
reading function STReadImageHeader. The additional information in the
stream will be placed on the tag list and may be queried using the
STGetTag function.
The PSTImageHeader structure is defined as follows.
typedef struct pst_imghdr {
unsigned long width, height; /* Dimensions in dots */
unsigned short bitsPerSample; /* Bits per channel */
unsigned short samplesPerPixel; /* # of color channels */
unsigned long imgbytes; /* Bytes of image data */
STType type; /* Image data type */
STPlane plane; /* Planar configuration */
PSTResUnit resUnit; /* Resolution units */
unsigned long xRes, yRes; /* Resolution, dots/resUnit */
PSTThreshold thresholding; /* Dither mechanism */
PSTCompression compression; /* Compression method */
char *dateTime; /* Image time stamp */
char *hostComputer; /* Computer used */
char *software; /* Software used */
char *docName; /* Document name */
char *targetPrinter; /* Destination printer */
unsigned short pageNumbers[2]; /* Page numbers */
/* [0] = current page # */
/* [1] = total pages */
/* (0 = unknown) */
char *driverOptions; /* Driver options */
} PSTImageHeader;
Page 2
PSTReadImageHeader(3) Impressario PSTReadImageHeader(3)TIFF TAGS USED
The PSTWriteImageHeader function will write the TIFF tags listed below
into the STIFF stream. Any Caller specific tags added using STAddTag(3)
are written in addition to the tags listed. The tags are expressed in
terms of their names in the header file stiff.h. An '*' following a tag
name indicates that this tag is not used in the generic STIFF stream.
STBitsPerSample
STCompression*
STDateTime*
STDocumentName*
STHostComputer*
STImageLength
STImageWidth
STNewSubfileType*
STPageNumber*
STPhotometricInterpretation
STPlanarConfiguration
STResolutionUnit*
STSamplesPerPixel
STSGIPrinting*
STSoftware*
STStripByteCounts
STStripOffsets
STTargetPrinter*
STThresholding*
STXResolution*
STYResolution*
RETURN VALUE
Both PSTReadImageHeader and PSTWriteImageHeader return 0 if execution was
successful. -1 is returned and STerrno is set if an execution error has
occurred.
EXECUTION ERROR CODES
PSTReadImageHeader will fail under the following circumstances.
STEBADTAG Invalid TIFF tag.
STENOMEM Out of memory.
STEREADFROMWRITE Attempt to read from a write stream.
STESYSCALL System call failed.
STENEEDSEEK Operation requires seeking on a stream.
STEEOF End of stream.
PSTWriteImageHeader will fail under the following circumstances.
Page 3
PSTReadImageHeader(3) Impressario PSTReadImageHeader(3)
STEBADTAG Invalid TIFF tag.
STENOMEM Out of memory.
STEWRITETOREAD Attempt to write to a read only stream.
STESYSCALL System call failed.
STENEEDSEEK Operation requires seeking on a stream.
SEE ALSOlibstiff(3), STReadImageHeader(3), STAddTag(3)
Page 4
