WcsOpenColorProfile

Creates a handle to a specified color profile.

HPROFILE WINAPI WcsOpenColorProfile(
  __in PPROFILE pCDMPProfile,
  __in_opt PPROFILE pCAMPProfile,
  __in_opt PPROFILE pGMMPProfile,
  __in DWORD dwDesiredAccess,
  __in DWORD dwShareMode,
  __in DWORD dwCreationMode,
  __in DWORD dwFlags);

Parameters

• pCDMPProfile
  Pointer to a WCS DMP or an ICC color profile structure specifying the profile. You can free the pCDMPProfile pointer after you create the handle. If the profile is ICC and its dwType member is set to DONT_USE_EMBEDDED_WCS_PROFILES, WcsOpenColorProfile ignores any embedded WCS profile within the ICC profile.
• pCAMPProfile
  A pointer to a profile structure that specifies a WCS color appearance model profile (CAMP). You can free the pCAMPProfile pointer after you create the handle. If NULL, the default CAMP is used, and the current user setting, WCS_PROFILE_MANAGEMENT_SCOPE_CURRENT_USER, is used while querying the default CAMP.
• pGMMPProfile
  A pointer to a profile structure that specifies a WCS gamut map model profile (GMMP). You can free the pGMMPProfile pointer after you create the handle. If NULL, the default GMMP for the default rendering intent is used, and the current user setting, WCS_PROFILE_MANAGEMENT_SCOPE_CURRENT_USER, is used while querying the default GMMP. For a description of rendering intents, see Rendering Intents.
• dwDesiredAccess
  A flag value that specifies how to access the specified color profile. This parameter must take one of the following values:
  • PROFILE_READ
    Specifies that the color profile opens for read-only access.
  • PROFILE_READWRITE
    Specifies that the color profile opens for both read and write access. The value of this flag is ignored if the profile is a WCS profile.
• dwShareMode
  A flag value that specifies actions to take while opening a color profile contained in a file. This parameter must take one of the following values, which are defined in winnt.h:
  • FILE_SHARE_READ
    Specifies that you can perform other open (for read access) operations on the profile.
  • FILE_SHARE_WRITE
    Specifies that you can perform other open (for write access) operations on the profile. This flag value is ignored when a WCS profile is opened.
• dwCreationMode
  A flag value that specifies the actions to take while opening a color profile if it is contained in a file. This parameter must take one of the following values, which are defined in winbase.h:
  • CREATE_NEW
    Specifies that a new profile is created. This function fails if the profile already exists.
  • CREATE_ALWAYS
    Specifies that a new profile is created. If a profile already exists, it is overwritten.
  • OPEN_EXISTING
    Specifies that the profile is opened. This function fails if the profile does not exist.
  • OPEN_ALWAYS
    Specifies that the profile is to be opened if an International Color Consortium (ICC) file exists. If an ICC profile does not exist, WCS creates a new ICC profile. The function will fail for WCS profiles if this flag is set and a WCS profile does not exist.
  • TRUNCATE_EXISTING
    Specifies that the profile is to be opened and truncated to zero bytes. The function fails if the profile does not exist.
• dwFlags
  A flag value that specifies whether to use the embedded WCS profile. This parameter has no effect unless pCDMProfile specifies an ICC profile that contains an embedded WCS profile. This parameter takes one of the following values:
  • 0
    Specifies that the embedded WCS profile will be used and the ICC profile specfied by pCDMPProfile will be ignored.
  • DONT_USE_EMBEDDED_WCS_PROFILES
    Specifies that the ICC profile specified by pCDMPProfile will be used and the embedded WCS profile will be ignored.

Return Values

If this function succeeds, the return value is the handle of the color profile that is opened.

If this function fails, the return value is NULL.

Remarks

This API will take a set of DMP, CAMP, and GMMP and return a WCS profile handle. NULL values for GMMP are valid. A NULL value for CAMP will be replaced with the default CAMP value.

This API will also accept ICC profiles. Using an ICC profile does not guarantee processing by the WCS CITE engine. The WCS engine will only be used if it is passed at least one WCS profile. Pure ICC workflows will be consistent with legacy behavior.

You can use the handle that this function returns in other color profile management functions.

The dwCreationMode flags CREATE_NEW, CREATE_ALWAYS, and TRUNCATE_EXISTING will always return blank ICC HPROFILEs. If other dwCreationMode flags are present, the function will 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 does not exist, because 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 the dwDesiredAccess flag PROFILE_READWRITE are ignored within the WCS path.

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 that is returned by WcsOpenColorProfile.

Requirements

**  Windows Vista:** Included in Windows Vista and later.
**  Header:** Declared in Icm.h.
**  Library:** Use Mscms.lib.
**  Unicode:** Implemented as Unicode and ANSI versions on Windows Vista.

See Also

Basic Color Management Concepts, Windows Color System Schemas and Algorithms, Functions, CloseColorProfile