Share via

EnumColorProfiles

  • Article

The EnumColorProfiles function enumerates all the profiles satisfying the given enumeration criteria.

BOOL WINAPI EnumColorProfiles(
  PCTSTR pMachineName,  PENUMTYPE pEnumRecord,  PBYTE pBuffer,  PDWORD pdwSize,  PDWORD pnProfiles);

Parameters

  • pMachineName
    Reserved. Must be NULL. This parameter is intended to point to the name of the computer on which to enumerate profiles. A NULL pointer indicates the local computer.
  • pEnumRecord
    Pointer to a structure specifying the enumeration criteria.
  • pBuffer
    Pointer to a buffer in which the profiles are to be enumerated. A MULTI_SZ string of profile names satisfying the criteria specified in *pEnumRecord will be placed in this buffer.
  • pdwSize
    Pointer to a variable containing the size of the buffer pointed to by pBuffer. On return, *pdwSize contains the size of buffer actually used or needed.
  • pnProfiles
    Pointer to a variable that will contain, on return, the number of profile names actually copied to the buffer.

Return Values

If this function succeeds, the return value is TRUE.

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

Remarks

The EnumColorProfiles function can be used to find the default profile for a device by specifying the device's name and profile class in the pEnumRecord parameter. However, another way to find a device's default color profile is to create a device context for the device and then invoke the GetICMProfile function.

When enumerating profiles associated with devices. the EnumColorProfiles function returns the default profile last.

Several profiles are typically associated with printers, based on the paper and ink types. There is a default for each device. For International Color Consortium (ICC) profiles, GDI selects the best one from the ICC-associated profiles when your application creates a device context (DC).

If the dwFields member of the structure of type ENUMTYPE that is pointed to by the pEnumRecord parameter is set to ET_DEVICENAME, this function will enumerate all of the color profiles associated with all types of devices attached to the user's computer, regardless of the device class. If the dwFields member of the structure pointed to by the pEnumRecord parameter is set to ET_DEVICENAME or ET_DEVICECLASS and a device class is specified in the dwDeviceClass member of the structure, this function will only enumerate the profiles associated with the specified device class. If the dwFields member is set only to ET_DEVICECLASS, the EnumColorProfiles function will enumerate all profiles that can be associated with that type of device.

Whenever EnumColorProfiles is examining the profiles associated with a specific device, the results depend on whether the user has chosen to use the system-wide list of profiles associated with that device, or his or her own ("per-user") list. Calling WcsSetUserPerUserProfiles with its usePerUserProfiles parameter set to TRUE causes future calls to EnumColorProfiles to look at only the current user's per-user list of profile associations for the specified device. Calling WcsSetUserPerUserProfiles with its usePerUserProfiles parameter set to FALSE causes future calls to EnumColorProfiles to look at the system-wide list of profile associations for the specified device. If WcsSetUsePerUserProfiles has never been called for the current user, EnumColorProfiles examines the system-wide list.

Your application can use EnumColorProfiles to obtain the size of the buffer in which the profiles are enumerated. It should call the EnumColorProfiles function with the pBuffer parameter set to NULL. When the function returns, the pdwSize parameter will contain the required buffer size in bytes. Your program can use that information to allocate the enumeration buffer. It can then invoke EnumColorProfiles again with the pBuffer parameter set to the address of the buffer.

This function will provide the information for converting WCS-specific DMP information to the legacy EnumType record in enable consistent profile enumeration. The defaults will be the same as ICC if this information is not present.

Per-user/LUA support

The enumeration is specific to current user. Both system wide and current user device associations are considered. For default profile configuration, current user settings override system wide ones.

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, GetICMProfile, ENUMTYPE