Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

WcsOpenColorProfile Function

Creates a handle to a specified color profile.

Syntax

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 [in]

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 [in, optional]

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 [in, optional]

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 [in]

A flag value that specifies how to access the specified color profile. This parameter must take one of the following values:

PROFILE_READSpecifies that the color profile opens for read-only access.
PROFILE_READWRITESpecifies 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 [in]

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_READSpecifies that you can perform other open (for read access) operations on the profile.
FILE_SHARE_WRITESpecifies 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 [in]

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_NEWSpecifies that a new profile is created. This function fails if the profile already exists.
CREATE_ALWAYSSpecifies that a new profile is created. If a profile already exists, it is overwritten.
OPEN_EXISTINGSpecifies that the profile is opened. This function fails if the profile does not exist.
OPEN_ALWAYSSpecifies 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_EXISTINGSpecifies that the profile is to be opened and truncated to zero bytes. The function fails if the profile does not exist.

 

dwFlags [in]

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:

0Specifies that the embedded WCS profile will be used and the ICC profile specfied by pCDMPProfile will be ignored.
DONT_USE_EMBEDDED_WCS_PROFILESSpecifies that the ICC profile specified by pCDMPProfile will be used and the embedded WCS profile will be ignored.

 

Return Value

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

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008

Header

Icm.h

Library

Mscms.lib

DLL

Mscms.dll

See Also

Basic Color Management Concepts
Windows Color System Schemas and Algorithms
Functions

 

 

Send comments about this topic to Microsoft

Build date: 11/16/2010

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.