共用方式為

IPrintOemUI：:D eviceCapabilities 方法 （prcomoem.h）

  • 發行項

IPrintOemUI::DeviceCapabilities 方法可讓使用者介面外掛程式指定自定義的裝置功能。

語法

HRESULT DeviceCapabilities(
  POEMUIOBJ poemuiobj,
  HANDLE    hPrinter,
  PWSTR     pDeviceName,
  WORD      wCapability,
  PVOID     pOutput,
  PDEVMODE  pPublicDM,
  PVOID     pOEMDM,
  DWORD     dwOld,
  DWORD     *dwResult
);

參數

poemuiobj

OEMUIOBJ 結構的呼叫端提供的指標。

hPrinter

為印表機裝置提供呼叫端的句柄。

pDeviceName

代表裝置名稱之字串的呼叫端提供的指標。

wCapability

呼叫端提供的旗標，指出方法應該傳回的信息類型。 如需旗標清單，請參閱drvDeviceCapabilities 函式 的描述。

pOutput

呼叫端提供的緩衝區指標，以接收要求的資訊。 傳回的信息類型取決於 wCapability所指定的旗標。

pPublicDM

已驗證 DEVMODEW 結構的呼叫端提供的指標。

pOEMDM

呼叫端提供的指標，指向使用者介面外掛程式的私人 DEVMODEW 結構成員。

dwOld

從印表機驅動程式的 DrvDeviceCapabilities 函式，或從另一個使用者介面外掛程式取得呼叫端提供的傳回值。 如需詳細資訊，請參閱下列一節。

dwResult

傳回值，其相依於 wCapability所指定的旗標。 如需詳細資訊，請參閱 DrvDeviceCapabilities 函式的描述和下列一節。

傳回值

方法必須傳回下列其中一個值。

傳回碼 描述
S_OK
 作業成功。
S_DEVCAP_OUTPUT_FULL_REPLACEMENT
 外掛程式打算使用 pOutput 參數針對自己的用途所指向的緩衝區。 此傳回值定義於prcomoem.h中。 如需何時使用此傳回值的詳細資訊，請參閱下列一節。
E_FAIL
 作業失敗。
E_NOTIMPL
 未實作 方法。

言論

使用者介面外掛程式的 IPrintOemUI::DeviceCapabilities 方法會執行與使用者模式列印機介面 DLL 所匯出之 DrvDeviceCapabilities 函式相同的作業類型。 方法會指定印表機所提供的功能。

您可以使用 IPrintOemUI::DeviceCapabilities 方法來先佔 Unidrv 對功能的支援，或新增印表機驅動程式未提供的功能。 驅動程式會從其 DrvDeviceCapabilities 函式內呼叫 IPrintOemUI::DeviceCapabilities。

如果 IPrintOemUI::DeviceCapabilities 方法指出對功能的自定義支援（藉由設定適當的位來回應收到的DC_FIELDS旗標），自定義程式代碼必須完全支援此功能。 完整支援通常包括傳回功能的相關信息，以回應對 IPrintOemUI::DeviceCapabilities 方法的呼叫，以及提供適當的使用者模式或內核模式程式代碼來實作功能。

如果 IPrintOemUI::DeviceCapabilities 多個使用者介面外掛程式匯出方法，則會依外掛程式指定安裝的順序呼叫方法。 每次呼叫外掛程式的 IPrintOemUI::DeviceCapabilities 方法時，其 dwOld 輸入值就是先前稱為外掛程式 IPrintOemUI::DeviceCapabilities 方法的傳回值。 對於第一個稱為 的外掛程式，dwOld 包含印表機驅動程式 DrvDeviceCapabilities 函式的傳回值。 同樣地，pOutput 所指向的緩衝區會包含先前稱為 IPrintOemUI::DeviceCapabilities 方法或 DrvDeviceCapabilities 函式所放置的任何內容。

若要讓多個使用者介面外掛程式彼此搭配運作，每個 IPrintOemUI::DeviceCapabilities 方法都必須遵守下列規則：

  • 如果使用者介面外掛程式不支援指定的功能，其 IPrintOemUI::DeviceCapabilities 方法應該只會傳回 dwResult中 dwOld 參數的內容。
  • 如果使用者介面外掛程式支援 此功能，其 IPrintOemUI::DeviceCapabilities 方法應該忽略 dwOld，以及 pOutput 所指向之緩衝區的內容。 它應該提供適合的傳回值和緩衝區內容，指出它支援指定的功能。 如果方法偵測到錯誤，它應該會在 dwResult中傳回GDI_ERROR。
  • 如果您希望使用者介面外掛程式修改 pOutput所指向之緩衝區中接收的功能資訊，其 IPrintOemUI::DeviceCapabilities 方法應該修改緩衝區內容，並在 dwResult 傳回適當的傳回值。 例如，如果 wCapability 是DC_FIELDS，則 方法應該或它必須設定的位，並將 dwOld中所設定的位設定為 ，並在 dwResult中傳回 OR 作業的結果。
  • 即使收到 dwOld 的內容GDI_ERROR，也應該遵循上述規則。
當驅動程式的 DrvDeviceCapabilities 函式使用設定DC_FIELDS旗標時，函式會呼叫所有 IPrintOemUI::DeviceCapabilities 方法，同時指定DC_FIELDS，並將所有已設定位的聯集傳回給呼叫者。

S_DEVCAP_OUTPUT_FULL_REPLACEMENT傳回值是 Windows Vista 中的新功能，同時適用於 Unidrv 和 Pscript5 使用者介面外掛程式。只有在 pOutput 參數指向的緩衝區中，外掛程式才應該使用S_DEVCAP_OUTPUT_FULL_REPLACEMENT傳回值。 當外掛程式傳回S_DEVCAP_OUTPUT_FULL_REPLACEMENT時，Unidrv 和 Pscript5 核心驅動程式都不會將數據放在 pOutput 緩衝區。 當 DEVMODEW 結構中的設定（pPublicDM 和 pOEMDM 參數所指出的設定時，可能需要傳回此值給使用者介面外掛程式，指出它應該報告與 GPD 或 PPD 檔案中指定的裝置功能數據不同。 例如，指定相片列印的 DEVMODEW 結構可能需要與 GPD 或 PPD 檔案中指定的紙張類型不同。 在這種情況下，無論 pOutput 和 dwOld 參數的值為何，外掛程式都應該傳回S_DEVCAP_OUTPUT_FULL_REPLACEMENT，而且應該將 dwResult 參數設定為想要報告的紙張類型數目。 如果 pOutput 不是 NULL，外掛程式也應該將 pOutput 所指向的緩衝區填入 pOutput 所需的一組紙張類型，而且應該將 dwResult 設定為外掛程式想要報告的紙張類型數目。

當多個使用者介面外掛程式同時作用中，其中一個外掛程式會傳回S_DEVCAP_OUTPUT_FULL_REPLACEMENT時，Unidrv 或 Pscript5 核心驅動程式會解譯此傳回值，表示外掛程式想要提供完整的取代輸出數據。 因此，核心驅動程式不會在呼叫外掛程式之前，將任何數據放入 pOutput 緩衝區中。（核心驅動程式會以為安裝指定的相同順序呼叫外掛程式。

在核心驅動程式放置在 pOutput 緩衝區的值不需要取代的情況下，外掛程式應該會傳回S_OK。 Unidrv 和 Pscript5 核心驅動程式只會辨識S_DEVCAP_OUTPUT_FULL_REPLACEMENT傳回值給使用 pOutput buffer 的裝置功能，換句話說，當 wCapability 參數 設定為下列其中一個旗標時：

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

如需建立及安裝使用者介面外掛程式的詳細資訊，請參閱 自定義Microsoft的印表機驅動程式。

要求

要求 價值
目標平臺 桌面
標頭 prcomoem.h （include Prcomoem.h）

另請參閱

DrvDeviceCapabilities

IPrintOemUI