Sacs de propriétés du pilote d'imprimante V4
Important
La plateforme d’impression moderne est le moyen privilégié de Windows pour communiquer avec les imprimantes. Nous vous recommandons d’utiliser le pilote de classe IPP en boîte de Microsoft, ainsi que les applications de support d’impression (PSA), pour personnaliser l’expérience d’impression dans Windows 10 et 11 pour le développement de périphériques d’impression.
Pour plus d’informations, veuillez consulter la section Plateforme d’impression moderne et le Guide de conception des applications de support d’impression.
Le modèle de pilote d'impression v4 fournit un certain nombre de sacs de propriétés qui facilitent un flux de données entre les applications personnalisées de l'interface utilisateur et le processus de rendu.
Ces sacs de propriétés permettent de créer des propriétés personnalisées et des définitions de fonctionnalités dans une interface utilisateur personnalisée, puis de les utiliser dans le processus de rendu. Tous les sacs de propriétés sont exposés en utilisant l'interface IPrinterScriptablePropertyBag en JavaScript ou en utilisant l'interface IPrinterPropertyBag dans d'autres environnements.
Le tableau suivant donne un aperçu de la manière d'utiliser les différents composants pour obtenir l'objet « property bag » à partir de différentes parties d'un pilote d'impression v4.
| Composant | Description |
|---|---|
| Script de contrainte JavaScript | Les sacs de propriétés du pilote et de la file d'attente sont transmis aux scripts de contrainte JavaScript à l'aide du paramètre scriptContext. Ce paramètre est de type IPrinterScriptContext et contient des enfants : DriverProperties - fait référence à la propriété du pilote. QueueProperties - renvoie à la propriété de la file d'attente. UserProperties - La pochette de propriétés de l'utilisateur. Le sac de propriétés <DEVMODE est transmis aux méthodes de conversion DEVMOD>E - PrintTicket en tant que paramètre devModeProperties (qui est de type IPrinterScriptablePropertyBag). Elle n'est pas disponible pour les autres méthodes. |
| USB Bidi JavaScript | Les propriétés du pilote et de la file d'attente sont transmises aux scripts JavaScript USB Bidi à l'aide du paramètre scriptContext. Ce paramètre est de type IPrinterScriptContext et contient des enfants : DriverProperties - fait référence à la propriété du pilote. QueueProperties - renvoie à la propriété de la file d'attente. |
| Application d'extension d'imprimante | Tous les sacs de propriétés sont transmis en tant que paramètre IPrinterExtensionEventArgs au gestionnaire OnDriverEvent. Ils sont tous de type IPrinterPropertyBag. Ils sont spécifiés comme suit : DriverProperties - fait référence à la propriété du pilote. UserProperties - La pochette de propriétés de l'utilisateur. PrinterQueue.GetProperties()- fait référence au sac de propriétés de la file d'attente. |
| Application de l'appareil UWP | Tous les sacs de propriété sont transmis lors de l'activation à l'aide de l'objet IPrinterExtensionContext. Ils sont spécifiés comme suit : PrinterQueue.GetProperties() DriverProperties - fait référence à la propriété du pilote. UserProperties - La pochette de propriétés de l'utilisateur. PrinterQueue.GetProperties()- fait référence au sac de propriétés de la file d'attente. |
| Filtre de rendu XPS | Les filtres XPS peuvent accéder au sac de propriétés du pilote à partir du sac de propriétés du pipeline de filtre d'impression en utilisant le nom de propriété « DriverPropertyBag » ou la valeur définie XPS_FP_PROPERTY_BAG dans filterpipeline.h. Voici des informations sur DriverPropertyBag : Type de propriété : VT_UNKNOWN Description : Pointeur sur une interface IUnknown. Appelez QueryInterface pour obtenir un pointeur sur l'interface IPrinterPropertyBag du sac de propriétés du pilote. Les filtres XPS peuvent accéder au sac de propriétés de la file d'attente à partir du sac de propriétés du pipeline du filtre d'impression en utilisant le nom de propriété « QueuePropertyBag » ou la valeur définie XPS_FP_QUEUE_PROPERTY_BAG dans filterpipeline.h. Voici des informations sur QueuePropertyBag : Type de propriété : VT_UNKNOWN Description : Pointeur sur une interface IUnknown. Appelez QueryInterface pour obtenir un pointeur sur l'interface IPrinterPropertyBag du sac de propriétés de la file d'attente. |
Dans les implémentations JavaScript, les sacs de propriétés sont transmis en tant que paramètres. Dans les applications d'extension d'imprimante, les sacs de propriétés sont transmis en tant que membres de l'argument d'événement utilisé pour démarrer l'application.
Les accesseurs de sacs de propriétés fournis par les interfaces COM IPrinterQueue, IPrinterExtensionContext et IPrinterExtensionEventArgs ainsi que les accesseurs de sacs de propriétés dans les implémentations Javascript lèveront une exception si le sac de propriétés n'est pas spécifié ou n'est pas trouvé. En outre, la recherche de propriétés individuelles sur une interface IPrinterPropertyBag lèvera des exceptions si la propriété n'est pas trouvée. Vous devez utiliser une instruction « try catch » pour éviter un plantage si une propriété n'est pas disponible.
Sac de propriétés du pilote
Le sac de propriétés du pilote est un magasin de données permettant aux pilotes de prédéfinir des propriétés ou des blocs de données destinés à être utilisés en lecture seule par le pilote. Il peut être spécifié en utilisant la directive « PropertyBag » dans le fichier manifeste v4 et ne peut pas être modifié à l'exécution.
Le kit du pilote Windows comprend un projet modèle pour un sac de propriétés du pilote. La propriété du pilote est un blob binaire compilé. Visual Studio comprend un modèle pour générer un fichier de propriétés de pilote compilé. Le fichier XML généré pour ce modèle n'est pas la propriété, mais la sortie compilée de ce modèle est le fichier de propriété qui doit être spécifié dans le fichier manifeste v4.
Pochette de propriétés de l'utilisateur
La pochette de propriétés de l'utilisateur permet aux partenaires de stocker des paramètres dans un contexte local par utilisateur et par machine. Cette propriété est bien adaptée comme mécanisme de stockage pour les préférences de l'utilisateur telles que « Ne plus montrer ceci ». Cette propriété n'est pas gérable par les administrateurs et n'est pas synchronisée entre le client et le serveur lors du partage d'imprimantes. La propriété de l'utilisateur n'est définie qu'au moment de l'exécution et n'est accessible qu'aux extensions d'imprimante, aux applications d'appareil UWP et aux contraintes JavaScript.
Étant donné que les contraintes JavaScript peuvent également être appelées en dehors d'un contexte utilisateur, lors du déstockage, le sac de propriétés de l'utilisateur n'est pas disponible à ce moment-là et Windows renvoie HRESULT_FROM_WIN32(ERROR_NOT_FOUND).
Sac de propriétés DEVMODE
La pochette de propriétés DEVMODE est utilisée pour organiser le contenu de la section privée de la structure DEVMODE. Lors des appels ConvertPrintTicketToDevMode, JavaScript est invoqué pour remplir le contenu de la pochette de propriétés DEVMODE. Lors des appels ConvertDevModeToPrintTicket, JavaScript est invoqué pour lire les paramètres persistants du sac de propriétés DEVMODE et les stocker à nouveau dans le PrintTicket.
La taille de cette propriété est limitée à moins de 60 Ko (la quantité exacte varie en fonction de la taille des sections allouées du DEVMODE), car elle doit être sérialisée dans une structure DEVMODE afin d'éviter la perte de données dans certains scénarios. La taille exacte disponible varie selon le pilote car elle est déterminée par la taille de la section publique de DEVMODE plus la section privée gérée par le module de configuration.
La pochette de propriétés DEVMODE utilise un fichier XML pour spécifier les membres de la pochette de propriétés et utilise les API convertPrintTicketToDevMode et convertDevModeToPrintTicket pour gérer les conversions. Le fichier XML de mappage DEVMODE doit être spécifié dans le manifeste v4 à l'aide de la directive DevModeMap.
L'extrait de code suivant montre un exemple XML de mappage de sac de propriété 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>
La capture d'écran suivante montre le schéma XML de mappage de sac de propriété DEVMODE, et il peut être trouvé au chemin suivant dans le dossier d'installation du WDK : \NInclude\Nprinterdriverdevmodemap.xsd.pr
Les fichiers XML pour le mappage des sacs de propriétés DEVMODE sont validés par l'outil INFGate.
Sac de propriétés de la file d'attente
Le sac de propriétés de la file d'attente stocke les paramètres de configuration par file d'attente, y compris les mappages du formulaire au plateau et la configuration des propriétés de l'imprimante comme les options installables. Les propriétés définies par le pilote et les propriétés de l'imprimante sont configurables dans PowerShell, tandis que les mappages formulaire/plateau sont configurables dans l'interface utilisateur des propriétés de l'imprimante. Les extensions d'imprimante ne peuvent pas modifier les valeurs des propriétés.
Le sac de propriétés de la file d'attente est créé automatiquement pour de nombreux pilotes d'impression v4, mais les pilotes peuvent également fournir des propriétés supplémentaires à configurer à l'aide d'un fichier XML. Ce fichier XML ne doit pas être compilé à l'aide de l'outil de gestion des propriétés du pilote. Les propriétés de file d'attente sont disponibles pour les imprimantes prises en charge par les pilotes d'impression v4 qui présentent l'une des caractéristiques suivantes :
Spécifier des bacs multiples, OU
Spécifier des options installables dans le fichier GPD ou PPD, OU
Spécifier une propriété de file d'attente dans le manifeste du pilote à l'aide de la directive QueueProperties.
Les administrateurs configurent les sacs de propriétés de file d'attente à l'aide de PowerShell. Les commandes suivantes (cmdlets) sont des enfants d'un objet imprimante, qui peut être obtenu à l'aide de la cmdlet Get-Printer.
| Nom de la cmdlet | Description |
|---|---|
| Get-PrinterProperty -printerName <printerName> -name <propertyName*> | Récupère une ou plusieurs propriétés (-name prend en charge le globbing). |
| Set-PrinterProperty -inputObject <printerPropertyObject> | Modifie une propriété de file d'attente d'impression à l'aide d'un printerPropertyObject persistant. |
| Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value> | Modifie la propriété spécifiée en lui attribuant la valeur spécifiée. |
Options installables
Ces options, par exemple l'état d'un duplexeur, seront exposées dans le sac de propriétés de la file d'attente en tant que propriétés individuelles. Chaque propriété sera nommée comme suit, où le nom de la fonctionnalité est basé sur le nom de la fonctionnalité du fichier GPD ou PPD du pilote :
Config:<feature name>
Par exemple, Config:DuplexUnit
La valeur de la propriété est le nom du mot-clé de l'option qui a été sélectionné par l'administrateur. Par exemple, Installé. Les options installables sont modifiables à l'aide de la même cmdlet Set-PrinterProperty que celle utilisée pour les propriétés de file d'attente.
À partir de Windows 8.1, un utilisateur disposant de droits d'administrateur ou un utilisateur ayant créé une file d'attente d'impression peut modifier les options installables et les paramètres de configuration par file d'attente pour un sac de propriétés de file d'attente à partir d'une application d'appareil UWP.
Mappages entre le formulaire et le bac
Pour les imprimantes dotées d'un pilote d'impression v4 et de plusieurs bacs, les mappages « formulaire/plateau » sont exposés via le sac de propriétés de la file d'attente dans la propriété nommée « FormTrayTable ».
Cette propriété est formatée comme une chaîne à terminaison nulle contenant des appaires du format <tray name>, <form name>, où le nom du formulaire est l'un des suivants :
Si le format du papier est mappé dans le schéma d'impression du fichier GPD ou PPD (soit en utilisant les mots-clés standard *PaperSize/*PageSize, soit *(MS)PrintSchemaKeywordMap), le nom du formulaire suivra le format suivant :
PrintSchema:<Paper Size name>Par exemple,
PrintSchema:NorthAmericaLetterSi le formulaire est un formulaire défini par l'utilisateur, tel que déterminé par l'indicateur FORM_USER, le nom du formulaire suivra le format suivant. L'index du formulaire est la même valeur que celle utilisée dans la base de données des formulaires du spouleur. Cela correspond à l'index utilisé lorsque la taille du papier est spécifiée dans le PrintTicket comme suit :
UserForm<form index>Par exemple,
UserForm123Sinon, le nom du formulaire suivra le format suivant, où le nom du formulaire est le nom qui a été spécifié dans *PaperSize de GPD ou *PageSize de PPD.
Config:<name>Par exemple,
Config:_8_5x16
Un exemple complet de chaîne de caractères se lirait comme suit :
Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0
Les filtres de rendu doivent lire le paramètre PageMediaSize du ticket d'impression entrant et rechercher cette valeur dans les valeurs de nom de formulaire de la table FormTrayTable.
Exemple XML de sac de propriété de file d'attente
L'extrait de code suivant montre la syntaxe XML qui pourrait être utilisée pour trois propriétés, Name1, Name2, Name3 et leurs éléments enfants :
<?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 du sac de propriétés de la file d'attente
La capture d'écran suivante montre le schéma XML du sac de propriétés de la file d'attente, qui se trouve dans le dossier d'installation du WDK : \NInclude\Nprintqueueproperties.xsd.
