WcsOpenColorProfile function

The WcsOpenColorProfile function creates a handle to a specified color profile.

Syntax


HPROFILE WINAPI WcsOpenColorProfile(
  _In_     PROFILE pDMPProfile,
  _In_opt_ PROFILE pCAMPProfile,
  _In_opt_ PROFILE pGMMPProfile,
  _In_     DWORD   dwDesiredAccess,
  _In_     DWORD   dwShareMode,
  _In_     DWORD   dwCreationMode,
  _In_     DWORD   dwFlags
);

Parameters

pDMPProfile [in]

A pointer to a profile structure that specifies a WCS device model profile (DMP). The pDMPProfile pointer can be freed as soon as the handle is created.

pCAMPProfile [in, optional]

A pointer to a profile structure that specifies a WCS color appearance model profile (CAMP). The pCAMPProfile pointer can be freed as soon as the handle is created. If NULL, the standard 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). The pGMMPProfile pointer can be freed as soon as the handle is created. 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 in the Microsoft Windows SDK documentation.

dwDesiredAccess [in]

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

PROFILE_READ

Specifies that the color profile will be opened for read-only access.

PROFILE_READWRITE

Specifies that the color profile will be opened for both read and write access. This flag value is ignored when a WCS profile is opened.

dwShareMode [in]

A flag value that specifies 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 winnt.h:

FILE_SHARE_READ

Specifies that other open operations can be performed on the profile for read access.

FILE_SHARE_WRITE

Specifies that other open operations can be performed on the profile for write access. This flag value is ignored when a WCS profile is opened.

dwCreationMode [in]

A flag value that specifies 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 to be created. The function fails if the profile already exists.

CREATE_ALWAYS

Specifies that a new profile is to be created. If a profile already exists, it is overwritten.

OPEN_EXISTING

Specifies that the profile is to be opened. The 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 [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.

 

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. For extended error information, call GetLastError (described in the Microsoft Windows SDK documentation).

Remarks

The handle returned by this function can be used in other color profile management functions.

The compiler setting also determinDeclared in Icm.hes the function version. If Unicode is defined, the function call resolves to WcsOpenColorProfileW. Otherwise, the function call resolves to WcsOpenColorProfileA because ANSI strings are being used.

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

This function initially attempts to open the profile as an ICC profile. Even if a WCS profile is provided, the PROFILE_READWRITE and FILE_SHARE_WRITE flags are not ignored. However, if the provided profile is not an ICC profile (and a new ICC profile is not being created), these flag values are ignored.

The dwCreationMode flags CREATE_NEW, CREATE_ALWAYS, and TRUNCATE_EXISTING will always return an empty handle to the ICC color profile.

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

Requirements

Target platform

Universal

Version

Included in Windows Vista and later.

Header

Icm.h

Library

Mscms.lib

See also

CloseColorProfile

 

 

Send comments about this topic to Microsoft

Show: