DrvEnablePDEV 函数 (winddi.h)

项目
08/27/2023

DrvEnablePDEV 函数将物理设备特征的说明返回到 GDI。

语法

DHPDEV DrvEnablePDEV(
  [in]           DEVMODEW *pdm,
  [in]           LPWSTR   pwszLogAddress,
                 ULONG    cPat,
  [in, optional] HSURF    *phsurfPatterns,
                 ULONG    cjCaps,
  [out]          ULONG    *pdevcaps,
                 ULONG    cjDevInfo,
  [out]          DEVINFO  *pdi,
                 HDEV     hdev,
  [in]           LPWSTR   pwszDeviceName,
                 HANDLE   hDriver
);

参数

[in] pdm

指向包含驱动程序数据的 DEVMODEW 结构的指针。

对于支持 Windows NT 4.0 的驱动程序，当 GDI 调用时， DrvEnablePDEV 应返回硬件的默认模式，并将以下 DEVMODEW 成员设置为零： dmBitsPerPel、 dmPelsWidth、 dmPelsHeight 和 dmDisplayFrequency。

[in] pwszLogAddress

对于打印机驱动程序，指向逻辑地址字符串，该字符串是驱动程序正在写入的位置的用户名称。示例包括“LPT1”或“我的打印机”。

显示驱动程序应忽略此参数。

cPat

对于打印机驱动程序，指定 phsurfPatterns 指向的缓冲区中的图面句柄数。驱动程序无法访问超出缓冲区末尾的内存。

显示驱动程序应忽略此参数。

[in, optional] phsurfPatterns

显示驱动程序应忽略此参数。

对于打印机驱动程序，指向驱动程序将使用表示标准填充图案的图面图柄填充的缓冲区。必须按顺序定义以下模式：

模式	说明
HS_HORIZONTAL	水平阴影。
HS_VERTICAL	垂直阴影。
HS_FDIAGONAL	从左到右) (45 度向上的阴影。
HS_BDIAGONAL	向下 45 度阴影 (从左到右) 。
HS_CROSS	水平和垂直交叉阴影。
HS_DIAGCROSS	45 度交叉切线。

注意以前版本的驱动程序开发工具包 (DDK) 减少了需要驱动程序支持的默认阴影模式的数量。因此，HS_DDI_MAX（通常由驱动程序用来声明模式数组的大小）已减少。

GDI 使用其中一个图面调用 DrvRealizeBrush ，以实现具有标准图案的画笔。

对于光栅设备，每个表面都必须是单色 (1 位/像素) GDI 位图。在设备图面上写入时，设备驱动程序应选择最类似于标准模式的模式。

永远不需要 GDI 在矢量设备的支持例程中使用这些画笔。因此，表面可以是 DrvRealizeBrush 识别为标准模式的设备支持的表面。

cjCaps

指定 pdevcaps 指向的缓冲区的大小。驱动程序不得访问超过缓冲区末尾的内存。

[out] pdevcaps

指向 GDIINFO 结构的指针，该结构将用于描述设备功能。 GDI 对调用 DrvEnablePDEV 的此结构进行零初始化。

cjDevInfo

指定 pdi 指向的 DEVINFO 结构中的字节数。驱动程序在 DEVINFO 中修改的字节数不应超过此字节数。

[out] pdi

指向 DEVINFO 结构的指针，该结构描述驱动程序和物理设备。驱动程序应仅更改它所理解的成员。 GDI 在调用 DrvEnablePDEV 之前用零填充此结构。

hdev

GDI 提供给设备的句柄。此句柄必须用作某些 GDI 回调（如 EngGetDriverName）的输入。

[in] pwszDeviceName

指向以 null 结尾的字符串的指针，该字符串是设备的用户可读名称。

hDriver

输出设备的句柄。对于显示驱动程序，这是显示设备句柄。对于打印机驱动程序，此参数应在调用后台处理程序时用作打印机的句柄。

返回值

返回值是 PDEV 的句柄，如果函数成功，该句柄标识已启用的设备。也就是说， DrvEnablePDEV 在成功后返回驱动程序定义的专用设备实例信息的句柄。否则，它将返回 NULL。

注解

图形设备驱动程序可能支持多个附加到不同逻辑地址的物理设备。驱动程序还必须支持同时使用不同的绘图图面。

DrvEnablePDEV 的用途如下：

通知 GDI 设备的物理特征。
创建描述当前设备实例的专用 PDEV 结构， (基于收到的 DEVMODE 结构和设备名称) 。

当 GDI 随后调用其他图形 DDI 函数时，它会提供 DrvEnablePDEV 返回的句柄作为输入 (通常在 SURFOBJ 结构中) ，以便驱动程序可以识别设备实例。

单个逻辑设备可以管理多个 PDEV，这些 PDEV 可通过以下各项进行区分：

硬件类型 - 单个设备驱动程序可能支持“LaserWhiz”、“LaserWhiz II”和“LaserWhiz Super”。
逻辑地址 -- 单个设备驱动程序可以支持附加到“LPT1”、“COM2”、“\SERVER1\PSLAZER”等的打印机。可以同时支持多个 VGA 显示器的显示驱动程序可能会根据端口号对其进行区分;例如，0x3CE 或 0x2CE。
图面 - 打印机驱动程序可以同时处理两个打印作业。这两个图面表示将打印的两页。同样，显示设备驱动程序可能支持同一设备上的两个桌面。

收到对此函数的调用时，驱动程序必须分配内存以支持 PDEV。但是，在 GDI 调用 DrvEnableSurface 之前，不需要支持实际表面。

如果设备图面需要分配位图，则无需在需要之前进行这些分配。尽管应用程序通常在实际写入设备之前很久就请求设备信息，但等待分配资源（如大型位图）可以节省内存。

在调用此函数之前，GDI 对 phsurfPatterns 指向的 缓冲区进行零初始化。

图形驱动程序需要 DrvEnablePDEV。