PATHMac OS 8 and 9 Developer Documentation > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Profile Searching

This section describes the ColorSync functions you use to search for profiles.

IMPORTANT

Your application should use one of the ColorSync search functions described here to search for a profile file, even if you are only looking for one file. Do not search for a profile file by obtaining the location of the profiles folder and searching for the file directly.


Searching for Profiles With ColorSync 2.5

Starting with version 2.5, ColorSync provides a profile cache, described in The Profile Cache and Optimized Searching , for keeping track of profile files. A flexible new routine, CMIterateColorSyncFolder , takes advantage of the profile cache to provide truly optimized searching and quick access to profile information. Your application can quickly examine all the profile files in the ColorSync Profiles folder to find those that match a desired criteria.

For additional information on profile searching, see Searching for Profiles Prior to ColorSync 2.5 and Searching for a Profile by Profile Identifier .


CMIterateColorSyncFolder

New in ColorSync 2.5

Iterates over the available profiles.

pascal CMError CMIterateColorSyncFolder (
                     CMProfileIterateUPP proc,
                     unsigned long * seed,
                     unsigned long * count,
                     void * refCon);
proc
A universal procedure pointer of type CMProfileIterateUPP , which is described in CMProfileIterateProcPtr . If you do not wish to receive callbacks, pass NULL for this parameter. Otherwise, pass a pointer to your callback routine.
seed
A pointer to a value of type long . The first time you call CMIterateColorSyncFolder , you typically set the value to 0. In subsequent calls, you set the value to the seed value obtained from the previous call. ColorSync uses the value in determining whether to call your callback routine, as described in the discussion for this function. On return, the value is the current seed for the profile cache (unless you pass NULL , as described in the discussion).
count
A pointer to a value of type long . On return, the value is the number of available profiles. CMIterateColorSyncFolder provides the number of profiles even when no iteration occurs (unless you pass NULL , as described in the discussion below). To determine the count alone, without iteration, call CMIterateColorSyncFolder and pass a value of NULL for all parameters except count .
refCon
An untyped pointer to arbitrary data supplied by your application. CMIterateColorSyncFolder passes this data to your callback routine. If you pass NULL for the refCon parameter, CMIterateColorSyncFolder passes NULL to your callback routine.
function result
A result code of type CMError . If your callback function returns an error, CMIterateColorSyncFolder stops iterating and returns the error value to its caller (presumably your code). For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Starting with ColorSync version 2.5, when your application needs information about the profiles currently available in the ColorSync Profiles folder, it can call the CMIterateColorSyncFolder routine, which in turn calls your callback routine once for each profile.

Note

Starting with version 2.5, the name and location of the profile folder changed. In addition, the folder can now contain profiles within nested folders, as well as aliases to profiles or aliases to folders containing profiles. There are limits on the nesting of folders and aliases. For details, see Profile Search Locations .

Even though there may be many profiles available, CMIterateColorSyncFolder can take advantage of ColorSync's profile cache to return profile information quickly, and (if the cache is valid) without having to open any profiles. For each profile, CMIterateColorSyncFolder supplies your routine with the profile header, script code, name, and location, in a structure of type CMProfileIterateData . As a result, your routine may be able to perform its function, such as building a list of profiles to display in a pop-up menu, without further effort (such as opening each file-based profile).

IMPORTANT

Only 2.x profiles are included in the profile search result.

Before calling CMIterateColorSyncFolder for the first time, you typically set seed to 0. ColorSync compares 0 to its current seed for the profile cache. It isn't likely they will match--the odds are roughly one in two billion against it. If the values don't match, the routine iterates through all the profiles in the cache, calling your callback routine once for each profile. CMIterateColorSyncFolder then returns the actual seed value in seed (unless you passed NULL for that parameter).

If you pass the returned seed value in a subsequent call, and if there has been no change in the available profiles, the passed seed will match the stored cache seed and no iteration will take place.

Note that you can pass a NULL pointer for the seed parameter without harm. The result is the same as if you passed a pointer to 0, in that the function iterates through the available profiles, calling your callback routine once for each profile. However, the function doesn't return a seed value, since you haven't passed a valid pointer.

You can force ColorSync to call your callback routine (if any profiles are available) by passing a NULL pointer or by passing 0 for the seed value. But suppose you have an operation, such as building a pop-up menu, that you only want to perform if the available profiles have changed. In that case, you pass the seed value from a previous call to CMIterateColorSyncFolder . If the profile folder has not changed, ColorSync will not call your callback routine.

Note that if there are no profiles available, ColorSync does not call your callback routine.

Note

You can safely pass NULL for any or all of the parameters to the CMIterateColorSyncFolder function. If you pass NULL for all of the parameters, calling the function merely forces rebuilding of the profile cache, if necessary.

For sample code demonstrating how to use CMIterateColorSyncFolder , see Performing Optimized Profile Searching .


Searching for Profiles Prior to ColorSync 2.5

Not Recommended in ColorSync 2.5

This section describes the functions you use to search for profiles with versions of ColorSync prior to version 2.5. These functions are not recommended with version 2.5--see Searching for Profiles With ColorSync 2.5 instead.

The functions described here allow your application to search for profile files within the ColorSync Profiles folder based on certain criteria, and to obtain references to the found profiles and their file specifications.

Note

Starting with version 2.5, the name and location of the profile folder changed, as described in Profile Search Locations .

Code that uses these functions still works in version 2.5, but does not take full advantage of ColorSync's profile cache and optimized searching, which is described in Searching for Profiles With ColorSync 2.5 .

For additional information on profile searching, see Searching for a Profile by Profile Identifier .

IMPORTANT

Only 2.x profiles are included in the profile search result.


CMNewProfileSearch

Not Recommended in ColorSync 2.5

Searches the ColorSync Profiles folder and returns a list of 2.x profiles that match the search specification.

pascal CMError CMNewProfileSearch (
                     CMSearchRecord *searchSpec,
                     void *refCon,
                     unsigned long *count,
                     CMProfileSearchRef *searchResult);
searchSpec
A pointer to a search specification. For a description of the information you can provide in a search record of type CMSearchRecord to define the search, see CMSearchRecord .
refCon
An untyped pointer to arbitrary data supplied by your application. CMNewProfileSearch passes this data to your filter routine. For a description of the filter routine, see the function MyCMProfileFilterProc.
count
A pointer to a profile count. On output, a one-based count of profiles matching the search specification.
searchResult
A pointer to a search result reference. On output, a reference to the profile search result list. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The CMNewProfileSearch function sets up and defines a new search identifying through the search record the elements that a profile must contain to qualify for inclusion in the search result list. The function searches the ColorSync profiles folder for version 2.x profiles that meet the criteria and returns a list of these profiles in an internal private data structure whose reference is returned to you in the searchResult parameter. For a complete description of where the function searches for profiles, see Profile Search Locations .

You must provide a search record of type CMSearchRecord identifying the search criteria. You specify which fields of the search record to use for any given search through a search bit mask whose value you set in the search record's searchMask field.

Among the information you can provide in the search record is a pointer to a filter function to use to eliminate profiles from the search based on additional criteria not defined by the search record. The search result reference is passed to the filter function after the search is performed. For a description of the filter function and its prototype, see the function MyCMProfileFilterProc.

Your application cannot directly access the search result list. Instead, you pass the returned search result list reference to other search-related functions that allow you to use the result list. These functions are described in the "See Also" section.

When your application has completed its search, it should call the function CMDisposeProfileSearch to free the private memory allocated for the search.

VERSION NOTES

The CMNewProfileSearch function does not take full advantage of the optimized profile searching available starting with ColorSync version 2.5, as described in The Profile Cache and Optimized Searching . Use CMIterateColorSyncFolder instead.

SEE ALSO

To obtain a reference to a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfile . To obtain the file specification for a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfileFileSpec . To update the search result list, use the function CMUpdateProfileSearch . To free the private memory allocated for a profile search after your application has completed the search, use the function CMDisposeProfileSearch .


CMUpdateProfileSearch

Not Recommended in ColorSync 2.5

Searches the ColorSync Profiles folder and updates an existing search result obtained originally from the CMNewProfileSearch function.

pascal CMError CMUpdateProfileSearch (
                     CMProfileSearchRef search,
                     void *refCon,
                     unsigned long *count);
search
A reference to a search result list returned to your application when you called the CMNewProfileSearch function. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef .
refCon
A reference constant for application data passed as a parameter to calls to the filter function specified by the original search specification. For a description of the filter function, see the function MyCMProfileFilterProc.
count
A pointer to a profile count. On output, if the function result is noErr , a one-based count of the number of profiles matching the original search specification passed to the CMNewProfileSearch function. Otherwise undefined.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

After a profile search has been set up and performed through a call to the CMNewProfileSearch function, the CMUpdateProfileSearch function updates the existing search result. You must use this function if the contents of the ColorSync Profiles folder have changed since the original search result was created.

The search update uses the original search specification, including the filter function indicated by the search record. Data given in the CMUpdateProfileSearch function's refCon parameter is passed to the filter function each time it is called.

Sharing a disk over a network makes it possible for modification of the contents of the ColorSync Profiles folder to occur at any time.

VERSION NOTES

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.

SEE ALSO

For a description of the function you call to begin a new search, see the function CMNewProfileSearch . That function specifies the filter function referred to in the description of the refCon parameter.


CMDisposeProfileSearch

Not Recommended in ColorSync 2.5

Frees the private memory allocated for a profile search after your application has completed the search.

pascal void CMDisposeProfileSearch (CMProfileSearchRef search);
search
A reference to the profile search result list whose private memory is to be released. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef .
function result
This routine does not return value.

VERSION NOTES

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.

SEE ALSO

To set up a search, use the function CMNewProfileSearch . To obtain a reference to a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfile . To obtain the file specification for a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfileFileSpec . To update the search result list, use the function CMUpdateProfileSearch .


CMSearchGetIndProfile

Not Recommended in ColorSync 2.5

Opens the profile corresponding to a specific index into a specific search result list and obtains a reference to that profile.

pascal CMError CMSearchGetIndProfile (
                     CMProfileSearchRef search,
                     unsigned long index,
                     CMProfileRef *prof);
search
A reference to the profile search result list containing the profile whose reference you want to obtain. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef .
index
The position of the profile in the search result list. This value is specified as a one-based index into the set of profiles of the search result. The index must be less than or equal to the value returned as the count parameter of the CMNewProfileSearch function or the CMUpdateProfileSearch function; otherwise CMSearchGetIndProfile returns a result code of cmIndexRangeErr.
prof
A pointer to a profile reference of type CMProfileRef . On output, the reference refers to the profile associated with the specified index.
function result
A result code of type CMError . One possible result code is described with the index parameter above. For other possible values, see Result Codes for the ColorSync Manager .

VERSION NOTES

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.

SEE ALSO

Before your application can call the CMSearchGetIndProfile function, it must call the function CMNewProfileSearch to perform a profile search and produce a search result list. The search result list is a private data structure maintained by the ColorSync Manager. After your application has finished using the profile reference, it must close the reference by calling the function CMCloseProfile .


CMSearchGetIndProfileFileSpec

Not Recommended in ColorSync 2.5

Obtains the file specification for the profile at a specific index into a search result.

pascal CMError CMSearchGetIndProfileFileSpec (
                     CMProfileSearchRef search,
                     unsigned long index,
                     FSSpec *profileFile);
search
A reference to the profile search result containing the profile whose file specification you want to obtain. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef .
index
The index of the profile whose file specification you want to obtain. This is a one-based index into a set of profiles in the search result list. The index must be less than or equal to the value returned as the count parameter of the CMNewProfileSearch function or the CMUpdateProfileSearch function; otherwise CMSearchGetIndProfile returns a result code of cmIndexRangeErr
profileFile
A pointer to a file specification. On output, this parameter points to a file specification for the profile at the location specified by index . For a description of the FSSpec data type, see Inside Macintosh: Files.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Before your application can call the CMSearchGetIndProfileFileSpec function, it must call the function CMNewProfileSearch to perform a profile search and produce a search result list. The search result list is a private data structure maintained by ColorSync.

The CMSearchGetIndProfileFileSpec function obtains the Macintosh file system file specification for a profile at a specific index in the search result list.

VERSION NOTES

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.


Searching for a Profile by Profile Identifier

Starting with version 2.1, the ColorSync Manager defines the structure CMProfileIdentifier , which identifies a profile but takes up much less space than most profiles. A profile identifier can refer to an embedded profile or to a profile file stored in the ColorSync Profiles folder. Your application can embed profile identifiers in place of entire profiles, or in addition to them.

ColorSync provides the following functions for searching for profile identifiers:

IMPORTANT

Only version 2.x profiles are included in the profile search result.

For sample code that demonstrates how to use the profile identifier search functions, see Searching for a Profile That Matches a Profile Identifier .

For information on searching for entire profiles, see Profile Searching .


CMProfileIdentifierFolderSearch

Searches the ColorSync Profiles folder and returns a list of profile references, one for each profile that matches the specified profile identifier.

pascal CMError CMProfileIdentifierFolderSearch (
                     CMProfileIdentifierPtr ident,
                     unsigned long *matchedCount,
                     CMProfileSearchRef *searchResult);
ident
A pointer to a profile identifier structure specifying the profile to search for.
matchedCount
A pointer to a value of type unsigned long . On output, the one-based count of profiles that match the specified profile identifier. The count is typically 0 or 1, but can be higher.
searchResult
A pointer to a search result reference of type CMProfileSearchRef . On output, a reference to the profile search result list.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager . It is not an error condition if this function finds no matching profiles. It returns an error only if a File Manager or other low-level system error occurs.

DISCUSSION

When your application or device driver processes an image, it can keep a list of profile references for each profile it encounters in the image. Each time it encounters an embedded profile identifier, your application can call the function CMProfileIdentifierListSearch to see if there is already a matching profile reference in its list. If not, it can call the function CMProfileIdentifierFolderSearch to see if the profile is located in the ColorSync Profiles folder.

Although there should typically be at most one profile in the ColorSync Profiles folder that matches the profile identifier, two or more profiles with different filenames may qualify. It is not considered an error condition if the CMProfileIdentifierFolderSearch function finds no matching profiles.

For sample code demonstrating how to use CMProfileIdentifierListSearch , see Searching for a Profile That Matches a 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 CMProfileIdentifier .
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 . For possible values, see Result Codes for the ColorSync Manager . 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 can keep 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 can call 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 CMProfileIdentifier .

If no matching profile is found in the list, your application can call the function CMProfileIdentifierFolderSearch to see if a matching profile can be found in the ColorSync 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 .


© 1988-1999 Apple Computer, Inc. — (Last Updated 20 Jan 99)