V4 Druckertreiber-Eigenschaftstaschen
Wichtig
Die Modern Print-Plattform ist die von Windows bevorzugte Methode zur Kommunikation mit Druckern. Wir empfehlen die Verwendung des Microsoft IPP-Treibers für die Posteingangsklasse zusammen mit Print Support Apps (PSA), um das Druckverhalten in Windows 10 und 11 für die Entwicklung von Druckergeräten anzupassen.
Weitere Informationen finden Sie unter Modern Print-Plattform und der Anleitung zum Design der Print-Support-App.
Das v4-Druckertreibermodell bietet eine Reihe von Eigenschaftstaschen, die den Datenfluss von benutzerdefinierten Benutzeroberflächenanwendungen zum Rendern erleichtern.
Mit diesen Eigenschaftstaschen können Sie benutzerdefinierte Eigenschaften und Feature-Definitionen in einer benutzerdefinierten Benutzeroberfläche erstellen, die dann vom Rendern verwendet werden können. Alle Eigenschaftstaschen werden durch Verwendung der Schnittstelle IPrinterScriptablePropertyBag in JavaScript oder durch Verwendung der Schnittstelle IPrinterPropertyBag in anderen Umgebungen dargestellt.
Die folgende Tabelle gibt einen Überblick darüber, wie Sie verschiedene Komponenten verwenden, um das Objekt Eigenschaftstasche aus verschiedenen Teilen eines v4-Druckertreibers zu erhalten.
| Komponente | Beschreibung |
|---|---|
| Skript für JavaScript-Einschränkungen | Die Eigenschaftstaschen des Treibers und der Warteschlange werden mit dem Parameter scriptContext an JavaScript-Constraint-Skripte übergeben. Dieser Parameter ist vom Typ IPrinterScriptContext und enthält Variablen: DriverProperties – verweist auf die Eigenschaftstasche des Treibers. QueueProperties – verweist auf die Eigenschaftstasche der Warteschlange. UserProperties – Die Eigenschaftstasche des Benutzers. Die Eigenschaftstasche DEVMODE wird in den Konvertierungsmethoden DEVMODE <–> PrintTicket als Parameter devModeProperties (vom Typ IPrinterScriptablePropertyBag) übergeben. Bei den anderen Methoden ist sie nicht verfügbar. |
| USB Bidi JavaScript | Die Eigenschaftstaschen für den Treiber und die Warteschlange werden über den Parameter scriptContext an USB Bidi JavaScript-Skripte übergeben. Dieser Parameter ist vom Typ IPrinterScriptContext und enthält Variablen: DriverProperties – verweist auf die Eigenschaftstasche des Treibers. QueueProperties – verweist auf die Eigenschaftstasche der Warteschlange. |
| App zur Druckerweiterung | Alle Eigenschaftstaschen werden als Teil des Parameters IPrinterExtensionEventArgs an den OnDriverEvent-Handler übergeben. Sie sind alle vom Typ IPrinterPropertyBag. Sie sind wie folgt spezifiziert: DriverProperties – verweist auf die Eigenschaftstasche des Treibers. UserProperties – Die Eigenschaftstasche des Benutzers. PrinterQueue.GetProperties() – verweist auf die Eigenschaftstasche der Warteschlange |
| UWP-Geräte-App | Alle Eigenschaftstaschen werden bei der Aktivierung über das Objekt IPrinterExtensionContext übergeben. Sie werden wie folgt spezifiziert: DriverProperties – verweist auf die Eigenschaftstasche des Treibers. UserProperties – Die Eigenschaftstasche des Benutzers. PrinterQueue.GetProperties() – verweist auf die Eigenschaftstasche der Warteschlange |
| XPS-Filter zum Rendern | XPS-Filter können auf die Eigenschaftstasche des Treibers aus der Eigenschaftstasche der Druckfilter-Pipeline zugreifen, indem sie den Eigenschaftsnamen „DriverPropertyBag“ oder den definierten Wert XPS_FP_PROPERTY_BAG aus filterpipeline.h verwenden. Hier finden Sie Informationen über DriverPropertyBag: Eigenschaftstyp: VT_UNKNOWN Beschreibung: Ein Pointer auf eine IUnknown-Schnittstelle. Rufen Sie QueryInterface auf, um einen Pointer auf die Schnittstelle IPrinterPropertyBag für die Eigenschaftstasche des Treibers zu erhalten. Und XPS-Filter können auf die Eigenschaftstasche der Warteschlange aus der Eigenschaftstasche der Druckfilter-Pipeline zugreifen, indem sie den Eigenschaftsnamen „QueuePropertyBag“ oder den definierten Wert XPS_FP_QUEUE_PROPERTY_BAG aus filterpipeline.h verwenden. Hier finden Sie Informationen über QueuePropertyBag: Eigenschaftstyp: VT_UNKNOWN Beschreibung: Ein Pointer auf eine IUnknown-Schnittstelle. Rufen Sie QueryInterface auf, um einen Pointer auf die Schnittstelle IPrinterPropertyBag für die Eigenschaftstasche der Warteschlange zu erhalten. |
In JavaScript-Implementierungen werden Eigenschaftstaschen als Parameter übergeben. In Anwendungen zur Druckerweiterung werden Eigenschaftstaschen als Teil des Ereignisarguments übergeben, das zum Starten der Anwendung verwendet wird.
Die von den COM-Schnittstellen IPrinterQueue, IPrinterExtensionContext und IPrinterExtensionEventArgs bereitgestellten Eigenschaftstaschen-Zugriffsfunktionen sowie die Eigenschaftstaschen-Zugriffsfunktionen in Javascript-Implementierungen lösen eine Ausnahme aus, wenn die Eigenschaftstasche nicht angegeben oder nicht gefunden wird. Außerdem werden bei der Suche nach einzelnen Eigenschaften auf einer IPrinterPropertyBag-Schnittstelle Ausnahmen ausgelöst, wenn die Eigenschaft nicht gesucht wird. Sie sollten eine Try-Catch-Anweisung verwenden, um einen Absturz zu vermeiden, wenn eine Eigenschaft nicht verfügbar ist.
Treiber Eigenschaftstasche
Die Eigenschaftstasche des Treibers ist ein Datenspeicher, in dem Treiber Eigenschaften oder Datenblöcke vordefinieren können, die vom Treiber nur lesend verwendet werden können. Sie kann mit der „PropertyBag“-Direktive in der v4-Manifestdatei angegeben werden und darf zur Runtime nicht verändert werden.
Das Windows Driver Kit enthält eine Projektvorlage für eine Eigenschaftstasche für Treiber. Die Eigenschaftstasche des Treibers ist ein kompilierter, binärer Blob. Visual Studio enthält eine Vorlage zur Erstellung einer kompilierten Eigenschaftstasche für den Treiber. Die für diese Vorlage generierte XML-Datei ist nicht die Eigenschaftstasche, sondern die kompilierte Ausgabe dieser Vorlage ist die Eigenschaftstaschen-Datei, die in der v4-Manifestdatei angegeben werden sollte.
Eigenschaftstasche für Benutzer
Die Eigenschaftstasche für Benutzer ermöglicht es Partnern, Einstellungen in einem benutzer- und gerätespezifischen Kontext zu speichern. Diese Eigenschaftstasche eignet sich gut als Speichermedium für Benutzereinstellungen wie „Dies nicht mehr anzeigen“. Diese Eigenschaftstasche kann von Administratoren nicht verwaltet werden und wird bei der gemeinsamen Nutzung von Druckern nicht zwischen Client und Server synchronisiert. Die Eigenschaftstasche des Benutzers wird erst zur Runtime festgelegt und steht nur den Drucker-Erweiterungen, UWP-Geräteanwendungen und JavaScript-Einschränkungen zur Verfügung.
Da JavaScript-Einschränkungen auch außerhalb eines Benutzerkontextes angefragt werden können, ist die Eigenschaftstasche des Benutzers zu diesem Zeitpunkt nicht verfügbar und Windows gibt HRESULT_FROM_WIN32(ERROR_NOT_FOUND) zurück.
DEVMODE Eigenschaftstasche
Die Eigenschaftstasche DEVMODE wird verwendet, um Inhalte im privaten Bereich der DEVMODE-Struktur zu organisieren. Bei Anfragen zu ConvertPrintTicketToDevMode wird JavaScript aufgerufen, um den Inhalt der Eigenschaftstasche DEVMODE aufzufüllen. Bei Anfragen zu ConvertDevModeToPrintTicket wird JavaScript aufgerufen, um die persistierten Einstellungen aus der Eigenschaftstasche DEVMODE zu lesen und im PrintTicket zu speichern.
Die Größe dieser Eigenschaftstasche ist auf weniger als 60 KB begrenzt (die genaue Größe hängt von der Größe der zugewiesenen Abschnitte des DEVMODE ab), da sie in eine DEVMODE-Struktur serialisiert werden muss, um in einigen Szenarien Datenverlust zu vermeiden. Die genaue verfügbare Größe variiert je nach Treiber, da sie durch die Größe des öffentlichen Bereichs des DEVMODE und des vom Konfigurationsmodul verwalteten privaten Bereichs bestimmt wird.
Die Eigenschaftstasche DEVMODE verwendet eine XML-Datei, um die Mitglieder der Eigenschaftstasche zu spezifizieren und verwendet die APIs convertPrintTicketToDevMode und convertDevModeToPrintTicket, um die Konvertierungen durchzuführen. Die XML DEVMODE-Zuordnungsdatei muss im v4-Manifest mit der DevModeMap-Direktive angegeben werden.
Der folgende Codeschnipsel zeigt ein DEVMODE Property Bag Mapping XML-Beispiel.
<?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>
Der folgende Screenshot zeigt das XML-Schema für das Mapping der Eigenschaftstaschen von DEVMODE. Sie finden es unter folgendem Pfad im WDK-Installationsordner: \Include\um\printerdriverdevmodemap.xsd.pr
Die XML-Dateien für das Mapping der Eigenschaftstaschen von DEVMODE werden vom Tool INFGate validiert.
Eigenschaftstasche für Warteschlangen
In der Eigenschaftstasche für die Warteschlange werden die Konfigurationseinstellungen für die einzelnen Warteschlangen gespeichert, einschließlich der Zuordnungen von Formularen zu Schächten und der Konfiguration von Druckereigenschaften wie installierbaren Optionen. Treiberdefinierte Eigenschaften und Druckereigenschaften sind in der PowerShell konfigurierbar, während die Zuordnungen von Formularen zu Schächten in der Benutzeroberfläche der Druckereigenschaften konfiguriert werden können. Drucker-Erweiterungen können keinen der Eigenschaftswerte bearbeiten.
Die Eigenschaftstasche für die Warteschlange wird bei vielen v4-Druckertreibern automatisch erstellt, aber die Treiber können auch zusätzliche Eigenschaften bereitstellen, die über eine XML-Datei konfiguriert werden können. Diese XML-Datei sollte nicht mit dem Tool für die Eigenschaftstasche des Treibers kompiliert werden. Eigenschaftstaschen für Warteschlangen sind für Drucker verfügbar, die von v4-Druckertreibern unterstützt werden, die eine der folgenden Funktionen haben:
Angabe von mehreren Ausgabefächern, ODER
Angabe der installierbaren Optionen in der GPD- oder PPD-Datei, ODER
Angabe einer Eigenschaftstasche für die Warteschlange im Treibermanifest mit Hilfe der QueueProperties-Direktive.
Administratoren konfigurieren die Eigenschaftstaschen der Warteschlange mit PowerShell. Die folgenden Befehlszeilen (Cmdlets) sind Variablen eines Druckerobjekts, das mit dem Cmdlet Get-Printer abgerufen werden kann.
| Cmdlet-Name | Beschreibung |
|---|---|
| Get-PrinterProperty -printerName <printerName> -name <propertyName*> | Ruft eine oder mehrere Eigenschaften ab (-name unterstützt Globbing). |
| Set-PrinterProperty -inputObject <printerPropertyObject> | Ändert eine Eigenschaft der Druckwarteschlange mit Hilfe eines persistierten printerPropertyObjects. |
| Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value> | Ändert die angegebene Eigenschaft auf den angegebenen Wert. |
Installationsfähige Optionen
Diese Optionen, z. B. der Status eines Duplexers, werden in der Eigenschaftstasche der Warteschlange als individuelle Eigenschaften angezeigt. Jede Eigenschaft wird wie folgt benannt, wobei der Funktionsname auf dem Namen der Funktion aus der GPD- oder PPD-Datei des Treibers basiert:
Config:<feature name>
Beispiel: Config:DuplexUnit
Der Wert der Eigenschaft ist der Schlüsselwortname für die Option, die der Administrator ausgewählt hat. Zum Beispiel: Installiert. Installationsfähige Optionen können mit demselben Cmdlet Set-PrinterProperty bearbeitet werden, das auch für Warteschlangeneigenschaften verwendet wird.
Ab Windows 8.1 kann ein Benutzer mit Administratorrechten oder ein Benutzer, der eine Druckwarteschlange erstellt hat, die installierbaren Optionen und die Konfigurationseinstellungen pro Warteschlange für eine Eigenschaftstasche der Warteschlange von einer UWP-Geräte-App aus ändern.
Zuordnungen von Formularen zu Fächern
Bei Druckern mit einem v4-Druckertreiber und mit mehr als einem Schacht werden die Zuordnungen von Formularen zu Schächten über die Eigenschaftstasche der Warteschlange in der Eigenschaft „FormTrayTable“ angezeigt.
Diese Eigenschaft ist als null-terminierte Zeichenkette formatiert, die Paare des Formats <tray name>, <form name>, enthält, wobei der Formularname einer der folgenden ist:
Wenn das Papierformat im Druckschema in der GPD- oder PPD-Datei abgebildet ist (entweder mit den Standard-Schlüsselwörtern *PaperSize/*PageSize oder *(MS)PrintSchemaKeywordMap), hat der Formularname das folgende Format:
PrintSchema:<Paper Size name>Beispiel:
PrintSchema:NorthAmericaLetterWenn es sich bei dem Formular um ein benutzerdefiniertes Formular handelt, wie durch das Flag FORM_USER festgelegt, lautet der Formularname wie folgt. Der Formularindex ist derselbe Wert, der auch in der Formulardatenbank des Spoolers verwendet wird. Dies entspricht dem Index, der verwendet wird, wenn das Papierformat im PrintTicket wie folgt angegeben wird:
UserForm<form index>Beispiel:
UserForm123Andernfalls folgt der Formularname dem folgenden Format, wobei der Formularname der Name ist, der in der *PaperSize des GPD oder der *PageSize des PPD angegeben wurde.
Config:<name>Beispiel:
Config:_8_5x16
Eine vollständige Beispielzeichenkette würde wie folgt lauten:
Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0
Renderfilter sollten die PageMediaSize-Einstellung des eingehenden PrintTickets lesen und nach diesem Wert in den Formularnamenwerten aus der FormTrayTable suchen.
Warteschlange Eigenschaftstasche XML Sample
Der folgende Code-Schnipsel zeigt die XML-Syntax, die für die drei Eigenschaften Name1, Name2, Name3 und ihre untergeordneten Elemente verwendet werden könnte:
<?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-Schema für die Eigenschaftstasche der Warteschlange
Der folgende Screenshot zeigt das XML-Schema für die Eigenschaftstasche der Warteschlange. Sie finden es unter folgendem Pfad im WDK-Installationsordner: \Include\um\printqueueproperties.xsd.
