Sacs de propriétés du pilote d’imprimante V4

Article
03/08/2023

Important

Nous vous recommandons d’utiliser le pilote de classe de boîte de réception IPP 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 d’appareils d’imprimante.

Pour plus d’informations, consultez le guide de conception d’application de prise en charge de l’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 des applications d’interface utilisateur personnalisées vers 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 caractéristiques dans une interface utilisateur personnalisée, puis d’être consommées par le processus de rendu. Tous les sacs de propriétés sont exposés à l’aide de l’interface IPrinterScriptablePropertyBag dans JavaScript ou de l’interface IPrinterPropertyBag dans d’autres environnements.

Le tableau suivant fournit une vue d’ensemble de l’utilisation de différents composants pour obtenir l’objet de conteneur de propriétés à partir de différentes parties d’un pilote d’impression v4.

Composant	Description
Script de contrainte JavaScript	Les sacs de propriétés de pilote et de file d’attente sont passés 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 au sac de propriétés du pilote. QueueProperties : fait référence au conteneur de propriétés de file d’attente. UserProperties : le conteneur de propriétés utilisateur. Le conteneur de propriétés DEVMODE est passé dans les méthodes de conversion DEVMODE <-> PrintTicket en tant que paramètre devModeProperties (qui est de type IPrinterScriptablePropertyBag). Il n’est pas disponible sur les autres méthodes.
USB Bidi JavaScript	Les sacs de propriétés de pilote et de file d’attente sont transmis aux scripts JavaScript Bidi USB à l’aide du paramètre scriptContext. Ce paramètre est de type IPrinterScriptContext et contient des enfants : DriverProperties : fait référence au sac de propriétés du pilote. QueueProperties : fait référence au conteneur de propriétés de file d’attente.
Application d’extension d’imprimante	Tous les sacs de propriétés sont transmis dans le cadre du paramètre IPrinterExtensionEventArgs au gestionnaire OnDriverEvent. Ils sont tous de type IPrinterPropertyBag. Ils sont spécifiés comme suit : DriverProperties : fait référence au sac de propriétés du pilote. UserProperties : le conteneur de propriétés utilisateur. PrinterQueue.GetProperties(): fait référence au conteneur de propriétés de file d’attente
Application d’appareil UWP	Tous les sacs de propriétés sont transmis lors de l’activation à l’aide de l’objet IPrinterExtensionContext . Ils sont spécifiés comme suit : DriverProperties : fait référence au sac de propriétés du pilote. UserProperties : le conteneur de propriétés utilisateur. PrinterQueue.GetProperties(): fait référence au conteneur de propriétés de file d’attente
Filtre de rendu XPS	Les filtres XPS peuvent accéder au conteneur de propriétés de pilote à partir du conteneur de propriétés de pipeline de filtre d’impression à l’aide du nom de propriété « DriverPropertyBag » ou de la valeur définie XPS_FP_PROPERTY_BAG à partir de filterpipeline.h. Voici des informations sur DriverPropertyBag : Type de propriété : VT_UNKNOWN Description: Pointeur vers une interface IUnknown. Appelez QueryInterface pour obtenir un pointeur vers l’interface IPrinterPropertyBag vers le conteneur de propriétés du pilote. Et les filtres XPS peuvent accéder au conteneur de propriétés de file d’attente à partir du conteneur de propriétés de pipeline de filtre d’impression à l’aide du nom de propriété « QueuePropertyBag » ou de la valeur définie XPS_FP_QUEUE_PROPERTY_BAG à partir de filterpipeline.h. Voici des informations sur QueuePropertyBag : Type de propriété : VT_UNKNOWN Description: Pointeur vers une interface IUnknown. Appelez QueryInterface pour obtenir un pointeur vers l’interface IPrinterPropertyBag vers le conteneur de propriétés de 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 sac de propriétés fournis par les interfaces COM IPrinterQueue, IPrinterExtensionContext et IPrinterExtensionEventArgs, ainsi que les accesseurs de sac de propriétés dans les implémentations Javascript lèvent une exception si le conteneur de propriétés n’est pas spécifié ou introuvable. En outre, l’interrogation de propriétés individuelles sur une interface IPrinterPropertyBag lève des exceptions si la propriété est introuvable. Vous devez utiliser une instruction try catch pour éviter le blocage si une propriété n’est pas disponible.

Driver Property Bag

Le sac de propriétés de pilote est un magasin de données permettant aux pilotes de prédéfinir des propriétés ou des objets blob de données pour une utilisation en lecture seule par le pilote. Il peut être spécifié à l’aide de la directive « PropertyBag » dans le fichier manifeste v4 et ne peut pas être modifié au moment de l’exécution.

Le Kit de pilotes Windows inclut un projet de modèle pour un sac de propriétés de pilote. Le sac de propriétés du pilote est un objet blob binaire compilé. Visual Studio inclut un modèle pour générer un sac de propriétés de pilote compilé. Le fichier XML généré pour ce modèle n’est pas le conteneur de propriétés, mais la sortie compilée de ce modèle est le fichier de conteneur de propriétés qui doit être spécifié dans le fichier manifeste v4.

Sac de propriétés utilisateur

Le sac de propriétés utilisateur permet aux partenaires de stocker les paramètres dans un contexte local d’ordinateur par utilisateur. Ce conteneur de propriétés est bien adapté en tant que mécanisme de stockage pour les préférences de l’utilisateur telles que « Ne plus afficher cela ». Ce conteneur de propriétés n’est pas gérable par les administrateurs et n’est pas synchronisé entre le client et le serveur pendant le partage d’imprimante. Le sac de propriétés utilisateur est défini uniquement au moment de l’exécution et n’est disponible que pour les extensions d’imprimante, les applications d’appareil UWP et les contraintes JavaScript.

Étant donné que les contraintes JavaScript peuvent également être appelées en dehors d’un contexte utilisateur, lors du dépooling, le conteneur de propriétés utilisateur n’est pas disponible pour le moment et Windows retourne HRESULT_FROM_WIN32(ERROR_NOT_FOUND).

DEVMODE Property Bag

Le conteneur de propriétés DEVMODE est utilisé pour organiser le contenu dans la section privée de la structure DEVMODE. Pendant les appels ConvertPrintTicketToDevMode, JavaScript est appelé pour remplir le contenu du conteneur de propriétés DEVMODE. Pendant les appels ConvertDevModeToPrintTicket, JavaScript est appelé pour lire les paramètres persistants du conteneur de propriétés DEVMODE et les stocker à nouveau dans le PrintTicket.

Ce conteneur de propriétés est limité à moins de 60 Ko (la quantité exacte varie en fonction de la taille des sections allouées du DEVMODE), car il doit être sérialisé 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 du DEVMODE plus la section privée gérée par le module de configuration.

Le conteneur de propriétés DEVMODE utilise un fichier XML pour spécifier les membres du conteneur de propriétés et utilise les API convertPrintTicketToDevMode et convertDevModeToPrintTicket pour gérer les conversions. Le fichier de mappage DEVMODE XML 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 sacs de propriétés 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 sacs de propriétés DEVMODE, qui se trouve dans le chemin d’accès suivant dans le dossier d’installation WDK : \Include\um\printerdriverdevmodemap.xsd.pr

Schéma xml de mappage de sac de propriétés devmode.

Les fichiers XML du mappage de sacs de propriétés DEVMODE sont validés par l’outil INFGate.

Sac de propriétés de file d’attente

Le sac de propriétés de file d’attente stocke les paramètres de configuration par file d’attente, y compris les mappages de formulaire à plateau et la configuration des propriétés d’imprimante comme les options installables. Les propriétés définies par le pilote et les propriétés d’imprimante sont configurables dans PowerShell, tandis que les mappages de formulaire à plateau sont configurables dans l’interface utilisateur des propriétés de l’imprimante. Les extensions d’imprimante ne peuvent modifier aucune des valeurs de propriété.

Le sac de propriétés de 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 sac de propriétés du pilote. Les sacs de propriétés de file d’attente sont disponibles pour les imprimantes prises en charge par les pilotes d’impression v4 qui effectuent l’une des opérations suivantes :

Spécifier plusieurs plateaux, OR
Spécifier les options installables dans le fichier GPD ou PPD, OU
Spécifiez un conteneur de propriétés de file d’attente dans le manifeste du pilote à l’aide de la directive QueueProperties.

Les administrateurs configurent des sacs de propriétés de file d’attente à l’aide de PowerShell. Les commandes suivantes (applets de commande) sont des enfants d’un objet d’imprimante, qui peuvent être obtenus à l’aide de l’applet de commande Get-Printer.

Nom de l'applet de commande	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’une propriété printerPropertyObject persistante.
Set-PrinterProperty -printerName <printerName> -PropriétéName <->Valeur <>	Remplace la propriété spécifiée par la valeur spécifiée.

Options installables

Ces options, par exemple, l’état d’un duplexeur, sont exposées dans le conteneur de propriétés de file d’attente en tant que propriétés individuelles. Chaque propriété est 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 sélectionnée par l’administrateur. Par exemple, Installé. Les options installables sont modifiables à l’aide de la même applet de commande Set-PrinterProperty que celle utilisée pour les propriétés de file d’attente.

À compter de Windows 8.1, un utilisateur disposant de droits d’administrateur ou un utilisateur qui a créé une file d’attente d’impression peut modifier les options Installable et les paramètres de configuration par file d’attente pour un conteneur de propriétés de file d’attente à partir d’une application d’appareil UWP.

Mappages de formulaire à plateau

Pour les imprimantes avec un pilote d’impression v4 et avec plusieurs bacs, les mappages « formulaire à bac » sont exposés via le conteneur de propriétés de file d’attente dans la propriété nommée « FormTrayTable ».

Cette propriété est mise en forme sous la forme d’une chaîne terminée par null contenant des paires 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 dans le fichier GPD ou PPD (à l’aide des mots clés *PaperSize/*PageSize standard, ou *(MS)PrintSchemaKeywordMap), le nom du formulaire suit le format suivant :

PrintSchema:<Paper Size name>

Par exemple : PrintSchema:NorthAmericaLetter
Si le formulaire est un formulaire défini par l’utilisateur, tel que déterminé par l’indicateur FORM_USER, le nom du formulaire est le suivant. L’index de formulaire est la même valeur que celle utilisée dans la base de données de formulaires du spouleur. Cela est cohérent avec l’index utilisé lorsque le format de papier est spécifié dans le PrintTicket comme suit :

UserForm<form index>

Par exemple : UserForm123
Sinon, le nom du formulaire suit le format suivant, où le nom du formulaire est le nom spécifié dans *PaperSize du GPD ou *PageSize du PPD.

Config:<name>

Par exemple : Config:_8_5x16

Un exemple de chaîne complet se lit 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 PrintTicket entrant et rechercher cette valeur dans les valeurs de nom de formulaire à partir de FormTrayTable.

Exemple XML de conteneur de propriétés de file d’attente

L’extrait de code suivant montre la syntaxe XML qui peut ê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 conteneur de propriétés de file d’attente

La capture d’écran suivante montre le schéma XML du conteneur de propriétés de file d’attente, qui se trouve dans le chemin d’accès suivant dans le dossier d’installation WDK : \Include\um\printqueueproperties.xsd.

schéma xml de conteneur de propriétés de file d’attente.