V4 Druckertreiber-Eigenschaftentaschen

Artikel
03/08/2023

Wichtig

Es wird empfohlen, den IPP-Posteingangsklassentreiber von Microsoft zusammen mit Druckunterstützungs-Apps (PSA) zu verwenden, um die Druckoberfläche in Windows 10 und 11 für die Druckergeräteentwicklung anzupassen.

Weitere Informationen finden Sie im Designhandbuch für Druckunterstützungs-Apps.

Das v4-Drucktreibermodell bietet eine Reihe von Eigenschaftentaschen, die einen Datenfluss von benutzerdefinierten Ui-Anwendungen zum Renderingprozess erleichtern.

Diese Eigenschaftensammlungen ermöglichen es, benutzerdefinierte Eigenschaften und Featuredefinitionen auf einer benutzerdefinierten Benutzeroberfläche zu erstellen und dann vom Renderingprozess zu verwenden. Alle Eigenschaftentaschen werden mithilfe der IPrinterScriptablePropertyBag-Schnittstelle in JavaScript oder mithilfe der IPrinterPropertyBag-Schnittstelle in anderen Umgebungen verfügbar gemacht.

Die folgende Tabelle enthält eine Übersicht über die Verwendung verschiedener Komponenten zum Abrufen des Eigenschaftsbehälterobjekts aus verschiedenen Teilen eines v4-Drucktreibers.

Komponente	BESCHREIBUNG
JavaScript-Einschränkungsskript	Die Treiber- und Warteschlangeneigenschaften werden mithilfe des scriptContext-Parameters an JavaScript-Einschränkungsskripts übergeben. Dieser Parameter ist vom Typ IPrinterScriptContext und enthält untergeordnete Elemente: DriverProperties – bezieht sich auf den Treibereigenschaftenbehälter. QueueProperties– bezieht sich auf den Warteschlangeneigenschaftenbehälter. UserProperties: Der Benutzereigenschaftenbehälter. Der DEVMODE-Eigenschaftenbehälter wird als devModeProperties-Parameter (vom Typ IPrinterScriptablePropertyBag) an die Konvertierungsmethoden DEVMODE <–> PrintTicket übergeben. Es ist für die anderen Methoden nicht verfügbar.
USB Bidi JavaScript	Die Treiber- und Warteschlangeneigenschaften werden mithilfe des scriptContext-Parameters an USB Bidi JavaScript-Skripts übergeben. Dieser Parameter ist vom Typ IPrinterScriptContext und enthält untergeordnete Elemente: DriverProperties – bezieht sich auf den Treibereigenschaftenbehälter. QueueProperties– bezieht sich auf den Warteschlangeneigenschaftenbehälter.
Druckererweiterungs-App	Alle Eigenschaftentaschen werden als Teil des IPrinterExtensionEventArgs-Parameters an den OnDriverEvent-Handler übergeben. Sie sind alle vom Typ IPrinterPropertyBag. Sie werden wie folgt angegeben: DriverProperties – bezieht sich auf den Treibereigenschaftenbehälter. UserProperties: Der Benutzereigenschaftenbehälter. PrinterQueue.GetProperties() – bezieht sich auf den Warteschlangeneigenschaftenbehälter
UWP-Geräte-App	Alle Eigenschaftenbehälter werden während der Aktivierung mit dem IPrinterExtensionContext-Objekt übergeben. Sie werden wie folgt angegeben: DriverProperties – bezieht sich auf den Treibereigenschaftenbehälter. UserProperties: Der Benutzereigenschaftenbehälter. PrinterQueue.GetProperties() – bezieht sich auf den Warteschlangeneigenschaftenbehälter
XPS-Renderingfilter	XPS-Filter können über den Eigenschaftenbehälter der Druckfilter-Pipeline unter Verwendung des Eigenschaftennamens "DriverPropertyBag" oder des definierten Werts XPS_FP_PROPERTY_BAG aus filterpipeline.h auf den Treibereigenschaftenbehälter zugreifen. Hier finden Sie Informationen zu DriverPropertyBag: Eigenschaftstyp: VT_UNKNOWN Beschreibung: Ein Zeiger auf eine IUnknown-Schnittstelle. Rufen Sie QueryInterface auf, um einen Zeiger auf die IPrinterPropertyBag-Schnittstelle auf den Treibereigenschaftenbehälter abzurufen. XpS-Filter können über den Eigenschaftenbehälter der Druckfilter-Pipeline mithilfe des Eigenschaftennamens "QueuePropertyBag" oder des definierten Werts XPS_FP_QUEUE_PROPERTY_BAG aus filterpipeline.h auf den Warteschlangeneigenschaftenbehälter zugreifen. Hier finden Sie Informationen zu QueuePropertyBag: Eigenschaftstyp: VT_UNKNOWN Beschreibung: Ein Zeiger auf eine IUnknown-Schnittstelle. Rufen Sie QueryInterface auf, um einen Zeiger auf die IPrinterPropertyBag-Schnittstelle auf den Warteschlangeneigenschaftenbehälter abzurufen.

In JavaScript-Implementierungen werden Eigenschaftssäcke als Parameter übergeben. In Druckererweiterungsanwendungen werden Eigenschaftsbehälter als Member des Ereignisarguments übergeben, das zum Starten der Anwendung verwendet wird.

Die Von den COM IPrinterQueue-, IPrinterExtensionContext- und IPrinterExtensionEventArgs-Schnittstellen bereitgestellten Eigenschaftenbehälter-Accessoren sowie die Property Bag-Accessoren in Javascript-Implementierungen lösen eine Ausnahme aus, wenn der Eigenschaftenbehälter nicht angegeben oder nicht gefunden wird. Darüber hinaus löst das Abfragen einzelner Eigenschaften für eine IPrinterPropertyBag-Schnittstelle Ausnahmen aus, wenn die Eigenschaft nicht gefunden wird. Sie sollten eine try catch-Anweisung verwenden, um einen Absturz zu vermeiden, wenn eine Eigenschaft nicht verfügbar ist.

Treibereigenschaftenbehälter

Der Treibereigenschaftenbehälter ist ein Datenspeicher für Treiber für vordefinierte Eigenschaften oder Datenblobs zur schreibgeschützten Verwendung durch den Treiber. Sie kann mithilfe der "PropertyBag"-Anweisung in der v4-Manifestdatei angegeben werden und kann zur Laufzeit nicht geändert werden.

Das Windows Driver Kit enthält ein Vorlagenprojekt für eine Treibereigenschaftentasche. Der Treibereigenschaftenbehälter ist ein kompiliertes, binäres Blob. Visual Studio enthält eine Vorlage zum Generieren eines kompilierten Treibereigenschaftenbehälters. Die für diese Vorlage generierte XML-Datei ist nicht der Eigenschaftenbehälter, sondern die kompilierte Ausgabe dieser Vorlage ist die Eigenschaftenbehälterdatei, die in der v4-Manifestdatei angegeben werden sollte.

Benutzereigenschaftenbehälter

Der Benutzereigenschaftenbehälter ermöglicht Partnern das Speichern von Einstellungen in einem lokalen Kontext pro Benutzer und Computer. Diese Eigenschaftentasche eignet sich gut als Speichermechanismus für Benutzereinstellungen wie "Nicht erneut anzeigen". Dieser Eigenschaftenbehälter ist von Administratoren nicht verwaltbar und wird während der Druckerfreigabe nicht zwischen Client und Server synchronisiert. Der Benutzereigenschaftenbehälter ist nur zur Laufzeit festgelegt und nur für die Druckererweiterungen, UWP-Geräte-Apps und JavaScript-Einschränkungen verfügbar.

Da JavaScript-Einschränkungen auch außerhalb eines Benutzerkontexts aufgerufen werden können, ist der Benutzereigenschaftenbehälter während der Entpoolung derzeit nicht verfügbar, und Windows gibt HRESULT_FROM_WIN32(ERROR_NOT_FOUND) zurück.

DEVMODE-Eigenschaftenbehälter

Der DEVMODE-Eigenschaftenbehälter wird verwendet, um Inhalte im privaten Abschnitt der DEVMODE-Struktur zu organisieren. Während ConvertPrintTicketToDevMode-Aufrufen wird JavaScript aufgerufen, um den Inhalt des DEVMODE-Eigenschaftenbehälters aufzufüllen. Während ConvertDevModeToPrintTicket-Aufrufen wird JavaScript aufgerufen, um die persistenten Einstellungen aus dem DEVMODE-Eigenschaftenbehälter zu lesen und sie wieder im PrintTicket zu speichern.

Dieser Eigenschaftenbehälter ist in seiner Größe auf weniger als 60 KB beschränkt (die genaue Menge variiert je nach Größe der zugeordneten Abschnitte des DEVMODE), da er in eine DEVMODE-Struktur serialisiert werden muss, um Datenverlust in einigen Szenarien zu vermeiden. Die genaue verfügbare Größe variiert je nach Treiber, da sie von der Größe des öffentlichen Abschnitts des DEVMODE sowie des privaten Abschnitts bestimmt wird, der vom Konfigurationsmodul verwaltet wird.

Der DEVMODE-Eigenschaftenbehälter verwendet eine XML-Datei, um die Member des Eigenschaftenbehälters anzugeben, und verwendet die convertPrintTicketToDevMode- und convertDevModeToPrintTicket-APIs, um die Konvertierungen zu verarbeiten. Die XML DEVMODE-Zuordnungsdatei muss im v4-Manifest mithilfe der DevModeMap-Direktive angegeben werden.

Der folgende Codeausschnitt zeigt ein XML-Beispiel für die Zuordnung von DEVMODE-Eigenschaftenbehältern.

<?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 der DEVMODE-Eigenschaftsbehälterzuordnung, das im folgenden Pfad im WDK-Installationsordner zu finden ist: \Include\um\printerdriverdevmodemap.xsd.pr

devmode-Eigenschaft: XML-Schema.

Die XML-Dateien für die ZUORDNUNG der DEVMODE-Eigenschaft werden vom INFGate-Tool überprüft.

Warteschlangeneigenschaftenbehälter

Der Warteschlangeneigenschaftenbehälter speichert Konfigurationseinstellungen pro Warteschlange, einschließlich Zuordnungen von Formular zu Fach und die Konfiguration von Druckereigenschaften wie installierbare Optionen. Treiberdefinierte Eigenschaften und Druckereigenschaften sind in PowerShell konfigurierbar, während Die Zuordnungen von Formular zu Fach in der Benutzeroberfläche der Druckereigenschaften konfigurierbar sind. Druckererweiterungen können keine der Eigenschaftswerte bearbeiten.

Der Warteschlangeneigenschaftenbehälter wird für viele v4-Drucktreiber automatisch erstellt. Treiber können jedoch auch zusätzliche Eigenschaften bereitstellen, um mithilfe einer XML-Datei zu konfigurieren. Diese XML-Datei sollte nicht mithilfe des Treibereigenschaftenbehältertools kompiliert werden. Warteschlangeneigenschaftentaschen sind für Drucker verfügbar, die von v4-Drucktreibern unterstützt werden und eine der folgenden Aktionen ausführen:

Geben Sie mehrere Trays an, ODER
Angeben installierbarer Optionen in der GPD- oder PPD-Datei, ODER
Geben Sie einen Warteschlangeneigenschaftenbehälter im Treibermanifest mithilfe der QueueProperties-Anweisung an.

Administratoren konfigurieren Warteschlangeneigenschaften mit PowerShell. Die folgenden Befehlsvorgänge (Cmdlets) sind untergeordnete Elemente eines Druckerobjekts, das mithilfe des Cmdlets Get-Printer abgerufen werden kann.

Cmdlet-Name	BESCHREIBUNG
Get-PrinterProperty -printerName <printerName> -name <propertyName*>	Ruft mindestens eine Eigenschaft ab (-name unterstützt globbing).
Set-PrinterProperty -inputObject <printerPropertyObject>	Ändert eine Druckwarteschlangeneigenschaft mithilfe eines persistenten printerPropertyObject.
Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value>	Ändert die angegebene Eigenschaft in den angegebenen Wert.

Installierbare Optionen

Diese Optionen, z. B. der Zustand eines Duplexers, werden im Warteschlangeneigenschaftenbehälter als einzelne Eigenschaften verfügbar gemacht. Jede Eigenschaft wird wie folgt benannt, wobei der Featurename auf dem Namen des Features aus der GPD- oder PPD-Datei des Treibers basiert:

Config:<feature name>

Zum Beispiel, Config:DuplexUnit

Der Wert der Eigenschaft ist der Schlüsselwortname für die Option, die vom Administrator ausgewählt wurde. Beispiel: Installiert. Installierbare Optionen können mit demselben Set-PrinterProperty Cmdlet bearbeitet werden, das für Warteschlangeneigenschaften verwendet wird.

Ab Windows 8.1 kann ein Benutzer mit Administratorrechten oder ein Benutzer, der eine Druckwarteschlange erstellt hat, die Installable-Optionen und die Konfigurationseinstellungen pro Warteschlange für einen Warteschlangeneigenschaftenbehälter aus einer UWP-Geräte-App ändern.

Zuordnungen von Formularen zu Fach

Bei Druckern mit einem v4-Drucktreiber und mit mehr als einem Fach werden "Form-zu-Fach"-Zuordnungen über den Warteschlangeneigenschaftenbehälter in der Eigenschaft "FormTrayTable" verfügbar gemacht.

Diese Eigenschaft ist als NULL-endende Zeichenfolge formatiert, die Paare des Formats <tray name>, <form name>, enthält, bei dem der Formularname eines der folgenden ist:

Wenn das Papierformat dem Druckschema in der GPD- oder PPD-Datei zugeordnet ist (entweder mithilfe der Standardmäßigen Schlüsselwörter *PaperSize/*PageSize oder *(MS)PrintSchemaKeywordMap), hat der Formularname das folgende Format:

PrintSchema:<Paper Size name>

Zum Beispiel, PrintSchema:NorthAmericaLetter
Wenn es sich bei dem Formular um ein benutzerdefiniertes Formular handelt, wie durch das flag FORM_USER bestimmt, lautet der Formularname wie folgt. Der Formularindex ist derselbe Wert, der in der Formulardatenbank des Spoolers verwendet wird. Dies ist konsistent mit dem Index, der verwendet wird, wenn das Papierformat im PrintTicket wie folgt angegeben wird:

UserForm<form index>

Zum Beispiel, UserForm123
Andernfalls folgt der Formularname dem folgenden Format, wobei der Formularname dem Namen entspricht, der in der *PaperSize-Datei der GPD oder in der PPD's *PageSize angegeben wurde.

Config:<name>

Zum Beispiel, Config:_8_5x16

Eine vollständige Beispielzeichenfolge würde wie folgt lauten:

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

Renderingfilter sollten die PageMediaSize-Einstellung des eingehenden PrintTicket lesen und in den Formularnamenwerten aus der FormTrayTable nach diesem Wert suchen.

XML-Beispiel für Warteschlangeneigenschaftenbehälter

Der folgende Codeausschnitt zeigt die XML-Syntax, die für drei Eigenschaften verwendet werden kann: Name1, Name2, Name3 und deren untergeordnete Elemente:

<?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 des Warteschlangeneigenschaftenbehälters

Der folgende Screenshot zeigt das XML-Schema des Warteschlangeneigenschaftenbehälters, das im folgenden Pfad im WDK-Installationsordner zu finden ist: \Include\um\printqueueproperties.xsd.

xml-Schema der Queue-Eigenschaft