![]() |
PATH![]() |
![]() ![]() |
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.
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.
CMIterateColorSyncFolder
Iterates over the available profiles;
new in ColorSync 2.5
.For additional information on profile searching, see Searching for Profiles Prior to ColorSync 2.5 and Searching for a Profile by Profile Identifier .
Iterates over the available profiles.
pascal CMError CMIterateColorSyncFolder (
CMProfileIterateUPP proc,
unsigned long * seed,
unsigned long * count,
void * refCon);
CMProfileIterateProcPtr
. If you do not wish to receive callbacks, pass
NULL
for this parameter. Otherwise, pass a pointer to your callback routine.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 .
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 .
CMNewProfileSearch
searches the ColorSync Profiles folder and returns a list of 2.x profiles that match the search specification;
not recommended in ColorSync 2.5
.CMUpdateProfileSearch
searches the ColorSync Profiles folder and updates an existing search result obtained originally from the
CMNewProfileSearch
function;
not recommended in ColorSync 2.5
.CMDisposeProfileSearch
frees the private memory allocated for a profile search after your application has completed the search;
not recommended in ColorSync 2.5
.CMSearchGetIndProfile
opens the profile corresponding to a specific index into a specific search result list and obtains a reference to that profile;
not recommended in ColorSync 2.5
.CMSearchGetIndProfileFileSpec
obtains the file specification for the profile at a specific index into a search result;
not recommended in 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.
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);
CMSearchRecord
.MyCMProfileFilterProc
. CMProfileSearchRef
.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.
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.
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
.
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);
CMProfileSearchRef
.MyCMProfileFilterProc
.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.
Starting with version 2.5, you should use the function
CMIterateColorSyncFolder
for profile searching.
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.
Frees the private memory allocated for a profile search after your application has completed the search.
pascal void CMDisposeProfileSearch (CMProfileSearchRef search);
CMProfileSearchRef
.
Starting with version 2.5, you should use the function
CMIterateColorSyncFolder
for profile searching.
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
.
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);
CMProfileSearchRef
.CMProfileRef
. On output, the reference refers to the profile associated with the specified index.
Starting with version 2.5, you should use the function
CMIterateColorSyncFolder
for profile searching.
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
.
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);
CMProfileSearchRef
.
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.
Starting with version 2.5, you should use the function
CMIterateColorSyncFolder
for profile searching.
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:
CMProfileIdentifierFolderSearch
searches the ColorSync Profiles folder and returns a list of profile references, one for each profile that matches the specified profile identifier.CMProfileIdentifierListSearch
searches a list of profile references and returns a list of all references that match a specified profile identifier. 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 .
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);
CMProfileSearchRef
. On output, a reference to the profile search result list.
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 .
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);
CMProfileIdentifier
.
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 .