Legacy Document

Inside Macintosh: Advanced Color Imaging on the Mac OS /

Chapter 4 - Developing ColorSync-Supportive Applications / Developing Your ColorSync-Supportive Application

Opening a Profile and Obtaining a Reference to It

To open a profile and obtain a reference to it, you call the CMOpenProfile function. (The CMCopyProfile, CWNewLinkProfile, and CMNewProfile functions also return profile references.) To identify a profile that is file based, memory based, or accessed through a procedure, you must give its location.

The ColorSync Manager defines the following data type that you use to tell the profile's location:

struct CMProfileLocation {
   short     locType;/* specifies the location type */
   CMProfLoc u;      /* structure for specified type */
};

The CMProfileLocation data type contains a field called CMProfLoc for which you specify a value using the following union defined by the ColorSync Manager:

union CMProfLoc {
   CMFileLocation    fileLoc; /* disk location structure */
   CMHandleLocation  handleLoc;/* handle location structure */
   CMPtrLocation     ptrLoc;  /* pointer location structure */
   CMProcedureLocation procLoc;/* procedure access structure */
};

The value you specify in a CMProfLoc structure specifies the actual location of the profile. In most cases, a ColorSync profile is stored in a disk file, and you use the union to give the file specification. However, a profile can also be located in memory or in an arbitrary location (such as a resource) that is accessed through a procedure provided by your application. In addition, you can specify that a profile be temporary, meaning that it will not persist in memory after your application uses it for a color session.

Depending on the location of the profile, your application supplies a variable of type

• CMFileLocation to provide a file specification for a profile stored in a disk file
• CMHandleLocation to specify a handle for a profile stored in relocatable memory
• CMPtrLocation to specify a pointer to a profile stored in nonrelocatable memory
• CMProcedureLocation to specify a profile accessed through a procedure provided by you

For more information on profile access, see "Accessing a Resource-Based Profile With a Procedure" (page 4-57).

To identify the data type in the u field of the CMProfileLocation structure, you assign to the CMProfileLocation.locType field one of the constants or numeric equivalents defined by the following enumeration:

enum {
   cmNoProfileBase   = 0,  /* the profile is temporary */
   cmFileBasedProfile= 1,  /* file-based profile */
   cmHandleBasedProfile= 2,/* handle-based profile */
   cmPtrBasedProfile = 3   /* pointer-based profile */
   cmProcedureBasedProfile= 4/* procedure-based profile */
};

For example, for a file-based profile, the u field would hold a file specification and the locType field would hold the constant cmFileBasedProfile. Your application passes a CMProfileLocation structure when it calls the CMOpenProfile function and the function returns a reference to the specified profile.

Listing 4-2 shows an application-defined function, MyOpenProfileFSSpec, that assigns the file specification for the profile file to the profLoc union and identifies the location type as file based. Given the file specification, MyOpenProfileFSSpec then calls the CMOpenProfile function, passing to it the profile's file specification and receiving in return a reference to the profile.

Listing 4-2 Opening a reference to a file-based profile

CMError MyOpenProfileFSSpec (FSSpec spec, CMProfileRef *prof)
{
   CMError           cmErr;
   CMProfileLocation profLoc;
   
   profLoc.locType = cmFileBasedProfile;
   profLoc.u.file.spec = spec;

   cmErr = CMOpenProfile(prof, &profLoc);

   return cmErr;
}

The ColorSync Manager keeps an internal reference count for each profile reference returned from a call to the CMOpenProfile, CMCopyProfile, CMNewProfile, or CWNewLinkProfile functions. Calling the CMCloneProfileRef function increments the count; calling the CMCloseProfile function decrements it. When the count reaches 0, the ColorSync Manager releases all private memory, files, or resources allocated in association with that profile. The profile remains open as long as the reference count is greater than 0, indicating that at least one task retains a reference to the profile. You can determine the current reference count for a profile reference by calling the CMGetProfileRefCount function.

When your application passes a copy of a profile reference to an independent task, whether synchronous or asynchronous, it should call CMCloneProfileRef to increment the reference count. Both the called task and the caller should call CMCloseProfile when finished with the profile reference.

Note

You call CMCloneProfileRef after copying a profile reference but not after duplicating an entire profile (as with the CMCopyProfile function).

When your application passes a copy of a profile reference internally, it may not need to call CMCloneProfileRef, as long as the application calls CMCloseProfile once for the profile.

IMPORTANT

In your application, make sure that CMCloseProfile is called once for each time a profile reference is created or cloned. Otherwise, the private memory and resources associated with the profile reference may not be properly freed, or a task may attempt to use a profile reference that is no longer valid.