Borse della proprietà Driver stampante V4

Articolo
03/08/2023

Importante

È consigliabile usare il driver di classe IPP di Microsoft, insieme a Print Support Apps (PSA), per personalizzare l'esperienza di stampa in Windows 10 e 11 per lo sviluppo di dispositivi stampanti.

Per altre informazioni, vedere la guida alla progettazione dell'app di supporto stampa.

Il modello di driver di stampa v4 offre numerosi contenitori di proprietà che facilitano un flusso di dati da applicazioni dell'interfaccia utente personalizzate al processo di rendering.

Questi contenitori di proprietà consentono la creazione di proprietà e definizioni di funzionalità personalizzate in un'interfaccia utente personalizzata e quindi vengono usate dal processo di rendering. Tutti i borse di proprietà vengono esposti usando l'interfaccia IPrinterScriptablePropertyBag in JavaScript o usando l'interfaccia IPrinterPropertyBag in altri ambienti.

Nella tabella seguente viene fornita una panoramica di come usare componenti diversi per ottenere l'oggetto contenitore delle proprietà da parti diverse di un driver di stampa v4.

Componente	Descrizione
Script di vincolo JavaScript	I pacchetti di proprietà driver e code vengono passati agli script di vincolo JavaScript usando il parametro scriptContext. Questo parametro è di tipo IPrinterScriptContext e contiene elementi figlio: DriverProperties: fa riferimento alla borsa delle proprietà del driver. QueueProperties: fa riferimento al contenitore delle proprietà della coda. UserProperties: contenitore delle proprietà utente. Il contenitore delle proprietà DEVMODE viene passato ai metodi di conversione DEVMODE <-> PrintTicket come parametro devModeProperties , ovvero di tipo IPrinterScriptablePropertyBag. Non è disponibile negli altri metodi.
USB Bidi JavaScript	I contenitori delle proprietà driver e coda vengono passati agli script JavaScript USB Bidi usando il parametro scriptContext. Questo parametro è di tipo IPrinterScriptContext e contiene elementi figlio: DriverProperties: fa riferimento alla borsa delle proprietà del driver. QueueProperties: fa riferimento al contenitore delle proprietà della coda.
App per l'estensione della stampante	Tutti i borse delle proprietà vengono passati come parte del parametro IPrinterExtensionEventArgs al gestore OnDriverEvent. Sono tutti di tipo IPrinterPropertyBag. Vengono specificati come segue: DriverProperties: fa riferimento alla borsa delle proprietà del driver. UserProperties: contenitore delle proprietà utente. PrinterQueue.GetProperties()– fa riferimento al contenitore delle proprietà della coda
App per dispositivi UWP	Tutti i contenitori di proprietà vengono passati durante l'attivazione usando l'oggetto IPrinterExtensionContext . Vengono specificati come: DriverProperties: fa riferimento alla borsa delle proprietà del driver. UserProperties: contenitore delle proprietà utente. PrinterQueue.GetProperties()– fa riferimento al contenitore delle proprietà della coda
Filtro di rendering XPS	I filtri XPS possono accedere al contenitore delle proprietà del driver dall'interno della pipeline di filtro di stampa usando il nome della proprietà "DriverPropertyBag" o il valore definito XPS_FP_PROPERTY_BAG da filterpipeline.h. Ecco le informazioni su DriverPropertyBag: Tipo di proprietà: VT_UNKNOWN Descrizione: Puntatore a un'interfaccia IUnknown. Chiamare QueryInterface per ottenere un puntatore all'interfaccia IPrinterPropertyBag nel contenitore delle proprietà del driver. E i filtri XPS possono accedere al contenitore delle proprietà della coda dall'interno della pipeline di filtro di stampa usando il nome della proprietà "QueuePropertyBag" o il valore definito XPS_FP_QUEUE_PROPERTY_BAG da filterpipeline.h. Ecco le informazioni su QueuePropertyBag: Tipo di proprietà: VT_UNKNOWN Descrizione: Puntatore a un'interfaccia IUnknown. Chiamare QueryInterface per ottenere un puntatore all'interfaccia IPrinterPropertyBag nel contenitore delle proprietà della coda.

Nelle implementazioni di JavaScript i contenitori delle proprietà vengono passati come parametri. Nelle applicazioni di estensione della stampante i contenitori di proprietà vengono passati come membri dell'argomento evento usato per avviare l'applicazione.

Le funzioni di accesso del bag delle proprietà fornite dalle interfacce COM IPrinterQueue, IPrinterExtensionContext e IPrinterExtensionEventArgs e le funzioni di accesso del bag delle proprietà nelle implementazioni javascript genereranno un'eccezione se il contenitore delle proprietà non è specificato o non trovato. Inoltre, la query per le singole proprietà in un'interfaccia IPrinterPropertyBag genererà eccezioni se la proprietà non viene trovata. È consigliabile usare un'istruzione try catch per evitare l'arresto anomalo se una proprietà non è disponibile.

Borsa della proprietà driver

Il contenitore delle proprietà driver è un archivio dati per i driver per le proprietà predefinite o i BLOB di dati per l'uso di sola lettura dal driver. Può essere specificato usando la direttiva "PropertyBag" nel file manifesto v4 e potrebbe non essere modificata in fase di esecuzione.

Windows Driver Kit include un progetto modello per una borsa delle proprietà driver. Il contenitore delle proprietà driver è un BLOB binario compilato. Visual Studio include un modello per generare un contenitore di proprietà del driver compilato. Il file XML generato per questo modello non è il contenitore delle proprietà, ma l'output compilato di questo modello è il file del contenitore di proprietà che deve essere specificato nel file manifesto v4.

User Property Bag

Il contenitore delle proprietà utente consente ai partner di archiviare le impostazioni in un contesto locale del computer per utente. Questo contenitore di proprietà è adatto come meccanismo di archiviazione per le preferenze utente come "Non mostrare di nuovo questo". Questo contenitore di proprietà non è gestibile dagli amministratori e non è sincronizzato tra client e server durante la condivisione della stampante. Il contenitore delle proprietà utente è impostato solo in fase di esecuzione ed è disponibile solo per le estensioni della stampante, le app per dispositivi UWP e i vincoli JavaScript.

Poiché i vincoli JavaScript possono essere chiamati anche all'esterno di un contesto utente, durante il despooling, il contenitore delle proprietà utente non è disponibile in questo momento e Windows restituirà HRESULT_FROM_WIN32(ERROR_NOT_FOUND).

DevMODE, borsa di proprietà

Il contenitore delle proprietà DEVMODE viene usato per organizzare il contenuto nella sezione privata della struttura DEVMODE. Durante le chiamate ConvertPrintTicketToDevMode, JavaScript viene richiamato per popolare il contenuto del contenitore delle proprietà DEVMODE. Durante le chiamate ConvertDevModeToPrintTicket, JavaScript viene richiamato per leggere le impostazioni persistenti dal contenitore delle proprietà DEVMODE e archiviarle nuovamente in PrintTicket.

Questo contenitore di proprietà è limitato a meno di 60 KB (l'importo esatto varia in base alle dimensioni delle sezioni allocate di DEVMODE), perché deve essere serializzato in una struttura DEVMODE per evitare la perdita di dati in alcuni scenari. Le dimensioni esatte disponibili variano per ogni driver perché è determinato dalle dimensioni della sezione pubblica di DEVMODE e dalla sezione privata gestita dal modulo di configurazione.

Il contenitore delle proprietà DEVMODE usa un file XML per specificare i membri del contenitore delle proprietà e usa le API convertPrintTicketToDevMode e convertDevModeToPrintTicket per gestire le conversioni. Il file di mapping XML DEVMODE deve essere specificato nel manifesto v4 usando la direttiva DevModeMap.

Il frammento di codice seguente mostra un esempio XML di mapping XML del mapping delle proprietà 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>

Nella schermata seguente viene illustrato lo schema XML Mapping delle proprietà DEVMODE e si trova nel percorso seguente nella cartella di installazione WDK: \Include\um\printerdriverdevmodemap.xsd.pr

Devmode property bag mapping xml Schema.

I file XML per il mapping del contenitore di proprietà DEVMODE vengono convalidati dallo strumento INFGate.

Bag della coda

Il contenitore delle proprietà della coda archivia le impostazioni di configurazione per coda, tra cui i mapping dei moduli e la configurazione delle proprietà della stampante, ad esempio opzioni installabili. Le proprietà definite dal driver e le proprietà della stampante sono configurabili in PowerShell, mentre i mapping dei moduli per i trasli sono configurabili nell'interfaccia utente delle proprietà della stampante. Le estensioni della stampante non possono modificare uno dei valori delle proprietà.

Il contenitore delle proprietà della coda viene creato automaticamente per molti driver di stampa v4, ma i driver possono anche fornire proprietà aggiuntive per configurare l'uso di un file XML. Questo file XML non deve essere compilato usando lo strumento del contenitore delle proprietà driver. I borse delle proprietà code sono disponibili per le stampanti supportate dai driver di stampa v4 che eseguono una delle operazioni seguenti:

Specificare più vassoi, OR
Specificare le opzioni installabili nel file GPD o PPD, OR
Specificare un contenitore di proprietà della coda nel manifesto del driver usando la direttiva QueueProperties.

Gli amministratori configurano i contenitori delle proprietà della coda con PowerShell. Il comando seguente consente (cmdlet) di essere figlio di un oggetto stampante, che può essere ottenuto usando il cmdlet Get-Printer.

Nome cmdlet	Descrizione
Get-PrinterProperty -printerName printerName <> -name <propertyName*>	Recupera una o più proprietà (il nome supporta il globbing).
Set-PrinterProperty -inputObject printerPropertyObject <>	Modifica una proprietà della coda di stampa usando una stampante persistentePropertyObject.
Set-PrinterProperty -printerName <printerName> -PropertyName propertyName <> -Value <>	Modifica la proprietà specificata nel valore specificato.

Opzioni installabili

Queste opzioni, ad esempio, lo stato di un duplexer verranno esposte nel contenitore delle proprietà della coda come singole proprietà. Ogni proprietà verrà denominata come indicato di seguito, dove il nome della funzionalità si basa sul nome della funzionalità dal file GPD o PPD del driver:

Config:<feature name>

Ad esempio, usare Config:DuplexUnit

Il valore della proprietà è il nome della parola chiave per l'opzione selezionata dall'amministratore. Ad esempio, Installato. Le opzioni installabili sono modificabili usando lo stesso cmdlet di Set-PrinterProperty usato per le proprietà della coda.

A partire da Windows 8.1, un utente con diritti di amministratore o un utente che ha creato una coda di stampa può modificare le opzioni installabili e le impostazioni di configurazione per coda per un contenitore delle proprietà della coda da un'app per dispositivi UWP.

Mapping di form a tray

Per le stampanti con un driver di stampa v4 e con più di una barra, i mapping "form to tray" vengono esposti tramite il contenitore delle proprietà della coda nella proprietà denominata "FormTrayTable".

Questa proprietà viene formattata come stringa con terminazione null contenente coppie del formato <tray name>, <form name>, in cui il nome del modulo è uno dei seguenti:

Se le dimensioni della carta vengono mappate nello schema di stampa nel file GPD o PPD (usando le parole chiave *PaperSize/*PageSize o *(MS)PrintSchemaKeywordMap, il nome del modulo seguirà il formato seguente:

PrintSchema:<Paper Size name>

Ad esempio, usare PrintSchema:NorthAmericaLetter
Se il modulo è un modulo definito dall'utente, come determinato dal flag FORM_USER, il nome del modulo sarà il seguente. L'indice del modulo è lo stesso valore usato nel database del modulo di spooler. Ciò è coerente con l'indice usato quando le dimensioni della carta vengono specificate in PrintTicket come indicato di seguito:

UserForm<form index>

Ad esempio, usare UserForm123
In caso contrario, il nome del modulo seguirà il formato seguente, in cui il nome del modulo è il nome specificato nell'oggetto *PaperSize o il PPD *PageSize.

Config:<name>

Ad esempio, usare Config:_8_5x16

Una stringa di esempio completa legge come indicato di seguito:

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

I filtri di rendering devono leggere l'impostazione PageMediaSize di PrintTicket in ingresso e cercare tale valore nei valori del nome del modulo da FormTrayTable.

Esempio XML del contenitore di proprietà queue

Il frammento di codice seguente mostra la sintassi XML che può essere usata per tre proprietà, Name1, Name2, Name3 e i relativi elementi figlio:

<?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>

Queue Property Bag XML Schema

Lo screenshot seguente mostra lo schema XML del contenitore delle proprietà della coda e si trova nel percorso seguente nella cartella di installazione WDK: \Include\um\printqueueproperties.xsd.

xml schema xml del contenitore delle proprietà della coda.