Метод 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 и в следующем разделе Примечания.
Возвращаемое значение
Метод должен возвращать одно из следующих значений.
| Код возврата | Описание |
|---|---|
|
Операция успешно выполнена. |
|
Подключаемый модуль намерен использовать буфер, на который указывает параметр pOutput , для собственных целей. Это возвращаемое значение определяется в prcomoem.h. Дополнительные сведения об использовании этого возвращаемого значения см. в следующем разделе Примечания. |
|
Операция не удалась. |
|
Метод не реализован. |
Комментарии
Метод подключаемого модуля 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 в dwResult. -
Если подключаемый модуль пользовательского интерфейса поддерживает возможность, его
IPrintOemUI::DeviceCapabilitiesметод должен игнорировать dwOld и содержимое буфера, на который указывает pOutput. Он должен предоставлять возвращаемое значение и содержимое буфера, соответствующие указаниям на то, что он поддерживает указанную возможность. Если метод обнаруживает ошибку, он должен вернуть GDI_ERROR в dwResult. -
Если требуется, чтобы подключаемый модуль пользовательского интерфейса изменял сведения о возможностях, полученные в буфере, на который указывает pOutput, его
IPrintOemUI::DeviceCapabilitiesметод должен изменить содержимое буфера и вернуть соответствующее возвращаемое значение в dwResult. Например, если wCapability имеет DC_FIELDS, метод должен или биты, которые ему необходимо задать с битами, заданными в dwOld, и возвращать результат операции OR в dwResult. - Приведенные выше правила должны соблюдаться, даже если полученное содержимое dwOld GDI_ERROR.
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 (включая Prcomoem.h) |