Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 3 - ColorSync Manager Reference for Applications and Device Drivers / ColorSync Manager Functions

Application-Defined Functions for the ColorSync Manager /

MyColorSyncDataTransfer

Application-defined function that transfers profile data from the format for embedded profiles to disk file format or vice versa. Used by PostScript functions to transfer data from a profile to text format usable by a PostScript driver.

This application-supplied function must conform to the following declaration, although the function name is arbitrary:

pascal OSErr MyColorSyncDataTransfer (
long command,
long *size,
void *data,
void *refCon);

command

The command with which the MyColorSyncDataTransfer function is called. This command specifies the operation the function is to perform.

size

A pointer to a size value. On input, the size in bytes of the data to transfer. On output, the size of the data actually transferred.

data

A pointer to the buffer supplied by the ColorSync Manager to use for the data transfer.

refCon

A reference constant that holds the application data passed in from the CMFlattenProfile function, the CMUnflattenProfile function, or the CMGetPS2ColorSpace, CMGetPS2ColorRenderingIntent, or CMGetPS2ColorRendering functions. Each time the CMM calls your MyColorSyncDataTransfer function, it passes this data to the function.

function result

A result code of type OSErr. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes.

DISCUSSION

Your MyColorSyncDataTransfer function is called to flatten and unflatten profiles or to transfer PostScript-related data from a profile to the PostScript format to send to an application or device driver.

The ColorSync dispatcher and the CMM communicate with the MyColorSyncDataTransfer function using the command parameter to identify the operation to perform. To read and write profile data, your function must the support the following commands: openReadSpool, openWriteSpool, readSpool, writeSpool, and closeSpool.

You determine the behavior of your MyColorSyncDataTransfer function. This section describes how your function might handle the flattening and unflattening processes.

FLATTENING A PROFILE

The ColorSync Manager calls the specified profile's preferred CMM when an application calls the CMFlattenProfile function to transfer profile data embedded in a graphics document.

The ColorSync Manager determines if the CMM supports the CMFlattenProfile function. If so, the ColorSync Manager dispatches the CMFlattenProfile function to the CMM. If not, ColorSync calls the default Apple CMM, dispatching the CMFlattenProfile function to it.

The CMM communicates with the MyColorSyncDataTransfer function using a command parameter to identify the operation to perform. The CMM calls your function as often as necessary, passing to it on each call any data transferred to the CMM from the CMFlattenProfile function's refCon parameter.

The ColorSync Manager calls your function with the following sequence of commands: openWriteSpool, writeSpool, and closeSpool. Here is how you should handle these commands:

• When the CMM calls your function with the openWriteSpool command, you should perform any initialization required to write profile data you receive from the CMM to a buffer or file.
• The CMM will call your function with the writeSpool command as many times as necessary to transfer all the profile data to you. Each time you are called, you should receive the data and write it to your buffer or file, returning in the size parameter the number of bytes of data you actually accepted.
• When the CMM calls your function with the closeSpool command, you should perform any required cleanup processes.

As part of this process, your function can embed the profile data in a graphics document, for example, a PICT file or a TIFF file. For example, your MyColorSyncDataTransfer function can call the QuickDraw PicComment function to embed the flattened profile in a picture.

UNFLATTENING A PROFILE

When an application calls the CMUnflattenProfile function to transfer a profile that was embedded in a graphics document to an independent disk file, the ColorSync dispatcher calls your MyColorSyncDataTransfer function to obtain the preferred CMM of the profile to flatten. The ColorSync Manager calls your function with the following sequence of commands: openReadSpool, readSpool, closeSpool. Here is how you should handle these commands:

• When the CMM calls your function with the openReadSpool command, you should perform any initialization required to read from the embedded profile format.
• The CMM will call your function with the readSpool command as many times as necessary, directing your function to extract the profile data from the embedded format in the image file and return it to the CMM in the data buffer. The CMM passes in the size parameter the number of bytes of data you should return. Each time your function is called, it should read and return the data, also returning in the size parameter the number of bytes of data you actually returned to the CMM.
• When the CMM calls your function with the closeSpool command, you should perform any required cleanup processes.

The preferred CMM is stored in the profile header's CMMType field. The MyColorSyncDataTransfer function must be able to buffer at least 8 bytes of data to hold the CMMType field value.

The ColorSync Manager determines if the CMM supports the CMUnflattenProfile function. If so, the ColorSync Manager calls the preferred CMM to dispatch the CMUnflattenProfile function to it. If not, the ColorSync Manager calls the default Apple CMM to dispatch the CMUnflattenProfile function to it.

The CMM calls the MyColorSyncDataTransfer function, supplied by the calling application, to unflatten the profile data and write it to a disk file. The CMM calls the function as often as necessary, passing to it on each call any data transferred to the CMM from the CMUnflattenProfile function's refCon parameter.