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.