OpenColorProfile

  • Article

The OpenColorProfile function creates a handle to a specified color profile. The handle can then be used in other profile management functions.

HPROFILE WINAPI OpenColorProfile(
  PPROFILE pProfile,  DWORD dwDesiredAccess,  DWORD dwShareMode,  DWORD dwCreationMode);

Parameters

  • pProfile
    Pointer to a color profile structure specifying the profile. The pProfile pointer can be freed as soon as the handle is created.

  • dwDesiredAccess
    Specifies how to access the given profile. This parameter must take one the following constant values.

    Constant Meaning
    PROFILE_READ Opens the profile for read access.
    PROFILE_READWRITE Opens the profile for both read and write access. Has no effect for WCS XML profiles.

  • dwShareMode
    Specifies how the profile should be shared, if the profile is contained in a file. A value of zero prevents the profile from being shared at all. The parameter can contain one or both of the following constants (combined by addition or logical OR).

    Constant Meaning
    FILE_SHARE_READ Other open operations can be performed on the profile for read access.
    FILE_SHARE_WRITE Other open operations can be performed on the profile for write access. Has no effect for WCS XML profiles.

  • dwCreationMode
    Specifies which actions to take on the profile while opening it, if it is contained in a file. This parameter must take one of the following constant values.

    Constant Meaning
    CREATE_NEW Creates a new profile. Fails if the profile already exists.
    CREATE_ALWAYS Creates a new profile. Overwrites the profile if it exists.
    OPEN_EXISTING Opens the profile. Fails if it does not exist
    OPEN_ALWAYS Opens the profile if it exists. For ICC profiles, if the profile does not exist, creates the profile. For WCS XML profiles, if the profile does not exist, returns an error.
    TRUNCATE_EXISTING Opens the profile, and truncates it to zero bytes, returning a blank ICC profile. Fails if the profile doesn't exist.

Return Values

If this function succeeds, the return value is the handle of the color profile that is opened. For ICC and WCS profiles, a CAMP and GMMP are provided by the function based on the current default CAMP and GMMP in the registry.

When OpenColorProfile encounters an ICC profile with an embedded WCS profile, and if the dwType member within the Profile structure does not take the value DONT_USE_EMBEDDED_WCS_PROFILES, it should extract and use the WCS profile(s) contained in this WcsProfilesTag.  The HPROFILE returned would be a WCS HPROFILE.

If this function fails, the return value is NULL. For extended error information, call GetLastError.

Remarks

If the profile data is not specified using a file name, dwShareMode and dwCreationMode are ignored.

dwCreationMode flags CREATE_NEW, CREATE_ALWAYS, and TRUNCATE_EXISTING, will always return blank ICC HPROFILEs. If other dwCreationMode flags are present, InternalOpenColorProfile is called (using the flags as provided by the API) to determine whether the profile is ICC or WCS XML.

Within the ICC code path, an ICC HPROFILE is returned using the requested sharing, access and creation flags as specified in the tables above.

Within the WCS path, the dwCreationMode flag OPEN_ALWAYS will fail if the profile doesn't exist, since WCS profiles cannot be created or edited within the WCS architecture (they must be edited outside of it, using MSXML6). For the same reason, dwShareMode flag FILE_SHARE_WRITE, and dwDesiredAccess flag PROFILE_READWRITE are ignored within the WCS path.

When the function opens the ICC profile, it will look for a WcsProfilesTag and, if there is one, it will extract and use the original WCS profiles contained therein. (See WcsCreateIccProfile.)

An HPROFILE with WCS profile information is derived from a DMP by acquiring the default CAMP and default GMMP from the registry. An HPROFILE is a composition of a DMP, CAMP and GMMP. 

Once the handle to the color profile is created, any information used to create that handle can be deleted.

Use the CloseColorProfile function to close an object handle returned by OpenColorProfile.

Requirements

**  Windows Vista:** Support for WCS profiles included in Windows Vista and later.
**  Windows NT/2000/XP:** Support for ICC profiles included in Windows 2000 and later.
**  Windows 95/98/Me:** Support for ICC profiles included in Windows 98 and later.
**  Header:** Declared in Icm.h.
**  Library:** Use Mscms.lib.
**  Unicode:** Implemented as Unicode and ANSI versions on Windows 2000/XP/Vista.

See Also

Basic Color Management Concepts, Functions, CloseColorProfile, PROFILE