V4 Printer Driver Property Bags
The v4 print driver model provides a number of property bags that facilitate a data flow from customized UI applications to the rendering process.
The following table provides an overview of how to use different components to obtain the property bag object from different parts of a v4 print driver.
|Printer extension app||All property bags are passed in as part of the IPrinterExtensionEventArgs parameter to the OnDriverEvent handler. They are all of type IPrinterPropertyBag. They are specified as the following:|
|Windows Store device app||All property bags are passed in during activation using the IPrinterExtensionContext object.
They are specified as:|
|XPS rendering filter||
XPS filters can access the driver property bag from within the Print Filter Pipeline Property Bag using the property name "DriverPropertyBag", or the defined value XPS_FP_PROPERTY_BAG from filterpipeline.h. Here is information about DriverPropertyBag:
And XPS filters can access the queue property bag from within the Print Filter Pipeline Property Bag using the property name "QueuePropertyBag", or the defined value XPS_FP_QUEUE_PROPERTY_BAG from filterpipeline.h. Here is information about QueuePropertyBag:
The driver property bag is a data store for drivers to predefine properties or data blobs for read-only use by the driver. It can be specified by using the "PropertyBag" directive in the v4 manifest file and may not be modified at runtime.
The Windows Driver Kit includes a template project for a driver property bag. The driver property bag is a compiled, binary blob. Visual Studio includes a template to generate a compiled driver property bag. The XML file generated for this template is not the property bag, instead the compiled output of this template is the property bag file that should be specified in the v4 manifest file.
This property bag is limited in size to less than 60 KB (the exact amount will vary based on the size of the allocated sections of the DEVMODE), because it must be serialized into a DEVMODE structure in order to avoid data loss in some scenarios. The exact size available will vary per driver because it is determined by the size of the public section of the DEVMODE plus the private section managed by the configuration module.
The DEVMODE property bag uses an XML file to specify the members of the property bag and uses the convertPrintTicketToDevMode and convertDevModeToPrintTicket APIs to handle the conversions. The XML DEVMODE mapping file must be specified in the v4 manifest by using the DevModeMap directive.
The follwoing code snippet shows a DEVMODE Property Bag Mapping XML Sample.
<?xml version="1.0" encoding="utf-8"?> <Properties xmlns="http://schemas.microsoft.com/windows/2011/08/printing/devmodemap"> <Property Name="FabrikamAccountCode"> <String Length="32"></String> </Property> </Properties>
The following screenshot shows the DEVMODE Property Bag Mapping XML Schema, and it can be found at the following path in the WDK installation folder: \Include\um\printerdriverdevmodemap.xsd.pr
The XML files for the DEVMODE property bag mapping are validated by the INFGate tool.
The queue property bag stores per-queue configuration settings, including form to tray mappings and the configuration of printer properties like installable options. Driver-defined properties and printer properties are configurable in PowerShell, whereas form to tray mappings are configurable in the printer properties UI. Printer extensions cannot edit any of the property values.
The queue property bag is created automatically for many v4 print drivers, but drivers may also provide additional properties to configure using an XML file. This XML file should not be compiled using the driver property bag tool. Queue property bags are available for printers supported by v4 print drivers that do either of the following:
1. Specify multiple trays, OR
2. Specify installable options in the GPD or PPD file, OR
3. Specify a queue property bag in the driver manifest using the QueueProperties directive.
|Get-PrinterProperty -printerName <printerName> -name <propertyName*>||Retrieves one or more properties (-name supports globbing)|
|Set-PrinterProperty -inputObject <printerPropertyObject>||Changes a print queue property using a persisted printerPropertyObject.|
|set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value>||Changes the property specified to the value specified.|
Installable options. These options, for example, the state of a duplexer, will be exposed into the queue property bag as individual properties. Each property will be named as follows, where the feature name is based on the name of the feature from the driver’s GPD or PPD file:
- Config:<feature name>
For example, Config:DuplexUnit
The value of the property is the keyword name for the option that has been selected by the administrator. For example, Installed. Installable options are editable using the same Set-PrinterProperty cmdlet that is used for queue properties.
Note Starting with Windows 8.1, a user with Administrator rights, or a user who created a print queue can change the Installable options and the per-queue configuration settings for a queue property bag from a Windows Store device app.
Form to Tray Mappings. For printers with a v4 print driver, and with more than one tray, "form to tray" mappings are exposed via the queue property bag in the property named “FormTrayTable”.
This property is formatted as a null-terminated string containing pairs of the format “<tray name>, <form name>,” where the form name is one of the following:
1. If the paper size is mapped into the Print Schema in the GPD or PPD file (either by using standard *PaperSize/*PageSize keywords, or *(MS)PrintSchemaKeywordMap), then the form name will follow the following format:
PrintSchema:<Paper Size name>
For example, PrintSchema:NorthAmericaLetter
2. If the form is a user-defined form, as determined by the FORM_USER flag, then the form name will be as follows. The form index is the same value used in the spooler’s form database. This is consistent with index used when the paper size is specified in the PrintTicket as UserForm<Form index>.
For example, UserForm123
3. Otherwise, the form name will follow the following format, where the form name is the name that was specified in the GPD’s *PaperSize or the PPD’s *PageSize.
For example, Config:_8_5x16
A complete example string would read as follows: "Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0".
Rendering filters should read the incoming PrintTicket’s PageMediaSize setting, and search for that value in the form name values from the FormTrayTable.
Queue Property Bag XML Sample. The following code snippet shows the XML syntax that could be used for three properties, Name1, Name2, Name3 and their child elements:
<?xml version="1.0" encoding="utf-8"?> <Properties xmlns= "http://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>
Queue Property Bag XML Schema. The following screenshot shows the queue property bag XML schema, and it can be found at the following path in the WDK installation folder: \Include\um\printqueueproperties.xsd.
- Print Filter Pipeline Property Bag