Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

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

Profile Searching / Searching for a Profile by Profile Identifier

CMProfileIdentifierListSearch

Searches a list of profile references and returns a list of all references that match a specified profile identifier.

pascal CMError CMProfileIdentifierListSearch (
CMProfileIdentifierPtr ident,
CMProfileRef *profileList,
unsigned long listSize,
unsigned long *matchedCount,
CMProfileRef *matchedList);

ident

A pointer to a profile identifier. The function looks for profile references in profileList that match the profile described by this identifier. For information on how a profile identifier match is determined, see "Profile Identifier Structure" (page 3-64).

profileList

A pointer to a list of profile references to search.

listSize

The number of profile references in profileList.

matchedCount

A pointer to a count of matching profile references. If you set matchedList to NULL, on output matchedCount specifies the number of references in profileList that match ident. The count is typically 0 or 1, but can be higher.

If you do not set matchedList to NULL, on input you set matchedCount to the maximum number of matching references to be returned in matchedList. On output, the value of matchedCount specifies the actual number of matching references returned, which is always equal to or less than the number passed in.

matchedList

A pointer to a list of profile references. If you set matchedList to NULL on input, on output nothing is returned in the parameter, and the actual number of matching references is returned in matchedCount.

If you do not set matchedList to NULL on input, it is treated as a pointer to allocated memory. On output, the allocated memory will contain a list, in no particular order, of profile references that match ident. The number of references in the list is equal to or less than the value you pass in the matchedCount parameter. You must allocate enough memory for matchedList to store the requested number of profile references.

function result

A result code of type CMError. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes. It is not an error condition if the CMProfileIdentifierListSearch function finds no matching profiles. The function returns an error only if a Memory Manager or other low-level system error occurs.

DISCUSSION

When your application or device driver processes an image, it typically keeps a list of profile references for each unique profile or profile identifier it encounters in the image. Each time it encounters an embedded profile identifier, your application first calls the CMProfileIdentifierListSearch function to see if there is already a matching profile reference in the list. Although your list of profile references would normally contain at most one reference that matches the profile identifier, it is possible to have two or more matches. For information on how a profile identifier match is determined, see "Profile Identifier Structure" (page 3-64).

If no matching profile is found in the list, your application calls the CMProfileIdentifierFolderSearch routine (page 3-139) to see if a matching profile can be found in the ColorSyncTM Profiles folder.

To determine the amount of memory needed for the list of profile references that match a profile identifier, your application may want to call CMProfileIdentifierListSearch twice. The first time, on input you set matchedList to NULL and ignore matchedCount. On output, matchedCount specifies the number of matching profiles. You then allocate enough memory to hold that many profile references (or a smaller number if you don't want all the references) and call CMProfileIdentifierListSearch again. This time you set matchedList to a pointer to the allocated memory and set matchedCount to the number of references you wish to obtain. To allocate memory, you use code such as the following:

myProfileRefListPtr = NewPtr(sizeof(CMProfileRef) * matchedCount);

If your application is interested in obtaining only the first profile that matches the specified profile, you need call CMProfileIdentifierListSearch only once. To do so, you just allocate enough memory to store one profile reference, set matchedList to point to that memory (or just set matchedList to point to a local variable), and set matchedCount to 1. On return, if matchedCount still has the value 1, then CMProfileIdentifierListSearch found a matching profile.

For sample code demonstrating how to use CMProfileIdentifierFolderSearch, see "Searching for a Profile That Matches a Profile Identifier" in Advanced Color Imaging on the Mac OS.