Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 4 - ColorSync Manager Reference for Color Management Modules / Optional CMM-Defined Functions

/

MyCMMUnflattenProfile

Handles the kCMMUnflattenProfile request by creating a uniquely named file in the temporary items folder to store the profile data.

A CMM may respond to the kCMMUnflattenProfile request code, but it is not required to do so. Most CMMs can rely on the default Apple CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMUnflattenProfile function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMUnflattenProfile request code typically responds by calling a CMM-defined function (for example, MyCMMUnflattenProfile).

The MyCMMUnflattenProfile function is a color management module-defined subroutine.

pascal CMError MyCMMUnflattenProfile (
ComponentInstance CMSession,
FSSpec *resultFileSpec,
CMFlattenUPP proc, 
void *refCon); 

CMSession

A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.

resultFileSpec

A pointer to a file specification for the profile file. This is a temporary file specification. You must create this temporary file, which is returned to the calling application or device driver. The calling application or driver is responsible for disposing of the file when finished with it.

proc

A pointer to a function supplied by the calling application or device driver to perform the low-level data transfer. Your MyCMMFlattenProfile function calls this function repeatedly as necessary until all the profile data is transferred.

refCon

A reference constant containing data specified by the calling application program.

function result

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

DISCUSSION

Only in rare circumstances should a custom CMM need to support this request code. The process of unflattening a profile is complex, and the default Apple CMM handles this process adequately for most cases. A custom CMM might respond to this request code if the CMM provides special services such as profile data encryption or compression, for example. Read the rest of this description if your CMM handles this request code.

Your MyCMMUnflattenProfile function must create a file with a unique name in which to store the profile data. (You should create this file in the temporary items folder.) The ColorSync Manager returns the temporary file specification to the calling application or device driver.

To obtain the profile data, your MyCMMUnflattenProfile function calls the MyColorSyncDataTransfer function supplied by the calling application or device driver. Here is the prototype for the MyColorSyncDataTransfer function pointed to by the proc parameter:

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

Before calling the MyColorSyncDataTransfer function, your MyCMMUnflattenProfile function must allocate a buffer to hold the profile data returned to you from the MyColorSyncDataTransfer function in the data parameter.

Your MyCMMUnflattenProfile function communicates with the MyColorSyncDataTransfer function using a command parameter to identify the operation to perform. Your function should call the MyColorSyncDataTransfer function first with the openReadSpool command to direct the MyColorSyncDataTransfer function to begin the process of transferring data. Following this, you should call the MyColorSyncDataTransfer function with the readSpool command as often as necessary until the MyColorSyncDataTransfer function has passed your function all the profile data from the graphics file. After you have received all the profile data, your function should call the MyColorSyncDataTransfer function with the closeSpool command.

Each time you call the MyColorSyncDataTransfer function, you should pass it a pointer to the data buffer you created, the size in bytes of the profile data to return to you in the buffer, and the reference constant passed to you from the calling application.

On return, the MyColorSyncDataTransfer function passes to you the profile data that your function must write to the temporary file that you created for the new profile file. The MyColorSyncDataTransfer function will not always transfer the number of bytes of profile data you requested. Therefore, the MyColorSyncDataTransfer function returns in the size parameter the number of bytes of profile data it actually returned in the data buffer.

The profile file you create is returned to the calling application or device driver in the resultFileSpec parameter. Your MyCMMUnflattenProfile function must identify the profile size and maintain a counter tracking the amount of data transferred to you and the amount of remaining data to determine when to call the MyColorSyncDataTransfer function with the closeSpool command. To determine the profile size, your function can obtain the profile header, which specifies the size.

The calling application or device driver uses the reference constant to pass information to the MyColorSyncDataTransfer function that the function requires to transfer the data.