drvConvertDevMode 函式 (winddiui.h)

發行項
03/01/2024

印表機介面 DLL 的 DrvConvertDevMode 函式會將印表機的 DEVMODEW 結構從一個版本轉換成另一個版本。

語法

BOOL DrvConvertDevMode(
  [in]      LPTSTR   pPrinterName,
  [in]      PDEVMODE pdmIn,
  [out]     PDEVMODE pdmOut,
  [in, out] PLONG    pcbNeeded,
  [in]      DWORD    fMode
);

參數

[in] pPrinterName

呼叫端提供的印表機名稱字串指標。如需此參數的詳細資訊，請參閱下列一節。

[in] pdmIn

呼叫端提供的輸入 DEVMODEW 結構的指標。如果 fMode 是CDM_DRIVER_DEFAULT，則此指標為 NULL。

[out] pdmOut

呼叫端提供的緩衝區指標，以接收輸出 DEVMODEW 結構。如果 fMode CDM_CONVERT緩衝區包含輸入時，有效的 DEVMODEW 結構會指出目標驅動程式版本。

[in, out] pcbNeeded

呼叫端提供的緩衝區指標大小，以位元組為單位，由 pdmOut 指向。在輸出中，印表機介面 DLL 應該以轉換之 DEVMODEW 結構的實際大小覆寫收到的大小值。如果接收的緩衝區太小，印表機介面 DLL 應該以所需的緩衝區大小覆寫收到的大小值。

[in] fMode

呼叫端提供的位旗標，指出要執行的作業類型。這可以是下列其中一個旗標：

CDM_CONVERT

函式應該會將 pdmIn) 所指向 (的輸入 DEVMODEW 結構內容轉換成新的 DEVMODEW 結構，並將結果放在 pdmOut 所指向的 DEVMODEW 結構中。 pdmOut 所指向之已接收輸出 DEVMODEW 結構的初始內容 (應該使用) 來判斷輸出版本。

CDM_CONVERT351

函式應該轉換 pdmIn) 所指向的輸入 DEVMODEW 結構內容 (，建立與 Windows NT 3.51 相容的輸出 DEVMODEW 結構，並將結果放在 pdmOut 所指向的 DEVMODEW 結構中。

如果驅動程式不支援 Windows NT 3.51 的 DEVMODEW 結構，函式應該會將輸入 DEVMODEW 轉換為目前的版本。

CDM_DRIVER_DEFAULT

函式應該將目前版本的預設 DEVMODEW 結構複製到 pdmOut 所指向的緩衝區。

傳回值

如果作業成功，函式應該會傳回 TRUE;否則，它應該呼叫 SetLastError 來設定錯誤碼，並傳回 FALSE。

備註

在用戶端/伺服器環境中，當伺服器 (多任務緩衝處理器) 執行另一個版本時，用戶端可能會執行一個版本的操作系統或列印機驅動程式，這表示列印機的 DEVMODEW 結構定義在用戶端與伺服器之間可能會不一致。 DrvConvertDevMode 函式必須能夠執行從印表機的 DEVMODEW 結構版本到另一個版本的轉換。

從一個 DEVMODEW 版本轉換成另一個 DEVMODEW 版本時，必須包含公用和私人 DEVMODEW 成員。

pPrinterName 所指向的印表機名稱可用來做為 OpenPrinter 函式的輸入自變數， (Microsoft Windows SDK 檔) 中所述，當收到CDM_DRIVER_DEFAULT旗標時，可以呼叫以取得預存的預設值。請注意，在呼叫 OpenPrinter 之前，不得以任何方式修改印表機名稱字串。此外， OpenPrinter 的呼叫必須位於用來呼叫 DrvConvertDevMode的相同線程中。

如果適用) 指向有效的 DEVMODEW 結構，函式應該確認 pdmIn 和 pdmOut (。如果沒有，函式應該呼叫 SetLastError (ERROR_INVALID_PARAMETER) 並傳回 FALSE。如果 azureneeded 所指定的輸出 DEVMODEW 大小太小，驅動程式應該以所需的緩衝區大小覆寫 其提供的大小 值、呼叫 SetLastError (ERROR_INSUFFICIENT_BUFFER) ，並傳回 FALSE。

DrvConvertDevMode 函式會在多任務緩衝處理程式的內容中執行，因此不得顯示使用者介面。

使用 pdmOut 參數中的 NULL DEVMODEW 結構指標呼叫 DrvConvertDevMode 以取得緩衝區大小時，驅動程式預期會將最後一個錯誤設定為 ERROR_INSUFFICIENT_BUFFER。如果最後一個錯誤未設定為此值，多任務緩衝處理程式會假設發生一般錯誤。

規格需求

需求	值
目標平台	桌面
標頭	winddiui.h (包含Winddiui.h)