To perform a profile iteration, you first create a CMSProfileIterator by calling cmsStartProfileIteration(), and then repeatedly call cmsNextProfileIteration(). If there is another profile in the iteration sequence, cmsNextProfileIteration() sets a pointer to its filename. When there are no more profiles on disk, cmsNextProfileIteration() returns NULL.

To efficiently select a profile or display a set of profiles in a menu, you typically need only the minimal information kept in profile headers, which are only 128 bytes. Use cmsGetHeaderProfileSpec() to query a profile on disk for header information.

When there are no more profiles available, you dispose of the iterator by calling cmsEndProfileIteration().

The following code fragment illustrates a profile iteration. In the interest of clarity, the proper error checking is not shown.

char               *pspec;
CMSProfileIterator  theIterator;
icHeader            header;
 
cmsStartProfileIteration(context, &theIterator);
while (cmsNextProfileIteration(context, theIterator, &pspec) !=  
        NULL) {
 
    cmsGetProfileSpecHeader(context, spec, &header);
    if (/* tests on fields in header pass */) {
        /* code to add profile to the application */
    }
    free(pspec);
}
cmsEndProfileIteration(context, theIterator); 

The next sections detail the data structures and function calls in this example, and introduce related functions.

The data structure icHeader is not discussed because it is not a Coloratura structure; it is the profile header data structure defined by the ICCColor Profile Format Specification. icHeader is defined in ic.h. Since icHeader is of fixed size, you are responsible for allocating and freeing storage for it, as discussed in "Managing Memory".

The pointer CMSProfileIterator refers to an opaque data structure that keeps track of position in a list of profiles during an iteration. This is the data type declaration:

typedef struct _CMSProfileIterator  *CMSProfileIterator;

The function cmsStartProfileIteration() starts a profile iteration and creates a CMSProfileIterator.

The function cmsNextProfileIteration() finds the next filename in a profile iteration. When the iteration is complete, the function returns NULL.

The function cmsGetProfileHeader() reads the ICC profile header from a profile on disk.

You can also read a profile header from an open profile, one that has been read into a Coloratura data structure; see "Getting Open-Profile Header Information: cmsGetProfileHeader()".

The function cmsEndProfileIteration() ends a profile iteration and disposes of the iterator.

The pointer CMSProfile refers to an opaque data structure that stores profile data. All of your program's interactions with profile data are mediated by a CMSProfile.

You call the function cmsOpenProfile() to provide Coloratura functions with access to profile data that are on disk. Only after the profile is open can your application read from it, write to it, or include it in a transform. The function cmsOpenProfile() needs a filename to get the data from disk, but all subsequent references to the profile data are through the CMSProfile pointer set by cmsOpenProfile().

The function cmsCloseProfile() closes the copy of a profile in memory, that is, a CMSProfile data structure, and frees the memory allocated. If you want to remove the profile data from disk, use cmsDeleteProfile(), discussed below.

The function cmsCloseProfile() does not automatically save the CMSProfile data to disk. To save changes to a profile before you call cmsCloseProfile(), call cmsSaveProfile(), which is discussed in "Saving Profile Changes to Disk: cmsSaveProfile()", or cmsSaveProfileAs(), which is discussed in "Saving to a New File on Disk: cmsSaveProfileAs()".

The function cmsDeleteProfile() deletes a profile from the file system. The usual IRIX permission system applies; you might not have permission to delete a given profile.

The cmsCreateProfile() function creates a new CMSProfile data structure that contains no tag data. The new profile is not available to the file system until you save it with a call to cmsSaveProfileAs(), which is discussed in "Saving to a New File on Disk: cmsSaveProfileAs()".

The function cmsGetProfileHeader() returns the same information as cmsGetProfileSpecHeader() (see "Examining Headers of Profiles on Disk: cmsGetProfileSpecHeader()"), but differs in that it takes a CMSProfile, rather than a filename.

cmsGetProfileHeader() gets the header information from an open profile and returns a pointer to an icHeader data structure, which is declared in ic.h (see the ICC Device Profile Format Specification for a definition of what is stored in an icHeader structure). Since icHeader is of fixed size, you must allocate and free storage for it, as discussed in "Managing Memory".

The function cmsSetProfileHeader() stores a header in an open profile. Typically, you use cmsSetProfileHeader() to put a header in a new profile.

The Coloratura CMS does not provide a function to update selected fields of a header, which it reads or writes as a whole. To update a specific field, you should first read the header into an icHeader structure, using cmsGetProfileHeader(). Then update the field with your own code and write the header to the profile with cmsSetProfileHeader().

The header file ic.h defines icHeader. Since icHeader is of fixed size, you must allocate and free storage for it. See the ICC Profile Format Specification for a definition of what is stored in a header.

The cmsSaveProfile() function saves an open profile to permanent storage, making it available to the file system. It does not remove the CMSProfile data structure from memory; the data remains available for further editing. Use cmsCloseProfile() to delete the CMSProfile data structure.

The function cmsSaveProfileAs() is similar to cmsSaveProfile(), in that it writes a profile to permanent storage, but it creates a new file with a filename you specify.

The function cmsExportProfile() converts the data in a CMSProfile data structure to the ICC file format. Storage for the exported data is allocated by the Coloratura CMS, so it must be freed by calling cmsFreeProfileExport().

The function cmsFreeProfileExport() frees the output data storage created by cmsExportProfile().

To create a CMSProfile data structure from a data buffer that is in the ICC format, typically obtained from an embedded profile, call cmsImportProfile(). You provide a CMSProfile, which cmsImportProfile() initializes to locate the newly constructed profile data structure.