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 所指向的緩衝區，而且應該將 dwResult 設定為外掛程式想要報告的紙張類型數目。

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

如果核心驅動程式在 pOutput 緩衝區中放置的值不需要取代，外掛程式應該會傳回S_OK。 Unidrv 和 Pscript5 核心驅動程式只會針對使用 pOutput 緩衝區的裝置功能辨識S_DEVCAP_OUTPUT_FULL_REPLACEMENT傳回值，換句話說，當 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 (包括 Prcomoem.h)

另請參閱

DrvDeviceCapabilities

IPrintOemUI