Поделиться через

Метод 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 пользовательского интерфейса выполняет те же типы операций, что и функция DrvDeviceCapabilities, экспортируемая библиотеками DLL интерфейса принтера в режиме пользователя. Метод задает возможности, предоставляемые принтером.

Вы можете использовать метод IPrintOemUI::DeviceCapabilities для подготовки поддержки Unidrv для возможности или добавления возможности, которую драйвер принтера не предоставляет. Драйвер вызывает IPrintOemUI::DeviceCapabilities из функции DrvDeviceCapabilities.

Если метод IPrintOemUI::DeviceCapabilities указывает настраиваемую поддержку возможности (задав соответствующие биты в ответ на полученный флаг DC_FIELDS), настраиваемый код должен полностью поддерживать возможности. Полная поддержка обычно включает возврат сведений о возможности в ответ на вызовы метода IPrintOemUI::DeviceCapabilities, а также предоставление соответствующего пользовательского режима или кода в режиме ядра для реализации возможности.

Если методы IPrintOemUI::DeviceCapabilities экспортируются несколькими подключаемыми модулями пользовательского интерфейса, методы вызываются в том порядке, в который указываются подключаемые модули для установки. Каждый раз, когда вызывается метод IPrintOemUI::DeviceCapabilities подключаемого модуля, его dwOld входное значение является возвращаемым значением из ранее называемого метода IPrintOemUI::DeviceCapabilities подключаемого модуля. Для первого подключаемого модуля dwOld содержит возвращаемое значение из функции драйвера принтера DrvDeviceCapabilities. Аналогичным образом буфер, на который указывает pOutput, содержит любое содержимое, размещенное там ранее вызываемым методом IPrintOemUI::DeviceCapabilitiesили функцией DrvDeviceCapabilities.

Для работы нескольких подключаемых модулей пользовательского интерфейса в сочетании друг с другом каждый метод IPrintOemUI::DeviceCapabilities должен соответствовать следующим правилам:

  • Если подключаемый модуль пользовательского интерфейса не поддерживает указанную возможность, его метод IPrintOemUI::DeviceCapabilities должен только вернуть содержимое параметра dwOld dwOld в dwResult.
  • Если подключаемый модуль пользовательского интерфейса поддерживает возможность, его метод IPrintOemUI::DeviceCapabilities должен игнорировать dwOld и содержимое буфера, на который указывает pOutput. Он должен предоставить возвращаемое значение и содержимое буфера, подходящее для указания того, что она поддерживает указанную возможность. Если метод обнаруживает ошибку, он должен возвращать GDI_ERROR в dwResult.
  • Если требуется подключаемый модуль пользовательского интерфейса для изменения сведений о возможностях, полученных в буфере, на который указывает pOutput, его метод IPrintOemUI::DeviceCapabilities должен изменить содержимое буфера и вернуть соответствующее возвращаемое значение в dwResult. Например, если wCapability DC_FIELDS, метод должен ИЛИ биты, которые необходимо задать с битами, заданными в dwOld, и возвращать результат операции OR в dwResult.
  • Предыдущие правила следует соблюдать, даже если полученное содержимое dwOld GDI_ERROR.
Когда функция драйвера DrvDeviceCapabilities вызывается с набором флагов DC_FIELDS, функция вызывает все методы IPrintOemUI::DeviceCapabilities, а также указывает DC_FIELDS и возвращает объединение всех наборов битов вызывающей стороны.

Возвращаемое значение S_DEVCAP_OUTPUT_FULL_REPLACEMENT новое в Windows Vista и применяется как к подключаемым модулям пользовательского интерфейса Unidrv, так и к Pscript5. Подключаемый модуль должен использовать возвращаемое значение S_DEVCAP_OUTPUT_FULL_REPLACEMENT только в том случае, если требуется полный контроль над тем, что размещено в буфере, на который указывает параметр pOutput. Ни модуль Unidrv, ни основной драйвер Pscript5 не будут размещать данные в буфере pOutput, когда подключаемый модуль возвращает S_DEVCAP_OUTPUT_FULL_REPLACEMENT. Подключаемый модуль может потребоваться вернуть это значение, если параметр в структуре 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 распознают S_DEVCAP_OUTPUT_FULL_REPLACEMENT возвращаемое значение только для возможностей устройств, использующих pOutput буфера, иными словами, если параметр wCapability имеет одно из следующих флагов:

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

Дополнительные сведения о создании и установке подключаемых модулей пользовательского интерфейса см. в настройке драйверов принтера Майкрософт.

Требования

Требование Ценность
целевая платформа Настольный
заголовка prcomoem.h (include Prcomoem.h)

См. также

DrvDeviceCapabilities

IPrintOemUI