OpenColorProfileW function (icm.h)

  • Article

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

Syntax

HPROFILE OpenColorProfileW(
  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.

Value 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).

Value 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.

Value 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 value

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

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Header icm.h
Library Mscms.lib
DLL Mscms.dll

See also