Пакеты свойств драйвера принтера версии 4

Статья
03/08/2023

Внимание

Современная платформа печати — это предпочтительный способ взаимодействия с принтерами Windows. Рекомендуется использовать драйвер класса "Входящие" Microsoft IPP вместе с приложениями поддержки печати (PSA), чтобы настроить возможности печати в Windows 10 и 11 для разработки устройств принтера.

Дополнительные сведения см. в статье "Современная платформа печати" и руководство по проектированию приложений поддержки печати.

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

Эти пакеты свойств позволяют создавать пользовательские свойства и определения признаков в настраиваемом пользовательском интерфейсе, а затем использовать процесс отрисовки. Все пакеты свойств предоставляются с помощью интерфейса IPrinterScriptablePropertyBag в JavaScript или с помощью интерфейса IPrinterPropertyBag в других средах.

В следующей таблице представлен обзор использования различных компонентов для получения объекта контейнера свойств из разных частей драйвера печати версии 4.

Компонент	Description
Скрипт ограничения JavaScript	Пакеты свойств драйверов и очередей передаются в скрипты ограничений JavaScript с помощью параметра scriptContext. Этот параметр имеет тип IPrinterScriptContext и содержит дочерние элементы: DriverProperties — относится к контейнеру свойств драйвера. QueueProperties — относится к контейнеру свойств очереди. UserProperties — контейнер свойств пользователя. Контейнер свойств DEVMODE передается в методы преобразования DEVMODE <—> PrintTicket в качестве параметра devModeProperties (который имеет тип IPrinterScriptablePropertyBag). Он недоступен для других методов.
USB Bidi JavaScript	Пакеты свойств драйвера и очереди передаются в скрипты JavaScript USB Bidi с помощью параметра scriptContext. Этот параметр имеет тип IPrinterScriptContext и содержит дочерние элементы: DriverProperties — относится к контейнеру свойств драйвера. QueueProperties — относится к контейнеру свойств очереди.
Приложение расширения принтера	Все пакеты свойств передаются в рамках параметра IPrinterExtensionEventArgs обработчику OnDriverEventEvent. Все они имеют тип IPrinterPropertyBag. Они указаны следующим образом: DriverProperties — относится к контейнеру свойств драйвера. UserProperties — контейнер свойств пользователя. PrinterQueue.GetProperties()— относится к контейнеру свойств очереди
Приложение устройства UWP	Все пакеты свойств передаются во время активации с помощью объекта IPrinterExtensionContext. Они указаны следующим образом: DriverProperties — относится к контейнеру свойств драйвера. UserProperties — контейнер свойств пользователя. PrinterQueue.GetProperties()— относится к контейнеру свойств очереди
Фильтр отрисовки XPS	Фильтры XPS могут получить доступ к контейнеру свойств драйвера из контейнера свойств конвейера печати с помощью имени свойства DriverPropertyBag или определенного значения, XPS_FP_PROPERTY_BAG из filterpipeline.h. Ниже приведены сведения о DriverPropertyBag: Тип свойства: VT_UNKNOWN Описание: указатель на интерфейс IUnknown. Вызовите QueryInterface, чтобы получить указатель на интерфейс IPrinterPropertyBag в контейнер свойств драйвера. Фильтры XPS могут получить доступ к контейнеру свойств очереди из контейнера свойств конвейера печати с помощью имени свойства QueuePropertyBag или определенного значения, XPS_FP_QUEUE_PROPERTY_BAG из filterpipeline.h. Ниже приведены сведения о QueuePropertyBag: Тип свойства: VT_UNKNOWN Описание: указатель на интерфейс IUnknown. Вызов queryInterface для получения указателя на интерфейс IPrinterPropertyBag в контейнер свойств очереди.

В реализации JavaScript пакеты свойств передаются в качестве параметров. В приложениях расширения принтера пакеты свойств передаются как члены аргумента события, используемого для запуска приложения.

Методы доступа к контейнерам свойств, предоставляемые интерфейсами COM IPrinterQueue, IPrinterExtensionContext и IPrinterExtensionEventArgs, а также методы доступа к контейнерам свойств в реализации Javascript вызывают исключение, если контейнер свойств не указан или не найден. Кроме того, при запросе отдельных свойств в интерфейсе IPrinterPropertyBag будут возникать исключения, если свойство не найдено. Чтобы избежать сбоя, если свойство недоступно, следует использовать инструкцию catch.

Контейнер свойств драйвера

Контейнер свойств драйвера — это хранилище данных для драйверов для предопределений свойств или больших двоичных объектов данных для использования драйвером только для чтения. Его можно указать с помощью директивы PropertyBag в файле манифеста версии 4 и не может быть изменено во время выполнения.

Пакет драйверов Windows включает в себя проект шаблона для контейнера свойств драйвера. Контейнер свойств драйвера — это скомпилированный двоичный большой двоичный объект. Visual Studio включает шаблон для создания скомпилированного контейнера свойств драйвера. XML-файл, созданный для этого шаблона, не является контейнером свойств, а скомпилированным результатом этого шаблона является файл контейнера свойств, который должен быть указан в файле манифеста версии 4.

Контейнер свойств пользователя

Контейнер свойств пользователя позволяет партнерам хранить параметры в локальном контексте компьютера для каждого пользователя. Этот контейнер свойств хорошо подходит в качестве механизма хранения для пользовательских предпочтений, таких как "Не показывать это снова". Этот контейнер свойств не управляется администраторами и не синхронизируется между клиентом и сервером во время общего доступа к принтерам. Контейнер свойств пользователя устанавливается только во время выполнения и доступен только для расширений принтера, приложений устройств UWP и ограничений JavaScript.

Так как ограничения JavaScript также могут вызываться вне контекста пользователя во время десполиирования, контейнер свойств пользователя в настоящее время недоступен, и Windows вернет HRESULT_FROM_WIN32(ERROR_NOT_FOUND).

Контейнер свойств DEVMODE

Контейнер свойств DEVMODE используется для упорядочивания содержимого в частном разделе структуры DEVMODE. Во время вызовов ConvertPrintTicketToDevMode JavaScript вызывается для заполнения содержимого контейнера свойств DEVMODE. Во время вызовов ConvertDevModeToPrintTicket JavaScript вызывается для чтения сохраненных параметров из контейнера свойств DEVMODE и сохранения их обратно в PrintTicket.

Этот контейнер свойств ограничен размером менее 60 КБ (точная сумма зависит от размера выделенных разделов DEVMODE), так как она должна быть сериализована в структуру DEVMODE, чтобы избежать потери данных в некоторых сценариях. Точный размер зависит от драйвера, так как он определяется размером общедоступного раздела DEVMODE и частным разделом, управляемым модулем конфигурации.

Пакет свойств DEVMODE использует XML-файл, чтобы указать элементы контейнера свойств и использовать интерфейсы API convertPrintTicketToDevMode и convertDevModeToPrintTicket для обработки преобразований. Файл сопоставления XML DEVMODE должен быть указан в манифесте версии 4 с помощью директивы DevModeMap.

В следующем фрагменте кода показан пример XML сопоставления пакета свойств DEVMODE.

<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns="https://schemas.microsoft.com/windows/2011/08/printing/devmodemap">
  <Property Name="FabrikamAccountCode">
    <String Length="32"></String>
  </Property>  
</Properties>

На следующем снимке экрана показана XML-схема сопоставления пакета свойств DEVMODE, и ее можно найти по следующему пути в папке установки WDK: \Include\um\printerdriverdevmodemap.xsd.pr

Сопоставление xml-схемы пакета свойств devmode.

XML-файлы для сопоставления контейнера свойств DEVMODE проверяются средством INFGate.

Контейнер свойств очереди

Контейнер свойств очереди хранит параметры конфигурации очереди, включая формы для сопоставления области и конфигурацию свойств принтера, таких как параметры установки. Определяемые драйвером свойства и свойства принтера настраиваются в PowerShell, в то время как форма для сопоставления области настраивается в пользовательском интерфейсе свойств принтера. Расширения принтера не могут изменять какие-либо из значений свойств.

Контейнер свойств очереди создается автоматически для многих драйверов печати версии 4, но драйверы также могут предоставлять дополнительные свойства для настройки с помощью XML-файла. Этот XML-файл не должен компилироваться с помощью средства пакета свойств драйвера. Пакеты свойств очереди доступны для принтеров, поддерживаемых драйверами печати версии 4, которые выполняют одно из следующих действий:

Указание нескольких лотков, OR
Укажите параметры установки в файле GPD или PPD, OR
Укажите контейнер свойств очереди в манифесте драйвера с помощью директивы QueueProperties.

Администраторы настраивают пакеты свойств очереди с помощью PowerShell. Следующие команды позволяют (командлеты) являются дочерними элементами объекта принтера, который можно получить с помощью командлета Get-Printer.

Имя командлета	Description
Get-PrinterProperty -printerName <printerName> -name <propertyName*>	Извлекает одно или несколько свойств (-name поддерживает глоббинг).
Set-PrinterProperty -inputObject printerPropertyObject <>	Изменяет свойство очереди печати с помощью сохраненного принтераPropertyObject.
Set-PrinterProperty -printerName printerName> <-PropertyName propertyName <->Value value <>	Изменяет свойство, указанное в указанном значении.

Параметры установки

Эти параметры, например, состояние дуплексера, будет предоставляться в контейнер свойств очереди в виде отдельных свойств. Каждое свойство будет называться следующим образом, где имя функции основано на имени функции из GPD или PPD-файла драйвера:

Config:<feature name>

Например: Config:DuplexUnit

Значение свойства — это имя ключевого слова для параметра, выбранного администратором. Например, установлено. Параметры установки можно изменять с помощью того же командлета Set-PrinterProperty, который используется для свойств очереди.

Начиная с Windows 8.1, пользователь с правами администратора или пользователь, создавший очередь печати, может изменить параметры установки и параметры конфигурации для контейнера свойств очереди из приложения устройства UWP.

Сопоставление области с областью

Для принтеров с драйвером печати версии 4 и несколькими полями сопоставления "форма для области" предоставляются через контейнер свойств очереди в свойстве FormTrayTable.

Это свойство отформатировано как строка, завершающая значение NULL, содержащая пары формата <tray name>, <form name>, , в котором имя формы является одним из следующих:

Если размер бумаги сопоставляется со схемой печати в файле GPD или PPD (используя стандартные ключевые слова *PaperSize/*PageSize, или *(MS)PrintSchemaKeywordMap), имя формы будет соответствовать следующему формату:

PrintSchema:<Paper Size name>

Например: PrintSchema:NorthAmericaLetter
Если форма является определяемой пользователем формой, как определено флагом FORM_USER, имя формы будет следующим образом. Индекс формы — это то же значение, которое используется в базе данных формы spooler. Это соответствует индексу, используемому при указании размера бумаги в PrintTicket следующим образом:

UserForm<form index>

Например: UserForm123
В противном случае имя формы будет соответствовать следующему формату, где имя формы — это имя, указанное в GPD *PaperSize или ppD *PageSize.

Config:<name>

Например: Config:_8_5x16

Полный пример строки будет прочитан следующим образом:

Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0

Фильтры отрисовки должны считывать входящий параметр PageMediaSize PrintTicket и искать это значение в значениях имени формы из FormTrayTable.

Пример XML-файла пакета свойств очереди

В следующем фрагменте кода показан синтаксис XML, который можно использовать для трех свойств, Name1, Name2, Name3 и их дочерних элементов:

<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns= "https://schemas.microsoft.com/windows/2011/08/printing/queueproperties">
  <Property Name="Name1">
    <String>String1</String>
  </Property>
  <Property Name="Name2">
    <Int32>3244</Int32>
  </Property>
  <Property Name="Name3">
    <Bool>true</Bool>
  </Property>
</Properties>

XML-схема пакета свойств очереди

На следующем снимке экрана показана XML-схема пакета свойств очереди, и ее можно найти по следующему пути в папке установки WDK: \Include\um\printqueueproperties.xsd.

XML-схема пакета свойств очереди.