The DEVMODEW Structure

The DEVMODEW structure is the Unicode version of the DEVMODE structure, which is described in the Microsoft Windows SDK documentation. (The 'W' suffix on DEVMODEW stands for "wide", or Unicode characters.) While applications can use either structure, drivers are required to use the DEVMODEW structure rather than the DEVMODE structure.

Public and Private Members

Immediately following a DEVMODEW structure's defined members (often referred to as its public DEVMODEW members), there can be a set of driver-defined members (its private DEVMODEW members). The following figure shows the public section (the actual DEVMODEW structure itself) and the private section.

Normally, the private members are used only by printer drivers. The driver supplies the size, in bytes, of this private area in the dmDriverExtra member. Driver-defined private members are for exclusive use by the driver.

For printer drivers, the DEVMODEW structure is used to specify user choices for a print document. It is also used to specify default values of these choices for printers, such as the number of copies to print, paper size, and other attributes. For display devices, the DEVMODEW structure specifies display attributes such as the number of bits per pixel, pixel dimensions, and display frequency.

Initializing a DEVMODEW Structure

Depending on whether it is to be used by a display driver or by a printer driver, a DEVMODEW structure is initialized in two different ways.

• Display driver DEVMODEW initialization

  A display driver's DrvGetModes entry point initializes all members of the DEVMODEW structure to zero. DrvGetModes then copies the name of the display driver DLL to the dmDeviceName member, fills in the dmSpecVersion and dmDriverVersion members with the version of the DEVMODEW structure, and copies display attribute information to the appropriate members.

• Printer driver DEVMODEW initialization

  When an application makes a call to either DocumentProperties (a printer interface DLL function that is described in the Microsoft Windows SDK documentation) or DrvDocumentPropertySheets (an NT-based operating system graphics DDI), a DEVMODEW structure is created with default values. An application is then free to modify any of the public DEVMODEW members. After any changes, the application should then make a second call to the same function it called before, in order to merge the changed members with those of the driver's internal DEVMODEW structure. The second call is necessary since some changes may not work correctly; the printer driver must be called to correct the DEVMODEW structure. When the document is about to be printed, the application passes the merged DEVMODEW structure to CreateDC (described in the Microsoft Windows SDK documentation), which passes it on to the DrvEnablePDEV DDI. At that time, the driver's rendering DLL validates the DEVMODEW structure and makes repairs, if necessary, before carrying out the print job.

Using a DEVMODEW Structure

Several APIs and graphics DDIs use the information in the DEVMODEW structure for such purposes as printing, querying device capabilities, showing user interface, and others. For example, DrvConvertDevMode is a print spooler graphics DDI that translates the DEVMODEW structure from one operating system version to another. This might be necessary if a printer driver gets a DEVMODEW structure from another machine that is running on a different operating system version.

Modifying a DEVMODEW Structure

Applications and drivers are free to ask for a DEVMODEW structure and modify its public part directly. Only drivers, however, are permitted to modify the private DEVMODEW structure members.

In order to modify private DEVMODEW structure members, a driver must first determine the offset of the beginning of the private data. Given a pointer to the beginning of this structure, and the dmSize member, which holds the size of the public portion of the structure, the beginning of the private portion can be found. The following example shows how to initialize a pointer to the beginning of the private section. In this example, pdm points to the beginning of the DEVMODEW structure.

PVOID pvDriverData = (PVOID)  (((BYTE *) pdm) + (pdm -> dmSize));

Printer Driver/Display Driver DEVMODEW Differences

The DEVMODEW structure members fall into three categories:

• Members used only by printer drivers

• Members used only by display drivers

• Members used by both printer and display drivers

The following table lists several public DEVMODEW members that are used only by printer drivers:

The next table lists several public DEVMODEW members that are used only by display drivers:

The third table lists several public DEVMODEW members that are used by both printer and display drivers: