Sady vlastností ovladače tiskárny V4

Článek
2025-02-20

Důležitý

Moderní tisková platforma je upřednostňovaná pro komunikaci s tiskárnami ve Windows. Doporučujeme použít ovladač třídy doručené pošty IPP od Microsoftu spolu s tiskovými podpůrnými aplikacemi (PSA) k přizpůsobení prostředí tisku ve Windows 10 a 11 pro vývoj zařízení tiskárny.

Další informace najdete v průvodci návrhem aplikace Podpora tisku.

Model ovladače tisku v4 poskytuje řadu sáčků vlastností, které usnadňují tok dat z přizpůsobených aplikací uživatelského rozhraní do procesu vykreslování.

Tyto balíčky vlastností umožňují vytvářet vlastní vlastnosti a definice v přizpůsobeném uživatelském rozhraní a poté být zpracovány procesem vykreslování. Všechny kontejnery vlastností jsou zpřístupněny pomocí rozhraní IPrinterScriptablePropertyBag v JavaScriptu nebo pomocí rozhraní IPrinterPropertyBag v jiných prostředích.

Následující tabulka obsahuje přehled o tom, jak pomocí různých komponent získat objekt tašky vlastností z různých částí tiskového ovladače v4.

Komponenta	Popis
Skript omezení JavaScriptu	Balíčky vlastností ovladače a fronty se předávají skriptům omezení v JavaScriptu pomocí parametru scriptContext. Tento parametr je typu IPrinterScriptContext a obsahuje děti: DriverProperties – odkazuje na sadu vlastností ovladače. QueueProperties – odkazuje na sadu vlastností fronty. UserProperties – taška vlastností uživatele. Soubor vlastností DEVMODE je předán do metod převodu PrintTicket DEVMODE <-> jako parametr devModeProperties (který je typu IPrinterScriptablePropertyBag). Není k dispozici u ostatních metod.
USB Bidi JavaScript	Kontejnery vlastností ovladače a fronty se předávají skriptům USB Bidi JavaScript pomocí parametru scriptContext. Tento parametr je typu IPrinterScriptContext a obsahuje podřízené prvky: DriverProperties – odkazuje na sadu vlastností ovladače. QueueProperties – odkazuje na sadu vlastností fronty.
Aplikace rozšíření tiskárny	Součástí parametru IPrinterExtensionEventArgs, který se předává obslužné rutině OnDriverEvent, jsou všechny kontejnery vlastností. Všechny jsou typu IPrinterPropertyBag. Jsou zadány takto: DriverProperties – odkazuje na kolekci vlastností ovladače. UserProperties – taška vlastností uživatele. PrinterQueue.GetProperties()– odkazuje na kolekci vlastností fronty.
Aplikace zařízení pro UWP	Všechny kontejnery vlastností jsou předány během aktivace prostřednictvím objektu IPrinterExtensionContext. Jsou zadány takto: DriverProperties – odkazuje na sadu vlastností ovladače. UserProperties – taška vlastností uživatele. PrinterQueue.GetProperties()– odkazuje na kolekci vlastností fronty.
Filtr vykreslování XPS	Filtry XPS mají přístup k balíčku vlastností ovladače z kontejneru vlastností kanálu filtru tisku pomocí názvu vlastnosti DriverPropertyBag nebo definované hodnoty XPS_FP_PROPERTY_BAG z filterpipeline.h. Zde jsou informace o DriverPropertyBag: typ vlastnosti : VT_UNKNOWN Popis: ukazatel na rozhraní IUnknown. Zavolejte QueryInterface, abyste získali ukazatel na rozhraní IPrinterPropertyBag k vlastnostní tašce ovladače. Filtry XPS mohou přistupovat k úložišti vlastností fronty v rámci úložiště vlastností potrubí filtru tisku pomocí názvu vlastnosti "QueuePropertyBag" nebo definovanou hodnotou XPS_FP_QUEUE_PROPERTY_BAG z filterpipeline.h. Zde jsou informace o QueuePropertyBag: typ vlastnosti : VT_UNKNOWN Popis: ukazatel na rozhraní IUnknown. Zavolejte QueryInterface, abyste získali ukazatel na rozhraní IPrinterPropertyBag k vlastnostní tašce fronty.

V implementacích JavaScriptu se kontejnery vlastností předávají jako parametry. V aplikacích rozšíření tiskárny jsou datové balíky vlastností předány jako členové argumentu události použitého ke spuštění aplikace.

Přístupové metody pro kolekce vlastností poskytované rozhraními COM IPrinterQueue, IPrinterExtensionContext a IPrinterExtensionEventArgs, stejně jako v implementacích JavaScriptu, vyvolají výjimku, pokud není specifikována nebo nenalezena kolekce vlastností. Kromě toho dotazování na jednotlivé vlastnosti v IPrinterPropertyBag rozhraní vyvolá výjimky, pokud vlastnost není nalezena. Měli byste použít příkaz try catch, abyste se vyhnuli pádu programu, pokud vlastnost není k dispozici.

Taška vlastností ovladače

Balíček vlastností ovladače je úložiště dat pro ovladače k předdefinování vlastností nebo ke čtení datových bloků pouze ovladačem. Lze jej zadat pomocí direktivy PropertyBag v souboru manifestu v4 a nelze jej změnit za běhu.

Sada Windows Driver Kit obsahuje projekt šablony pro tašku vlastností ovladače. Vlastnostní taška ovladače je kompilovaný binární soubor. Visual Studio obsahuje šablonu pro vygenerování zkompilované sady vlastností ovladače. Soubor XML vygenerovaný pro tuto šablonu není taška vlastností, místo toho zkompilovaný výstup této šablony je soubor tašky vlastností, který by měl být zadán v souboru manifestu v4.

Uživatelský kontejner vlastností

Taška vlastností uživatele umožňuje partnerům ukládat nastavení v místním kontextu pro jednotlivé uživatele. Tato struktura vlastností je vhodná jako úložiště pro uživatelské předvolby, například "Nezobrazovat znovu". Tato taška vlastností není spravovatelná správci a během sdílení tiskárny se nesynchronuje mezi klientem a serverem. Sada vlastností uživatele je nastavena pouze za běhu a je k dispozici pouze pro rozšíření tiskárny, aplikace pro zařízení UPW a omezení JavaScriptu.

Vzhledem k tomu, že omezení JavaScriptu mohou být také volána mimo uživatelský kontext, během despoolingu není v této fázi dostupná uživatelská vlastnost a Windows vrátí HRESULT_FROM_WIN32(ERROR_NOT_FOUND).

Kontejner vlastností DEVMODE

Sada vlastností DEVMODE slouží k uspořádání obsahu v privátní části struktury DEVMODE. Během volání ConvertPrintTicketToDevMode je JavaScript vyvolán k naplnění obsahu objektu vlastností DEVMODE. Při volání ConvertDevModeToPrintTicket se vyvolá JavaScript, který přečte trvalé nastavení z balíčku vlastností DEVMODE a uloží je zpět do PrintTicketu.

Tato kolekce vlastností je omezená na méně než 60 kB (přesná hodnota se bude lišit v závislosti na velikosti přidělených částí DEVMODE), protože se musí serializovat do struktury DEVMODE, aby se zabránilo ztrátě dat v některých scénářích. Přesná velikost, která je k dispozici, se bude lišit pro jednotlivé ovladače, protože je určena velikostí veřejné části modulu DEVMODE a privátním oddílem spravovaným modulem konfigurace.

Sada vlastností DEVMODE používá soubor XML k určení členů kontejneru vlastností a využívá API convertPrintTicketToDevMode a convertDevModeToPrintTicket pro zpracování převodů. Soubor mapování XML DEVMODE musí být zadán v manifestu v4 pomocí direktivy DevModeMap.

Následující fragment kódu ukazuje ukázku XML mapování kontejneru vlastností 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>

Následující snímek obrazovky ukazuje schéma XML mapování DEVMODE Property Bag a najdete na následující cestě v instalační složce WDK: \Include\um\printerdriverdevmodemap.xsd.pr

schématu XML mapování balíčku vlastností devmode.

Soubory XML pro mapování balíčku vlastností DEVMODE jsou ověřeny nástrojem INFGate.

Sada vlastností fronty

Datová struktura vlastností fronty ukládá nastavení konfigurace pro jednotlivé fronty, včetně namapování formulářů na zásobníky a konfigurace vlastností tiskárny, například instalovatelné možnosti. Vlastnosti definované ovladačem a vlastnosti tiskárny lze konfigurovat v PowerShellu, zatímco mapování formulářů na zásobníky lze konfigurovat v uživatelském rozhraní vlastností tiskárny. Rozšíření tiskárny nemohou upravovat žádné hodnoty vlastností.

Sada vlastností fronty se vytvoří automaticky pro mnoho ovladačů tisku v4, ale ovladače mohou také poskytovat další vlastnosti pro konfiguraci pomocí souboru XML. Tento soubor XML by neměl být zkompilován pomocí nástroje pro správu vlastností ovladače. Tašky vlastností tiskové fronty jsou k dispozici pro tiskárny podporované ovladači tisku verze 4 (v4), které provádějí jednu z následujících akcí:

Specifikujte více zásobníků nebo
Určení instalovatelných možností v souboru GPD nebo PPD NEBO
Zadejte v manifestu ovladače sadu vlastností fronty pomocí direktivy QueueProperties.

Správci konfigurují balíčky vlastností fronty pomocí PowerShellu. Následující cmdlety jsou podřízené objektu tiskárny, které lze získat pomocí cmdletu Get-Printer.

Název cmdletu	Popis
> Get-PrinterProperty -printerName <printerName> -name <propertyName*	Načte jednu nebo více vlastností (-name podporuje globbing).
Set-PrinterProperty -inputObject <printerPropertyObject>	Změní vlastnost tiskové fronty pomocí uloženého objektu vlastnosti tiskárny.
Set-PrinterProperty -printerName <název tiskárny> -PropertyName <vlastnostName> -Value <hodnota>	Změní vlastnost zadanou na zadanou hodnotu.

Možnosti instalace

Tyto možnosti, například stav duplexního nástroje, budou vystaveny do kontejneru vlastností fronty jako jednotlivé vlastnosti. Každá vlastnost bude pojmenována následujícím způsobem, kde název funkce vychází z názvu funkce ze souboru GPD nebo PPD ovladače:

Config:<feature name>

Například Config:DuplexUnit

Hodnota vlastnosti je název klíčového slova pro možnost, která byla vybrána správcem. Například Nainstalováno. Možnosti instalace se dají upravit pomocí stejné rutiny Set-PrinterProperty, která se používá pro vlastnosti fronty.

Počínaje Windows 8.1 může uživatel s právy správce nebo uživatel, který vytvořil tiskovou frontu, změnit instalovatelné možnosti a nastavení konfigurace fronty pro vlastnosti fronty z aplikace zařízení UWP.

Mapování formulářů na zásobník

Pro tiskárny s ovladačem tisku v4 a s více než jedním zásobníkem jsou mapování "formulář na zásobník" vystavena prostřednictvím sady vlastností fronty ve vlastnosti s názvem "FormTrayTable".

Tato vlastnost je formátována jako řetězec ukončený hodnotou null obsahující páry formátu <tray name>, <form name>,, kde název formuláře je jeden z následujících:

Pokud je formát papíru namapován na schéma tisku v souboru GPD nebo PPD (buď pomocí standardních klíčových slov *PaperSize/*PageSize, nebo *(MS)PrintSchemaKeywordMap), bude název formuláře následovat v následujícím formátu:

PrintSchema:<Paper Size name>

Například PrintSchema:NorthAmericaLetter
Pokud je formulář uživatelem definovaným příznakem FORM_USER, bude název formuláře následující. Index formuláře je stejná hodnota použitá v databázi formulářů spouštěče. To je konzistentní s indexem použitým při zadání formátu papíru v printTicketu následujícím způsobem:

UserForm<form index>

Například UserForm123
V opačném případě bude název formuláře následovat v následujícím formátu, kde název formuláře je název zadaný v souboru GPD *PaperSize nebo PPD *PageSize.

Config:<name>

Například Config:_8_5x16

Úplný ukázkový řetězec by se četl takto:

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

Vykreslovací filtry by měly číst nastavení PageMediaSize příchozího souboru PrintTicket a vyhledat tuto hodnotu v hodnotách názvů formulářů z FormTrayTable.

Ukázka XML souboru balíčku vlastností fronty

Následující fragment kódu ukazuje syntaxi XML, kterou je možné použít pro tři vlastnosti, Name1, Name2, Name3 a jejich podřízené prvky:

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

Schéma XML v pytli vlastností fronty

Následující snímek obrazovky zobrazuje schéma vlastností fronty ve formátu XML a lze jej najít v této cestě v instalační složce WDK: \Include\um\printqueueproperties.xsd.

kontejner vlastností fronty XML schématu.