PSTReadImageHeader(3)
PSTReadImageHeader, PSTWriteImageHeader - read/write printing specific STIFF image header
Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.
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) 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; 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. 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 ALSO libstiff(3), STReadImageHeader(3), STAddTag(3)