DEVMODE

typedef struct _DEVMODE {
     char  dmDeviceName[CCHDEVICENAME];
    UINT  dmSpecVersion;
    UINT  dmDriverVersion;
    UINT  dmSize;
    UNIT  dmDriverExtra;
    DWORD dmFields;
    int   dmOrientation;
    int   dmPaperSize;
    int   dmPaperLength;
    int   dmPaperWidth;
    int   dmScale;
    int   dmCopies;
    int   dmDefaultSource;
    int   dmPrintQuality;
    int   dmColor;
    int   dmDuplex;
    int   dmYResolution;
    int   dmTTOption;
    int   dmCollate;
    TCHAR dmFormName[CCHFORMNAME];
    WORD  dmLogPixels;
    DWORD dmBitsPerPel;
    DWORD dmPelsWidth;
    DWORD dmPelsHeight;
    DWORD dmDisplayFlags;
    DWORD dmDisplayFrequency;
    DWORD dmICMMethod;
    DWORD dmICMIntent;
    DWORD dmMediaType;
    DWORD dmDitherType;
    DWORD dmReserved1;
    DWORD dmReserved2;
} DEVMODE;

Structure that contains information about the device initialization and environment of a printer. An application passes this structure to DeviceCapabilities and ExtDeviceMode functions exported by the driver. The DEVMODE structure is defined in PRINT.H.

DEVMODE members which are new to Windows 95 are defined below.

dmCollate

Specifies whether collation should be used when printing multiple copies. This member can have one of the following values:

Value	Meaning
DMCOLLATE_TRUE	Collate when printing multiple copies.
DMCOLLATE_FALSE	Do not collate when making multiple copies.

Using DMCOLLATE_FALSE provides faster, more efficient output, since the data is sent to a page printer just once, no matter how many copies are required, and the printer is instructed to simply print the page again.

dmFormName	This member is unused for the first release of Windows 95.
dmLogPixels	Specifies the number of log pixels in the x direction. The value in this member should be equal to the value in the uLogPixels member of the GDIINFO structure.
dmBitsPerPel	Unused for printers. For display devices, specifies in bits per pixel the color resolution of the device.
dmPelsWidth	Unused for printers. For display devices, specifies the width, in pixels, of the visible device surface.
dmPelsHeight	Unused for printers. For display devices, specifies the height, in pixels, of the visible device surface.
dmDisplayFlags	Unused for printers. For display devices, specifies the display mode of the device.
dmDisplayFrequency	Unused for printers. For display devices, specifies the frequency of the device in particular modes.
dmICMMethod	Specifies which component, if any, will create the ICM color dictionaries. This member can have one of the following values:

Value	Meaning
DMICMMETHOD_SYSTEM	The Windows 95 System ICM library performs color matching.
DMICMMETHOD_NONE	ICM is disabled.
DMICMMETHOD_DRIVER	The driver performs color matching.
DMICMMETHOD_DEVICE	The device performs color matching.

The printer driver must provide a user interface for setting the dmICMMethod member of the DEVMODE structure. Most printer drivers support only the DMICMMETHOD_SYSTEM or DMICMMETHOD_NONE methods, although drivers for PostScript printers support all values.

dmICMIntent

Specifies the ICM setting to be used for a particular document. This information is used to select specific color-matching algorithms. This member can have one of the following values:

Value	Meaning
DMICM_SATURATE	Optimizes for color saturation. Generally used for high-contrast presentation graphics when dithering is not desired.
DMICM_CONTRAST	Optimizes for color contrast. Generally used for photographic images when dithering is desired.
DMICM_COLORMETRIC	Optimizes to match an exact given color. Used when a particular color must be respected.

The dmICMIntent member of the DEVMODE structure is used primarily by applications that do not support ICM. ICM-capable functions can establish color-matching algorithms by using the ICM functions.

dmMediaType

Specifies the type of media being printed on. The ICM library uses this information to compensate for different absorption of varying media. This member can have one of the following values:

Value	Meaning
DMICM_STANDARD	Plain paper.
DMICM_TRANSPARENCY	Transparencies.
DMICM_GLOSSY	Glossy paper.

A driver can define values for this member that are greater than the value DMMEDIA_USER.

dmDitherType

Specifies the dither brush to be used for a particular document. The choice of brush will generally affect the available colors for the device. This member can have one of the following predefined values, or a driver can define a value for this member that is greater than DMDITHER_USER.

Value	Meaning
DMDITHER_NONE	Colors will not be dithered.
DMDITHER_COARSE	Dither with a coarse brush. Perform ordered, or halftone, dithering. Suitable for scanned photographs or other images that have continuous gradations in intensity and hue.
DMDITHER_FINE	Dither with a fine brush. Perform ordered, or halftone, dithering. Suitable for scanned photographs or other images that have continuous gradations in intensity and hue.
DMDITHER_LINEART	Line art dithering, which produces well-defined borders between black, white, and gray scalings. Not suitable for scanned photographs or other images that have continuous gradations in intensity and hue.
DMDITHER_ERRORDIFFUSION	Error diffusion dithering. Can preserve more detail of an image that has continuous gradations in intensity and hue than ordered, or halftone, dithering does.
DMDITHER_GRAYSCALE	Device does gray scaling.

dmReserved1	Not used; must be zero.
dmReserved2	Not used; must be zero.

Printer drivers that support the new members in the DEVMODE structure must set DEVMODE.dmSpecVersion to 0x0400. If a driver sets DEVMODE.dmSpecVersion to this value, the driver must also meet the following requirements:

The driver must always return 0x0400 to a DeviceCapabilities function call that uses a DC_VERSION argument.
The driver must use the new DEVMODE structure definition, even if it does not use any of the new members (it should initialize them to zero).
The driver must use DrvSetPrinterData to store printer driver settings and use DrvGetPrinterData to retrieve them.
The driver must be able to handle friendly user-defined printer names, which can be any string up to 32 characters in length (including the terminating NULL character). When an application passes the driver a friendly printer name, the driver must query the registry to determine what the corresponding printer model name is. The driver can use the DrvGetPrinterData function to do this.
If the DEVMODE data retrieved from the registry is incorrect, the driver must build a default DEVMODE and merge as many member values as possible, and then update the registry. Win32 applications can use the DEVMODE structure, so the driver must update DEVMODE.dmDeviceName with the current friendly printer name.
Private DEVMODE data must contain the printer model name or some way of determining the current printer model name.
The driver does not have to contain code that writes settings to INI files since these settings are now maintained on the registry. The driver may have to contain code that reads INI files.

In addition to the requirements listed above, there are two other more detailed requirements which are described below:

The driver must handle brushes differently than in Windows 3.x.
The driver must organize the private members of the DEVMODE structure into two groups: printer-sticky members and document-sticky members.

Differences in Handling Brushes

The driver must deal with brushes differently than in Windows 3.x. After an Enable function call, GDI calls the driver RealizeObject function twice with an OBJ_BRUSH argument: the first time to get size information and the second time to realize the brush. Under Windows 3.x the driver returned only a TRUE or FALSE value on the second call. Under Windows 95, upon success, the driver must return a WORD with two or more of the following bits set:

Bit Setting	Description
PBF_SOLIDCLRBRUSH	A solid (not dithered) brush was realized.
PBF_SOLIDMONOBRUSH	A monochrome (not colored) brush was realized.
PBF_SUCCESS	Brush successfully realized.

For example, if a solid white brush was realized, for a monochrome DC the driver must return PBF_SUCCESS+PBF_SOLIDMONOBRUSH. For a color DC the driver must return PBF_SUCCESS+PBF_SOLIDCLRBRUSH. This is because a solid white brush is not dithered in either monochrome or color.

If, for example, a solid red brush was realized, for a monochrome DC the driver must return PBF_SUCCESS. This is because a red brush is dithered in monochrome. For a color DC, when a solid red brush is realized, the driver must return SUCCESS+PBF_SOLIDCLR.

Note that if the driver fails to realize the brush, it should still return FALSE.

Organizing and Grouping Private DEVMODE Members

Conceptually, a DEVMODE structure for a printer device has always followed the model of a public block of data, used by both the application and the driver, and a private block of data used only by the driver. The public portion of DEVMODE has been extended in Windows 95 to contain more information useful to the application, driver, and other system components such as the Image Color Mapper (ICM). These extensions (new structure members) are defined above.

This topic concentrates on how a driver writer should structure the private portion of the DEVMODE structure used by his or her driver. Organization of the private block of DEVMODE data is determined by the "stickiness" of members in the private data block. Stickiness in general refers to how much document formatting information can be retained when a document is printed on a different model printer than it was originally formatted for, or is printed after the printer the document was originally formatted for is physically changed (for example, an optional paper source is added or removed).

Each property represented by a member in the private portion of DEVMODE has one of two types of stickiness:

Document-sticky properties settings can be controlled by software. Paper size, paper orientation, and margin sizes are all examples of document-sticky properties. Document-sticky properties are set with AdvancedSetUpDialog, ExtDeviceMode, and ExtDeviceModePropSheet function calls.
Printer-sticky properties cannot be controlled by software. These properties can be changed only by physically changing the printer. Currently installed memory size, optional paper sources, and font cartridges are all printer-sticky properties. DEVMODE members that represent printer-sticky properties are configurable only by the ExtDeviceModePropSheet function.

Note that document-sticky property settings can be affected by changes in document-sticky property settings. The printer driver user interface must warn the user and give him or her a chance to change document-sticky properties when a printer-sticky property setting changes.

Looking at the organization of DEVMODE, all the properties represented in the public block are document-sticky. For Windows 95 printer drivers, the properties represented in the private block are a mixture of document-sticky and printer-sticky. In the private DEVMODE block, all the members representing document-sticky properties should come first, followed by all the members representing printer-sticky properties.

Many Windows 3.x printer driver designs make no attempt to segregate document-sticky and printer-sticky properties. As a result, applications that cache the DEVMODE structure as part of the document end up carrying information that the driver cannot rely on the next time the document is loaded. Drivers must ignore printer-sticky information stored with the document.

Organizing the private block if the DEVMODE structure into a layer of all document-sticky properties followed by a layer of all the printer-sticky properties gets around this problem. By setting the DEVMODE.dmDriverExtra member value to the size of the document-sticky layer, the driver can insure that applications access only document-sticky properties. The size of the DEVMODE structure used by the DrvGetPrinterData and DrvSetPrinterData functions the driver uses is the entire DEVMODE structure.

DrvGetPrinterData
    DWORD DrvGetPrinterData(LPSTR lpPrinter, LPSTR lpProfile, 
    DWORD lpType, LPBYTE lpPrinterData, DWORD cbData, 
    LPDWORD lpNeeded)

Retrieves printer driver information from the registry. Typically used to initialize the DEVMODE structure.

Returns ERROR_SUCCESS, if successful; otherwise, returns one of the following error codes: ERROR_INVALID_PARAMETER or ERROR_INVALID_DATA (for the meaning of these error codes, see the winerror.h documentation).

lpPrinter	Friendly name that identifies the printer device.
lpProfile	Name of profile from which to retrieve data. Note that setting this parameter to INT_PD_PRINTER_DEVMODE (which is defined in PRINT.H), the default DEVMODE is used. Private profile data can be used by passing the lpProfile parameter from ExtDeviceMode (it is non-NULL) as this parameter.
lpType	Type of data being retrieved. Use REG_BINARY for binary data (see the Win32 SDK for other registry data type descriptions).
lpPrinterData	Far pointer to location at which retrieved data should be written.
cbSize	Buffer size at the location pointed to by the lpPrinterData parameter.
lpNeeded	Size of buffer needed for original profile data.

Printer drivers are strongly encouraged to use DevSetPrinterData to store all printer driver settings in the registry and to avoid using INI files wherever possible. The DevGetPrinterData can be used to retrieve the settings.

If the data has the REG_SZ, REG_MULTI_SZ, or REG_EXPAND_SZ types, then the lpPrinterData and dwSize parameter byte counts must include one for the terminating NULL character.