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 使用下列DEVMODEW成員呼叫硬體時，DrvEnablePDEV應該傳回硬體的預設模式：dmBitsPerPel、dmPelsWidth、dmPelsHeight和dmDisplayFrequency。

[in] pwszLogAddress

針對印表機驅動程式，指向邏輯位址字串，該字串是驅動程式所寫入位置的使用者名稱。範例包括「LPT1」或「My Printer」。

顯示驅動程式應該忽略此參數。

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 裝置的實體特性。
若要根據收到的 DEVMODE 結構和裝置名稱) ，建立描述目前裝置實例 (的私人 PDEV 結構。

當 GDI 後續呼叫其他圖形 DDI 函式時，它會提供 DrvEnablePDEV 傳回的控制碼作為輸入 (通常位於 SURFOBJ 結構內，) ，讓驅動程式可以識別裝置實例。

單一邏輯裝置可以管理數個 PDEV，可由下列專案區分：

硬體類型 -- 單一設備磁碟機可能支援「LaserWhiz」、「LaserWhiz II」和「LaserWhiz Super」。
邏輯位址 -- 單一設備磁碟機可以支援連結至「LPT1」、「COM2」、「\SERVER1\PSLAZER」等的印表機。可同時支援多個 VGA 顯示器的顯示驅動程式可能會根據埠號碼區分它們;例如，0x3CE或0x2CE。
Surface -- 印表機驅動程式可以同時處理兩個列印工作。這兩個表面代表要列印的兩頁。同樣地，顯示裝置磁碟機可能支援相同裝置上的兩個桌面。

收到此函式呼叫時，驅動程式必須配置記憶體以支援 PDEV。不過，在 GDI 呼叫 DrvEnableSurface之前，不需要支援實際表面。

如果裝置表面需要配置點陣圖，則必須先進行這些配置，才能進行這些配置。雖然應用程式通常會在實際寫入裝置之前要求裝置資訊，但等候配置資源，例如大型點陣圖，可以節省記憶體。

GDI 會先初始化 phsurfPatterns 指向的緩衝區，再呼叫此函式。

圖形驅動程式需要DrvEnablePDEV。