Contenitori delle proprietà del driver della stampante V4

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

Questi contenitori di proprietà consentono la creazione di proprietà personalizzate e definizioni di funzionalità in un'interfaccia utente personalizzata e quindi vengono utilizzate dal processo di rendering. Tutti i contenitori 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 dell'utilizzo di componenti diversi per ottenere l'oggetto contenitore delle proprietà da parti diverse di un driver di stampa v4.

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

Le funzioni di accesso contenitore delle proprietà fornite dalle interfacce COM IPrinterQueue, IPrinterExtensionContext e IPrinterExtensionEventArgs e le funzioni di accesso contenitore delle proprietà nelle implementazioni di Javascript genereranno un'eccezione se il contenitore delle proprietà non viene specificato o non trovato. Inoltre, l'esecuzione di 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 di arrestarsi in modo anomalo se una proprietà non è disponibile.

Contenitore delle proprietà driver

Il contenitore delle proprietà del driver è un archivio dati per i driver per le proprietà predefinite o i BLOB di dati per l'uso di sola lettura da parte del 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 un contenitore delle proprietà driver. Il contenitore delle proprietà del driver è un BLOB binario compilato. Visual Studio include un modello per generare un contenitore delle 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 contenitore delle proprietà che deve essere specificato nel file manifesto v4.

Contenitore delle proprietà user

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 dell'utente, ad esempio "Non visualizzare 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 anche essere chiamati all'esterno di un contesto utente, durante il despooling, il contenitore delle proprietà utente non è attualmente disponibile e Windows restituirà HRESULT_FROM_WIN32(ERROR_NOT_FOUND).

Contenitore delle proprietà DEVMODE

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 delle proprietà è limitato a meno di 60 KB (la quantità esatta varia in base alle dimensioni delle sezioni allocate di DEVMODE), perché deve essere serializzata in una struttura DEVMODE per evitare la perdita di dati in alcuni scenari. Le dimensioni esatte disponibili variano in base al driver perché è determinato dalle dimensioni della sezione pubblica di DEVMODE più la 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 DEVMODE XML deve essere specificato nel manifesto v4 usando la direttiva DevModeMap.

Il frammento di codice seguente mostra un esempio XML di mapping xml del contenitore 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>

Lo screenshot seguente mostra l'XML Schema xml mapping del contenitore delle proprietà DEVMODE e si trova nel percorso seguente nella cartella di installazione di WDK: \Include\um\printerdriverdevmodemap.xsd.pr

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

Contenitore delle proprietà queue

Il contenitore delle proprietà della coda archivia le impostazioni di configurazione per coda, tra cui i mapping tra moduli e la configurazione delle proprietà della stampante, ad esempio le opzioni installabili. Le proprietà definite dal driver e le proprietà della stampante sono configurabili in PowerShell, mentre il form per i mapping tra vassoi è configurabile nell'interfaccia utente delle proprietà della stampante. Le estensioni della stampante non possono modificare i 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 da configurare usando un file XML. Questo file XML non deve essere compilato usando lo strumento contenitore delle proprietà del driver. I contenitori delle proprietà della coda sono disponibili per le stampanti supportate dai driver di stampa v4 che eseguono una delle operazioni seguenti:

1. Specificare più vassoi, OR

2. Specificare le opzioni installabili nel file GPD o PPD OPPURE

3. Specificare un contenitore delle proprietà della coda nel manifesto del driver usando la direttiva QueueProperties.

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

Opzioni installabili

Queste opzioni, ad esempio, lo stato di un duplex, verranno esposte nel contenitore delle proprietà della coda come singole proprietà. Ogni proprietà verrà denominata come segue, in cui il nome della funzionalità è basato sul nome della funzionalità dal file GPD o PPD del driver:

Config:<feature name>

Ad esempio, 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 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 da maschera a barra

Per le stampanti con un driver di stampa v4 e con più di un vassoio, 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 di formato <tray name>, <form name>, in cui il nome del modulo è uno dei seguenti:

1. Se il formato carta viene mappato allo schema di stampa nel file GPD o PPD (usando parole chiave *PaperSize/*PageSize standard o *(MS)PrintSchemaKeywordMap), il nome del modulo seguirà il formato seguente:

   PrintSchema:<Paper Size name>

   Ad esempio, PrintSchema:NorthAmericaLetter

2. 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 utilizzato nel database dei moduli dello 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, UserForm123

3. In caso contrario, il nome del modulo seguirà il formato seguente, in cui il nome del modulo è il nome specificato nel file *PaperSize dell'oggetto Criteri di gruppo o nel formato *PageSize del PPD.

   Config:<name>

   Ad esempio, Config:_8_5x16

Una stringa di esempio completa viene letta come segue:

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 contenitore delle proprietà della coda

Il frammento di codice seguente illustra 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>

XML Schema contenitore delle proprietà della coda

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

Argomenti correlati

IPrinterExtensionContext

IPrinterExtensionEventArgs

IPrinterPropertyBag

IPrinterScriptablePropertyBag

IPrinterScriptContext

Contenitore delle proprietà della pipeline del filtro di stampa