通过

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 参数指向）中的设置指示用户界面插件时，可能需要返回此值。 例如，指定照片打印的 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 （include Prcomoem.h）

另请参阅

DrvDeviceCapabilities

IPrintOemUI