Contents

NCMGetProfileLocation

Obtains either a profile location structure for a specified profile or the size of the location structure for the profile.

Declaration

CMError NCMGetProfileLocation (
   CMProfileRef prof,
   CMProfileLocation *theProfile,
   UInt32 *locationSize
);

Parameters

  • prof:

    A profile reference of type Cmprofileref. Before calling NCMGetProfileLocation, you set the reference to specify the profile for which you wish to obtain the location or location structure size.

  • theProfile:

    A pointer to a profile location structure, as described in Cmprofilelocation. If you pass NULL, NCMGetProfileLocation returns the size of the profile location structure for the profile specified by prof in the locationSize parameter. If you instead pass a pointer to memory you have allocated for the structure, on return, the structure specifies the location of the profile specified by prof.

  • locationSize:

    A pointer to a value of type long. If you pass NULL for the profLoc parameter, on return, locationSize contains the size in bytes of the profile location structure for the profile specified by prof. If you pass a pointer to a profile location structure in profLoc, set locationSize to the size of the structure before calling NCMGetProfileLocation, using the constant cmCurrentProfileLocationSize.

Return Value

A CMError value. See Result Codes.

Overview

The NCMGetProfileLocation function is available starting with ColorSync version 2.5. It differs from its predecessor, CMGetProfileLocation, in that the newer version has a parameter for the size of the location structure for the specified profile.

You should use NCMGetProfileLocation rather than CMGetProfileLocation for the following reasons:

  • Code using the older version (CMGetProfileLocation) may not be as easily ported to other platforms.

  • Specifying the size of the profile location structure ensures that it can grow, if necessary, in the future.

The best way to use NCMGetProfileLocation is to call it twice:

  1. Pass a reference to the profile to locate in the prof parameter and NULL for the profLoc parameter. NCMGetProfileLocation returns the size of the location structure in the locationSize parameter.

  2. Allocate enough space for a structure of the returned size, then call the function again, passing a pointer in the profLoc parameter; on return, the structure specifies the location of the profile.

It is possible to call NCMGetProfileLocation just once, using the constant cmCurrentProfileLocationSize for the size of the allocated profile location structure and passing the same constant for the locationSize parameter. The constant cmCurrentProfileLocationSize may change in the future, but will be consistent within the set of headers you build your application with. However, if the size of the CMProfileLocation structure changes in a future version of ColorSync (and the value of cmCurrentProfileLocationSize as well) and you do not rebuild your application, NCMGetProfileLocation may return an error.

See Also

Accessing Profiles