![]() |
PATH![]() |
![]() ![]() |
This section describes the functions you use to examine, set, and change individual elements of a profile.
CMProfileElementExists
tests whether the specified profile contains a specific element based on the element's tag signature.CMCountProfileElements
counts the number of elements in the specified profile.CMGetProfileElement
obtains
element data from the specified profile based on the specified element tag signature.CMGetProfileHeader
obtains the profile header for the specified profile.CMGetPartialProfileElement
obtains a portion
of the element data from the specified profile based on the specified element tag signature.CMGetIndProfileElementInfo
obtains the element tag and data size of an element by index from the specified profile.CMGetIndProfileElement
obtains the element data corresponding to a particular index from the specified profile.CMSetProfileElementSize
reserves the element data size for a specific tag in the specified profile before setting the element data.CMSetPartialProfileElement
sets part of the element data for a specific tag in the specified profile.CMSetProfileElement
sets or replaces the element data for a specific tag in the specified profile.CMSetProfileHeader
sets the header for the specified profile.CMSetProfileElementReference
adds a tag to the specified profile to refer to data corresponding to a previously set element.CMRemoveProfileElement
removes an element corresponding to a specific tag from the specified profile.CMGetScriptProfileDescription
obtains the internal name (or description) of a profile and the script code identifying the language in which the profile name is specified from the specified profile.Tests whether the specified profile contains a specific element based on the element's tag signature.
pascal CMError CMProfileElementExists (
CMProfileRef prof,
OSType tag,
Boolean *found);
CMProfileRef
that specifies the profile to examine.
You cannot use this function to test whether certain data in the
CM2Header
profile header exists. Instead, you must call the function
CMGetProfileHeader
to copy the entire profile header and read its contents.
Counts the number of elements in the specified profile.
pascal CMError CMCountProfileElements (
CMProfileRef prof,
unsigned long *elementCount);
CMProfileRef
to the profile to examine.Every element in the profile outside the header is counted. A profile may contain tags that are references to other elements. These tags are included in the count. For information about profiles and their tags, see Profile Properties .
Obtains element data from the specified profile based on the specified element tag signature.
pascal CMError CMGetProfileElement (
CMProfileRef prof,
OSType tag,
unsigned long *elementSize,
void *elementData);
CMProfileRef
to the profile containing the target element.Before you call the CMGetProfileElement function to obtain the element data for a specific element, you must know the size in bytes of the element data so you can allocate a buffer to hold the returned data.
The CMGetProfileElement function serves two purposes: to get an element's size and to obtain an element's data. In both instances, you provide a reference to the profile containing the element in the prof parameter and the tag signature of the element in the tag parameter.
To obtain the element data size, call the CMGetProfileElement function specifying a pointer to an unsigned long data type in the elementSize field and a NULL value in the elementData field.
After you obtain the element size, you should allocate a buffer large enough to hold the returned element data, then call the CMGetProfileElement function again, specifying NULL in the elementSize parameter to copy the entire element data and a pointer to the data buffer in the elementData parameter.
To copy only a portion of the element data beginning from the first byte, allocate a buffer the size of the number of bytes of element data you want to obtain and specify the number of bytes to copy in the elementSize parameter. In this case, on output the elementSize parameter contains the size in bytes of the element data actually returned.
You cannot use the
CMGetProfileElement
function to copy a portion of element data beginning from an offset into the data. To copy a portion of the element data beginning from any offset, use the function
CMGetPartialProfileElement
.
You cannot use this function to obtain a portion of the
CM2Header
profile header. Instead, you must call the function
CMGetProfileHeader
to copy the entire profile header and read its contents.
Obtains the profile header for the specified profile.
pascal CMError CMGetProfileHeader (
CMProfileRef prof,
CMAppleProfileHeader *header);
CMProfileRef
to the profile whose header is to be copied.CM2Header
. For information about the ColorSync 1.0 header, see
CMHeader
and
How ColorSync 1.0 Profiles and Version 2.x Profiles Differ
.
The
CMGetProfileHeader
function returns the header for a ColorSync 2.x or ColorSync 1.0 profile. To return the header, the function uses a union of type
CMAppleProfileHeader
, with variants for version 1.0 and 2.x headers.
A 32-bit version value is located at the same offset in either header. For ColorSync 2.x profiles, this is the profileVersion field. For ColorSync 1.0 profiles, this is the applProfileVersion field. You can inspect the value at this offset to determine the profile version, and interpret the remaining header fields accordingly.
To copy a profile header to a profile after you modify the header's contents, use the function
CMSetProfileHeader
.
Obtains a portion of the element data from the specified profile based on the specified element tag signature.
pascal CMError CMGetPartialProfileElement (
CMProfileRef prof,
OSType tag,
unsigned long offset,
unsigned long *byteCount,
void *elementData);
CMProfileRef
to the profile containing the target element.The CMGetPartialProfileElement function allows you to copy any portion of the element data beginning from any offset into the data. For the CMGetPartialProfileElement function to copy the element data and return it to you, your application must allocate a buffer in memory to hold the data.
You cannot use this function to obtain a portion of the
CM2Header
profile header. Instead, you must call the function
CMGetProfileHeader
to get the entire profile header and read its contents.
Obtains the element tag and data size of an element by index from the specified profile.
pascal CMError CMGetIndProfileElementInfo (
CMProfileRef prof,
unsigned long index,
OSType *tag,
unsigned long *elementSize,
Boolean *refs);
CMProfileRef
to the profile containing the element.
Before calling the
CMGetIndProfileElementInfo
function, you should call the function
CMCountProfileElements
, which returns the total number of elements in the profile in the
elementCount
parameter. The number you specify for the
index
parameter when calling
CMGetIndProfileElementInfo
should be in the range of 1 to
elementCount
; otherwise the function will return a result code of
cmIndexRangeErr
. The index order of elements is determined internally by the ColorSync Manager and is not publicly defined.
You might want to call this function, for example, to print out the contents of a profile.
Obtains the element data corresponding to a particular index from the specified profile.
pascal CMError CMGetIndProfileElement (
CMProfileRef prof,
unsigned long index,
unsigned long *elementSize,
void *elementData);
CMProfileRef
to the profile containing the element.Before you call the CMGetIndProfileElement function to obtain the element data for an element at a specific index, you first determine the size in bytes of the element data. To determine the data size, you can
CMGetIndProfileElementInfo
, passing the element's indexOnce you have determined the size of the element data, you allocate a buffer to hold as much of the data as you need. If you want all of the element data, you specify NULL in the elementSize parameter. If you want only a portion of the element data, you specify the number of bytes you want in the elementSize parameter. You supply a pointer to the data buffer in the elementData parameter. After calling CMGetIndProfileElement , the elementSize parameter contains the size in bytes of the element data actually copied.
Before calling this function, you should call the function
CMCountProfileElements
. It returns the profile's total element count in the
elementCount
parameter.
Reserves the element data size for a specific tag in the specified profile before setting the element data.
pascal CMError CMSetProfileElementSize (
CMProfileRef prof,
OSType tag,
unsigned long elementSize);
CMProfileRef
to the profile in which the element data size is reserved.
Your application can use the
CMSetProfileElementSize
function to reserve the size of element data for a specific tag before you call the function
CMSetPartialProfileElement
to set the element data. The most efficient way to set a large amount of element data when you know the size of the data is to first set the size, then call the
CMSetPartialProfileElement
function to set each of the data segments. Calling the
CMSetProfileElementSize
function first eliminates the need for the ColorSync Manager to repeatedly increase the size for the data each time you call the
CMSetPartialProfileElement
function.
In addition to reserving the element data size, the CMSetProfileElementSize function sets the element tag, if it does not already exist.
Sets part of the element data for a specific tag in the specified profile.
pascal CMError CMSetPartialProfileElement (
CMProfileRef prof,
OSType tag,
unsigned long offset,
unsigned long byteCount,
void *elementData);
CMProfileRef
to the profile containing the tag for which the element data is set.You can use the CMSetPartialProfileElement function to set the data for an element when the amount of data is large and you need to copy it to the profile in segments.
After you set the element size, you can call this function repeatedly, as many times as necessary, each time appending a segment of data to the end of the data already copied until all the element data is copied.
If you know the size of the element data, you should call the function
CMSetProfileElementSize
to reserve it before you call
CMSetPartialProfileElement
to set element data in segments. Setting the size first avoids the extensive overhead required to increase the size for the element data with each call to append another segment of data.
To copy the entire data for an element as a single operation, when the amount of data is small enough to allow this, call the function
CMSetProfileElement
.
Sets or replaces the element data for a specific tag in the specified profile.
pascal CMError CMSetProfileElement (
CMProfileRef prof, OSType tag,
unsigned long elementSize,
void *elementData);
CMProfileRef
to the profile containing the tag for which the element data is set.The CMSetProfileElement function replaces existing element data if an element with the specified tag is already present in the profile. Otherwise, it sets the element data for a new tag. Your application is responsible for allocating memory for the buffer to hold the data to transfer.
Sets the header for the specified profile.
pascal CMError CMSetProfileHeader (
CMProfileRef prof,
const CMAppleProfileHeader *header);
CMProfileRef
to the profile whose header is set.
You can use the
CMSetProfileHeader
function to set a header for a version 1.0 or a version 2.x profile. Before you call this function, you must set the values for the header, depending on the version of the profile. For a version 2.x profile, you use a data structure of type
CM2Header
. For a version 1.0 profile, you use a data structure of type
CMHeader
. You pass the header you supply in the
CMAppleProfileHeader
union, described in
CMAppleProfileHeader
.
Adds a tag to the specified profile to refer to data corresponding to a previously set element.
pascal CMError CMSetProfileElementReference (
CMProfileRef prof,
OSType elementTag,
OSType referenceTag);
CMProfileRef
to the profile to add the tag to.After the CMSetProfileElementReference function executes successfully, the specified profile will contain more than one tag corresponding to a single piece of data. All of these tags are of equal importance. Your application can set a reference to an element that was originally a reference itself without circularity.
If you call the function
CMSetProfileElement
subsequently for one of the tags acting as a reference to another tag's data, then the element data you provide is set for the tag and the tag is no longer considered a reference. Instead, the tag corresponds to its own element data and not that of another tag.
Removes an element corresponding to a specific tag from the specified profile.
pascal CMError CMRemoveProfileElement (
CMProfileRef prof,
OSType tag);
CMProfileRef
to the profile containing the tag remove.The CMRemoveProfileElement function deletes the tag as well as the element data from the profile.
Obtains the internal name (or description) of a profile and the script code identifying the language in which the profile name is specified from the specified profile.
pascal CMError CMGetScriptProfileDescription (
CMProfileRef prof,
Str255 name,
ScriptCode *code);
CMProfileRef
to the profile whose profile name and script code are obtained. The element data of the text description tag (which has the signature 'desc' or constant cmSigProfileDescriptionType , defined in the CMICCProfile.h header file) specifies the profile name and script code. The name parameter returns the profile name as a Pascal string. Use this function so that your application does not need to obtain and parse the element data, which contains other information.