Low-level Converter APIs
This section describes the APIs that the Download Manager uses to call the low-level converters that it knows about. The Download Manager knows about the built-in converters (a set of shared libraries built into PrintingLib) as well as converter modules in the “Printing Plug-ins” folder in the Extensions folder. Files containing converter module plug-ins must contain a resource of type ‘PLGN’, ID -8192 with the plug-in type ‘down’ and subtype ‘????’. Details of the PLGN resource are described in Technote 1170: The Printing Plug-ins Manager.
Back to top
Streams Information
Low-level converters don’t know where the data they are converting comes from, nor do they know the ultimate destination of their PostScript output data. Instead, they read the data from input procedures and write data to output procedures. These procedures are packed into structures called streams.
PSStream structure
The low-level converters read and write data from stream structures of type PSStream. PSStream is defined as:
typedef struct PSStream{
PSStreamType type; // The type of Stream, used to pick
// from the union below.
void *reserved; // For use by the stream implementation.
union{
PSReservedStreamType1 null;
PSReservedStreamType2 spool;
PSSerialStream ps;
PSRandomAccessStream file;
}u;
}PSStream;
The PSStreamType is defined as:
typedef enum{
kReservedStreamType1,
kReservedStreamType2,
kPSSerialStream, //For streams that can not be positioned.
kPSRandomAccessStream //For streams that can be positioned.
}PSStreamType;
The PSSerialStream and PSRandomAccessStream are defined as:
typedef struct{
PSOutProc write; // output proc
PSInProc read; // input proc
UInt32 reserved; // reserved
PSPosition pos; // structural info about where we are
// in the PostScript stream
}PSSerialStream;
typedef struct{
PSSerialStream serialStream;
PSGetPosProc getPos;
PSSetPosProc setPos;
PSGetEOFProc getEOF;
}PSRandomAccessStream;
|
The PSRandomAccessStream stream has the same callbacks and data as the PSSerialStream, but it also has functions to get the current stream position, set the current stream position and get the size of the file.
The read and write procedures of the PSSerialStream and PSRandomAccessStream types are used to read data from and write data to the stream. They are declared as follows:
typedef OSStatus (*PSInProc)(PSStream *psStream,
void *data, SInt32 *nBytes);
|
The read field of the PSSerialStream structure contains a function of type PSInProc which is used to read data from the stream. The psStream parameter is a pointer to the stream being read. The data parameter is a pointer to a client-supplied buffer into which the data is read. The caller sets *nBytes to the number of bytes to read into the data buffer. It is up to the caller to ensure that the data buffer it supplies has enough room for *nBytes of data. After the function call, *nBytes contains the number of bytes actually read.
typedef OSStatus (*PSOutProc)(PSStream *psStream,
const void *data, SInt32 nBytes);
|
The write field of the PSSerialStream structure contains a function of type PSOutProc which is used to write data to the stream. The psStream parameter is a pointer to the stream being written to. The data parameter is a pointer to the data to be written to the stream. The nBytes parameter specifies the number of bytes to be written.
The PSInProc routine of the input stream is used by the low-level converter to read and examine the data to be converted to determine if it can handle this data stream. During the psLowPeekConvert and psLowDoConvert calls (described below), the low-level converter calls the PSOutProc routine of the input stream to give time and status to the client. The PSPosition structure is used to pass Document Structuring Conventions data and status information back to the client idleProc.
When actually converting data, a low-level converter is passed an output stream of type kPSSerialStream for it to write the converted data. The converter uses the PSOutProc of the output stream to write its converted data to the output device (or file). It reads data returned from the output device back channel via the PSInProc of the output stream. It writes the data read from the back channel to the PSOutProc of the input stream, allowing the Download Manager to report any status information coming from the back channel.
Note that some output streams have no PSInProc routine (such as a print to file stream). The PSInProc routine in an output stream should be tested for NULL before calling the procedure.
Back to top
Additional functions for random-access streams
Streams of type kPSRandomAccessStream have additional procedures available:
The PSGetPosProc procedure determines the current position of the mark in the stream corresponding to the file (or file-like stream). This position is based on the last data read from the stream, not the underlying file since the data may be buffered. The prototype for this function is:
typedef OSStatus (*PSGetPosProc)(PSStream *psStream,
SInt32 *currentPos);
|
The psStream parameter points to the stream whose position you want to obtain; the value of *currentPos returned is the current stream position.
The position value is zero-based; that is, the value of *currentPos is 0 if the stream position mark is positioned at the beginning of the stream.
The PSSetPosProc procedure sets the position of the stream mark. The next data read from the stream is the first byte after the stream mark.
typedef OSStatus (*PSSetPosProc)(PSStream *psStream,
SInt32 positionMode, SInt32 posOffset);
|
For the PSSetPosProc call, the positionMode is the positioning mode and posOffset is the positioning offset. The positionMode parameter indicates how to position the mark; it must contain one of the following values:
enum{
fsFromStart = 1, //set mark relative to beginning of stream
fsFromLEOF = 2, //set mark relative to logical end-of-stream
fsFromMark = 3 //set mark relative to current mark
};
|
The positionMode parameter works like the Macintosh file system call SetFPos. These supported values of the positionMode constants are defined in the Macintosh header file “Files.h.” These constants let you position the mark relative to either the beginning of the file, the logical end-of-file, or the current mark. You must also pass in posOffset, a byte offset (either positive or negative) from the specified point. If you specify fsFromLEOF, the value in posOffset must be less than or equal to 0.
|
Note:
If a low-level converter uses the PSSetPosProc to reposition the stream to a new position before that of the previous stream position during the call psLowDoConvert, the Download Manager cannot determine the percentage progress of the download and it will report that the percentage progress is unknown for the remaining duration of the download.
|
The PSGetEOFProc procedure is used to determine the size of the stream. Not all streams which can be positioned have a procedure which can determine the size. When using a stream of type kPSRandomAccessStream, it is important for the user of a stream to verify that the PSGetEOFProc procedure pointer is not NULL before calling it.
typedef OSStatus (*PSGetEOFProc)(PSStream *psStream,
SInt32 *streamSize);
|
|
Note:
low-level converters should be prepared to handle input streams that do not allow random access, i.e., are not of type kPSRandomAccessStream. If a given converter cannot handle such a stream, it should properly advertise itself as unable to download such a stream. See the discussion for psLowCanConvert and psLowGetConverterInformation below.
|
One additional comment about the streams used by the Download Manager and the low-level converters is that they each call stream routines as native code, without using CallUniversalProc. In addition to requiring the stream functions to be native code, this also means that these functions must obey CFM-calling conventions, even on 68k machines.
Back to top
Low-level Converting Routines
When a client such as the Desktop Printing software calls the Download Manager routine psCanDownloadFile, the Download Manager uses the first 15 bytes of the file and its OSType to see which low-level converters can potentially handle the download. The Download Manager then calls the psLowCanConvert routine for each of those converters. This gives each of those converters an opportunity to examine the input data and determine if the converter can handle it.
OSStatus psLowCanConvert(PSStream *inputStreamP,
Collection hints, LowConverterInfo *dataInfoP,
Fixed *priority);
|
The *inputStreamP parameter is a pointer to a stream of PSStreamType, kPSRandomAccessStream, or kPSSerialStream. The low-level converter calls the PSInProc of inputStreamP to obtain the data.
hints is a collection passed to the low-level converter for use during its attempt to determine if it can download the file. It may contain information about the “job” being downloaded that is useful for the low-level converter. The low-level converter should not add or change any hints in the hints collection during the psLowCanConvert call since other low-level converters might be affected by such changes.
dataInfoP is a pointer to a LowConverterInfo structure. It is used by the low-level converter to help determine if the data/file is a type that it can handle.
typedef struct LowConverterInfo{
UInt32 version;
OSType type;
}LowConverterInfo;
|
The version field of the LowConverterInfo structure is 1 for the first version of the Download Manager. The type field is the OSType of the data supplied to the low-level converter.
*priority is a fixed number filled in by the psLowCanConvert call. Values greater than zero indicate that the converter can handle the stream. The larger the number, the more suitable the converter is for the data. Currently a value of 10 (0x000A0000 Fixed) indicates the converter is the best converter possible for the given data. Since the Download Manager simply looks for the ’best” result, a new converter could advertise itself as having a larger value to become the favored converter for a given type of data. (Remember that Nigel’s amplifier can be set to 11.)
|
Note:
The low-level converters in the “Printing Plug-ins” folder with a given priority are chosen over a converter that is built into PrintingLib which claims the same priority. This allows an external converter in the Printing Plug-in’s folder to override a built-in converter.
|
|
Note:
It is unfortunate that for some downloads we don’t always know about the output device when psCanDownloadFile is called. For example a JPEG converter could always download non-progressive JPEG data to a Level 2 printer, even if QuickTime isn’t available on the host. Since we might not know the PostScript level of the output device, we don’t know if we need QuickTime. If the client does know the printer is a Level 2 printer, specifying that would let the low-level converter know it doesn’t need QuickTime. The best we can do with this design is for the client to supply in the hints collection the best information it has about the output device and let the low-level converter decide what it can do based on that information plus the input stream data.
|
Once the Download Manager establishes the best converter for the job (i.e., the one returning the highest priority), the psCanDownloadFile routine returns and if the file is downloadable, the Download Manager client calls the Download Manager routine psDownloadFile to download the file.
|
Note:
low-level converters should be prepared to handle input streams that do not allow random access, i.e., are not of type kPSRandomAccessStream. If a given converter cannot handle such a stream, it should return a priority of 0 if psLowCanConvert is called with a different stream type.
|
Back to top
Getting Information For A Client
When a Download Manager client calls the Download Manager routine psGetDownloadDocumentInfo, the Download Manager asks the low-level converter to obtain the document information by calling the low-level converter’s psLowGetStreamInfo routine.
OSStatus psLowGetStreamInfo(PSStream *inputStreamP,
Collection hints, DownloadDocumentInfo *downloadDocInfoP);
|
*inputStreamP represents the stream of data to gather information from. The low-level converter calls the PSInProc of inputStreamP to obtain the data.
hints is a collection passed into the low-level converter for its use during the information gathering. It may contain information about the “job” being downloaded that is useful for the low-level converter during this phase. During a call to psLowGetStreamInfo, a low-level converter can add or change hints in the hints collection. Collection tag values used by LaserWriter 8/PrintingLib are reserved but can be used by a low-level converter for their normal, intended purpose.
|
Note:
If a converter wants to have private hints, it should use the collection tag ‘APPL’ with a collection ID value identical to its assigned application creator. This ensures that private hints will not collide with other software’s hints.
|
The updated hints collection returned from psLowGetStreamInfo may or may not be passed by the Download Manager and its clients to the other low-level converter calls psLowPeekConvert, psLowAddConverterQueries, and psLowDoConvert (see the description of psGetDownloadDocumentInfo in Section 1). A low-level converter should not require any data it adds to the hints collection in the psLowGetStreamInfo routine being available during any other low-level converter call.
*downloadDocInfoP is a pointer to a DownloadDocumentInfo structure (described above in Section 1) to be filled in by the low-level converter. This structure is initialized by the Download Manager to correspond to unknown values for each field. If the low-level converter does not know the information corresponding to a given field, it should not fill in that field.
Back to top
Peeking at the Data
When a Download Manager client calls the Download Manager routines psDownloadFile or psDownloadStream, the Download Manager determines if it can allow the low-level converter the opportunity to peek at the data before doing the conversion. If the stream is of a type that can be repositioned (i.e., type kPSRandomAccessStream), the Download Manager calls the psLowPeekConvert routine of the low-level converter. With a stream that cannot be repositioned, the act of peeking would prevent the stream from being converted.
|
Note:
If the client adds the hint kHintDownloaderPeekTag with a value of false, the Download Manager will not call psLowPeekConvert regardless of whether the stream supports peeking.
|
OSStatus psLowPeekConvert(PSStream *inputStreamP,
Collection hints);
|
This routine is called by the Download Manager to allow the low-level converter an opportunity to look at the data to be downloaded and thereby collect useful information. Such information might be collected to provide information back to the Download Manager for reporting to the Download Manager client (such as fonts used in a document, etc). Other information might be collected by the low-level converter for passing back to itself when it is later asked to “convert” and download the document with the psLowDoConvert call (described in the section Doing the Conversion below). For example, a PostScript converter might read DSC comments to determine what fonts the document requires as part of the download.
*inputStreamP represents the stream of data to peek at. The low-level converter calls the PSInProc of inputStreamP to obtain the data.
hints is a collection passed into the low-level converter for its use during peeking. It may contain information about the “job” being downloaded that is useful for the low-level converter during the peek phase. During a call to psLowPeekConvert, a low-level converter can add or change hints in the hints collection. Collection tag values used by LaserWriter 8/PrintingLib are reserved but can be used by a low-level converter for their normal, intended purpose.
|
Note:
If a converter wants to have private hints, it should use the collection tag ‘APPL’ with a collection ID value identical to their assigned application creator. This ensures that private hints will not collide with other software’s hints.
|
The updated hints collection returned from psLowPeekConvert is passed by the Download Manager to the low-level converter calls psLowAddConverterQueries and psLowDoConvert (described in the sections Queries and Doing the Conversion respectively). By adding private hints to the collection during the peek phase, a low-level converter can pass itself this information when the Download Manager calls the psLowAddConverterQueries and psLowDoConvert routines.
Examples of data put into the hints during the peek phase by a low-level converter might be:
- Font requirement data based on %%DocumentNeededResources comments in a PS file
- DSC information such as “user”, “pages”, “creator”, etc.
- Information about the procedure sets required, such as those required by a PICT converter
- Bounding Box information for handling EPS data
While a low-level converter should always be prepared to handle the fact that a peek pass may not be made, it may still find it useful to peek at the data when it is given the chance to do so. This means that a low-level converter should be prepared to operate without data it would normally collect during a possible psLowPeekConvert call.
|
Note:
While a low-level converter is required to implement a psLowPeekConvert routine, the implemented routine can simply return without doing any examination of the data stream.
|
Back to top
Queries
When a client makes a call to psDownloadFile, the Download Manager is responsible for querying the printer and providing the results from the queries to the low-level converter. Prior to any queries performed by the Download Manager, the low-level converter gets a chance to add its queries to the set of queries which the Download Manager will make. A low-level converter can add any or all of the queries currently available through PSUtilsLib.The low-level converter does not do the query itself, but instead the Download Manager calls the routine psLowAddConverterQueries supplied by a low-level converter to determine the queries the low-level converter needs.
OSStatus psLowAddConverterQueries(Collection hints,
Collection query);
|
This routine is passed the hints collection for the current job. If the low-level converter routine psLowPeekConvert was called, the hints collection as returned from that call is passed to psLowAddConverterQueries. The psLowAddConverterQueries routine is also passed a query collection so that the low-level converter can add query hints for use by the Download Manager. The low-level converter can use the hints collection to decide whether to add any queries to the query collection. When the psLowAddConverterQueries routine returns, the Download Manager uses the data in the query collection to query the target output device. The Download Manager copies the results of the queries into the hints collection that is used for the call to psLowDoConvert (see the section Doing the Conversion below).
Basic Queries
Most queries fall into the category of basic queries. Examples of these queries are the PostScript language level, PostScript version information, color or black and white device knowledge, and so forth. Such queries are generated by adding the appropriate hints to the query collection, with default values chosen by the converter for its own conservative handling approach. For example, to cause the Download Manager to query for the PostScript language level, the following code is used:
kHintLanguageLevelVar langlevel = UnknownLevel;
err = AddCollectionItem(queryCollection, kHintLanguageLevelTag,
kHintLanguageLevelId, sizeof(langlevel), &langlevel);
|
Note here that the default value used is UnknownLevel so that, if the query is not done (see the section Using Query Results below), getting this collection item later reflects this default.
Font Queries
The Download Manager can query for a specific list of fonts or obtain the entire list of fonts available in the target output device. Both of these font queries are specified with the hint kHintIncludeFontsTag with the ID value kHintIncludeFontsId. The data contained in this hint determines the type of query. The data is a PSFontHandling structure, defined as:
typedef struct {
long tag;
unsigned char name[1]; //packed array of names,
//length 0 indicates end of list
}PSFontHandling;
|
and the following constants are defined:
enum{
kIncludeNoFontsOtherThan,
kIncludeAllFontsBut
};
|
If the tag field of the PSFontHandling structure is kIncludeAllFontsBut, the query is for the complete list of fonts (the equivalent of the *?FontList query from the PPD file). For this flavor of the font query, there should be one name specified whose length is zero. Upon return of the query, the name field will be a packed array of Pascal strings corresponding to the fonts built into the output device. This list of names will be terminated with a Pascal string whose length is zero.
If the tag field of the PSFontHandling structure is kIncludeNoFontsOtherThan, the query is for a specified list of fonts (the equivalent of the *?FontQuery query from the PPD file). For this flavor of the font query, the list of fonts to query for should be in the name field of the structure. The list is a packed array of Pascal strings and is terminated with a Pascal string with a zero-length byte. After the query, the name field is a packed array of Pascal strings corresponding to the fonts from the query list which were not available, i.e., the fonts available in the output device are removed from the list. Again, this list of names is terminated with a Pascal string with a zero-length byte.
|
Note:
It is quite possible that a low-level converter might request a query with a tag of kIncludeAllFontsBut and the query result may contain a query with a tag of kIncludeNoFontsOtherThan or vice versa.
|
Communication Channel Queries
A second category of special queries is that for the communication channel characteristics. Most low-level converters will generate different output data if the communication pathway to the target output device supports binary data. There are two hints used to query for whether the output device supports binary data and both should be consulted.
The first is the hint with tag value kHintEighthBitTag and ID value kHintEighthBitId. If the hint value is true, the output stream supports the data range 0x80-0xFF inclusive. If the value is false, the PostScript output stream generated by the low-level converter should not contain these byte values.
The second is the hint with the tag value kHintTransparentChannelTag and ID value kHintTransparentChannelId. If the hint value is true, the output stream supports the data range 0x00-0x1F inclusive. If the value is false, the PostScript output stream generated by the low-level converter should not contain these byte values.
|
 (Disk 1).iso/pc/technical documentation/macintosh technotes and q&as/technotes/tn/images/tn11691.gif)
 (Disk 1).iso/pc/technical documentation/macintosh technotes and q&as/technotes/tn/images/tn11692.gif)
 (Disk 1).iso/pc/technical documentation/macintosh technotes and q&as/technotes/tn/images/acrobatsmall.gif){kind=small}
Acrobat version of this Note (147K). (Disk 1).iso/pc/technical documentation/macintosh technotes and q&as/technotes/tn/images/bluebook.gif){kind=small}
Binhexed Routine Descriptor Lib (196K).