DrvEnablePDEV

DHPDEV DrvEnablePDEV(

IN DEVMODEW *pdm,
IN LPWSTR pwszLogAddress,
IN ULONG cPat,
OUT HSURF *phsurfPatterns,
IN ULONG cjCaps,
OUT ULONG *pdevcaps,
IN ULONG cjDevInfo,
OUT DEVINFO *pdi,
IN HDEV hdev,
IN LPWSTR pwszDeviceName,
IN HANDLE hDriver
);

DrvEnablePDEV creates a logical representation of a physical device upon which the driver can associate a drawing surface.

Parameters

pdm

Points to a DEVMODEW structure that contains driver data.

pwszLogAddress

Points to the logical address string that is the user’s name for the location to which the driver is writing. Examples include “LPT1” or “My Printer.”

cPat

Specifies the number of standard patterns, equal to the number of HSURF structures in the buffer pointed to by phsurfPatterns. The driver cannot access memory beyond the end of the buffer.

phsurfPatterns

Points to a buffer that the driver will fill with surfaces representing the standard fill patterns. The following patterns must be defined in order:

Pattern	Description
HS_HORIZONTAL	Horizontal hatch.
HS_VERTICAL	Vertical hatch.
HS_FDIAGONAL	45-degree upward hatch (left to right).
HS_BDIAGONAL	45-degree downward hatch (left to right).
HS_CROSS	Horizontal and vertical cross hatch.
HS_DIAGCROSS	45-degree crosshatch.

Note      The number of default hatch patterns that require driver support was reduced in a previous version of the DDK. Consequently, HS_DDI_MAX, typically used by drivers to declare the size of the pattern array, was reduced.

GDI calls DrvRealizeBrush with one of these surfaces to realize a brush with a standard pattern.

Each of these surfaces must be a monochrome (1 bit per pixel) GDI bitmap for raster devices. The device driver should choose patterns that will look most like standard patterns when written on the device surface.

GDI is never required to use these brushes in support routines for a vector device. Therefore, surfaces can be device-supported surfaces that DrvRealizeBrush recognizes as standard patterns.

cjCaps

Specifies the size of the buffer pointed to by pdevcaps. The driver must not access memory beyond the end of the buffer.

pdevcaps

Points to a GDIINFO structure that will be used to describe device capabilities. GDI zero-initializes this structure before the application calls DrvEnablePDEV.

cjDevInfo

Specifies the number of bytes in the DEVINFO structure pointed to by pdi. The driver should modify no more than this number of bytes in the DEVINFO.

pdi

Points to the DEVINFO structure, which describes the driver and the physical device. The driver should only alter the members it understands. GDI fills this structure with zeros before a call to DrvEnablePDEV.

hdev

Points to a fully-qualified path name of a data file that the driver examines to determine rendering methods for the device. This parameter is ignored for display drivers.

pwszDeviceName

Points to a zero-terminated string that is the user-readable name of the device.

hDriver

Identifies the kernel-mode driver that supports the device. For a printer driver this parameter should be used as a handle to the printer when calling the spooler.

Return Value

The return value is a handle to the PDEV that identifies the enabled device if the function is successful. Otherwise, it is zero, and an error code is logged.

Comments

The device driver represents a logical device, called a PDEV. The PDEV is managed by GDI. A single logical device can manage several PDEVs that can be differentiated by the following:

1. Type of hardware. A single device driver might support “LaserWhiz,” “LaserWhiz II,” and “LaserWhiz Super.”

2. Logical address. A single device driver can support printers attached to “LPT1,” “COM2,” “\SERVER1\PSLAZER,” and so forth. A display driver that can support more than one VGA display simultaneously might differentiate them according to port numbers; for example, 0x3CE or 0x2CE.

3. Surfaces. A printer driver can process two print jobs simultaneously. The two surfaces represent two pages that will be printed. Similarly, a display device driver might support two desktops on the same device.

Each call to DrvEnablePDEV creates another device that is used with a distinct surface. The DEVMODEW structure indicates the type of hardware requested. GDI manages the logical address for printers and other hard copy output devices. The spooler service WritePrinter (a Win32 function) directs output to the proper destination. Displays and input devices either know their logical address implicitly or get it from the private section of the DEVMODEW structure. For more information, see the Win32 SDK.

When receiving a call to this function, the driver must allocate the memory to support the PDEV. However, the actual surface need not be supported until GDI calls DrvEnableSurface.

If a device surface requires a bitmap to be allocated, these allocations need not be made until needed. Although applications often request device information long before actually writing to the device, waiting to allocate resources, such as large bitmaps, can conserve memory.

GDI zero-initializes the buffer pointed to by phsurfPatterns before calling this function.

DrvEnablePDEV is required for graphics drivers.

See Also

DEVINFO, DEVMODEW, DrvEnableSurface, DrvRealizeBrush, EngCreatePalette, GDIINFO