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