Carbon


CMMUnflattenProfile

Header: CMMComponent.h Carbon status: Unsupported

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

CMError CMMUnflattenProfile (
    CMMComponentInst cmm, 
    FSSpec *resultFileSpec, 
    CMFlattenUPP proc, 
    void *refCon
);
Parameter descriptions
cmm

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 CMMFlattenProfile 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.

DISCUSSION

A CMM may respond to the kCMMUnflattenProfile request code, but it is not required to do so. Most CMMs can rely on the default 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, CMMUnflattenProfile).

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 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 CMMUnflattenProfile 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 CMMUnflattenProfile function calls the CMFlattenProcPtr function supplied by the calling application or device driver.

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

Your CMMUnflattenProfile function communicates with the CMFlattenProcPtr function using a command parameter to identify the operation to perform. Your function should call the CMFlattenProcPtr function first with the cmOpenReadSpool command to direct the CMFlattenProcPtr function to begin the process of transferring data. Following this, you should call the CMFlattenProcPtr function with the cmReadSpool command as often as necessary until the CMFlattenProcPtr 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 CMFlattenProcPtr function with the cmCloseSpool command.

Each time you call the CMFlattenProcPtr 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 CMFlattenProcPtr 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 CMFlattenProcPtr function will not always transfer the number of bytes of profile data you requested. Therefore, the CMFlattenProcPtr 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 CMMUnflattenProfile 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 CMFlattenProcPtr function with the cmCloseSpool 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 to the CMFlattenProcPtr function information the CMFlattenProcPtr function requires to transfer the data.

VERSION NOTES

Starting with ColorSync version 2.5, the ColorSync Manager calls the function provided by the calling program directly, without going through the preferred, or any, CMM. Your CMM only needs to handle the kCMMUnflattenProfile request code for versions of ColorSync prior to version 2.5.

CARBON NOTES

CMMUnflattenProfile is an API to CMMs. Application developers should avoid calling CMMs directly, since they may or may not support a given API.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)