IPrintTicketProvider2 ::BindPrinter, méthode (prdrvcom.h)

Article
02/07/2025

La méthode IPrintTicketProvider2 ::BindPrinter lie une imprimante ou une file d’attente d’impression à une version spécifique du schéma de ticket d’impression, ce qui permet au pilote principal d’associer un ensemble d’URI (Uniform Resource Identifiers) d’espace de noms privé à un appareil.

Syntaxe

HRESULT BindPrinter(
  [in]  IN HANDLE     hPrinter,
  [in]  IN INT        version,
  [out] OUT PSHIMOPTS pOptions,
  [out] OUT DWORD     *pDevModeFlags,
  [out] OUT INT       *cNamespaces,
  [out] OUT BSTR      **ppNamespaces
);

Paramètres

[in] hPrinter

Poignée d’impression du spouleur, fournie par le pilote principal. Le fournisseur ne doit pas fermer ce handle à tout moment, car le client du fournisseur est responsable de la gestion de la durée de vie de ce handle. Le fournisseur peut mettre en cache le handle d’impression ; tous les appels futurs sont relatifs à l’imprimante associée à ce handle.

[in] version

Numéro de version principal du ticket d’impression ou du schéma de ticket d’impression que le gestionnaire de tickets d’impression demande au fournisseur de plug-in OEM de prendre en charge. Windows Vista prend uniquement en charge la version 1. Le fournisseur doit échouer toute tentative de liaison à une version qu’il ne prend pas en charge ou ne reconnaît pas.

[out] pOptions

Pointeur vers une variable qui reçoit l’une des valeurs énumérées suivantes :

PTSHIM_DEFAULT

Le système place un encodage binaire (objet BLOB - objet volumineux binaire) de la partie privée de la structure DEVMODEW dans le ticket d’impression dans une conversion d’un DEVMODEW en ticket d’impression.
PTSHIM_NOSNAPSHOT

Le système ne placera pas d’encodage binaire (objet BLOB) de la partie privée de la structure DEVMODEW dans le ticket d’impression dans une conversion d’un DEVMODEW en ticket d’impression. Utilisez cette valeur si tous les membres du PUBLIC et privé DEVMODEW sont entièrement représentés dans le ticket d’impression.

[out] pDevModeFlags

Pointeur vers une variable typée DWORD qui reçoit un ensemble d’indicateurs de bits qui indiquent quels membres publics DEVMODEW ne doivent pas être traités par le shim de ticket d’impression dans le ticket DEVMODEW à imprimer ou les conversions ticket-à-DEVMODEW. Un indicateur de bits présent dans ce paramètre indique que l’imprimante ne prend pas en charge le membre DEVMODEW associé ou que le fournisseur gère cette caractéristique DEVMODEW. Par exemple, si DM_MEDIATYPE est défini dans *pDevModeFlags, l’imprimante ne prend pas en charge plusieurs types de supports, ou le fournisseur est responsable de la prise en charge de plusieurs types de supports. (Tous les indicateurs de bits DM_XXX sont définis dans wingdi.h et décrits dans le Kit de développement logiciel (SDK) Microsoft Windows.) Par défaut, le shim du ticket d’impression gère tous les membres représentés dans la structure dmFlags membre par défaut DEVMODEW.

[out] cNamespaces

Pointeur vers une variable qui reçoit le nombre d’URI d’espace de noms privés utilisés dans le plug-in. Ce nombre représente le nombre de chaînes dans le tableau pointé par ppNamespaces.

[out] ppNamespaces

Pointeur vers une variable qui reçoit l’adresse du premier élément d’un tableau BSTR. Le plug-in remplit chaque position de tableau avec un URI d’espace de noms. Pour plus d’informations sur ce paramètre, consultez la section Remarques suivante.

Valeur de retour

IPrintTicketProvider2 ::BindPrinter doit retourner l’une des valeurs suivantes :

Retourner le code	Description
S_OK	L’opération a réussi.
E_VERSION_NOT_SUPPORTED	Le plug-in ne prend pas en charge la version du schéma d’impression spécifié dans le paramètre version.

Remarques

La liaison à un appareil permet au fournisseur de mettre en cache certains objets et de gérer qu’il aura besoin d’un futur ticket d’impression ou des services de fonctionnalités d’appareil sur cet appareil. Par exemple, le handle d’imprimante dans le paramètre hPrinter peut être mis en cache. La méthode IPrintTicketProvider2 ::BindPrinter est garantie d’être appelée une seule fois.

Le pilote est responsable de l’allocation de mémoire pour le tableau vers lequel pointe le paramètre ppNamespaces et les chaînes d’URI d’espace de noms. Le tableau doit être alloué à l’aide de la fonction CoTaskMemAlloc ; les chaînes d’espace de noms doivent être allouées à l’aide de la fonction SysAllocString. Les deux fonctions sont décrites dans la documentation du Kit de développement logiciel (SDK) Windows. Le tableau vers lequel pointe le paramètre ppNamespaces n’est pas nécessaire pour contenir les espaces de noms pour les mots clés de schéma d’impression ou l’infrastructure de schéma d’impression.

Un objet IPrintTicketProvider2 ne doit pas être en mesure de lier plusieurs fois. Le gestionnaire de tickets d’impression utilise toujours différentes IPrintTicketProvider2 instances d’objet pour la liaison à différents appareils. Toutes les ressources acquises dans un appel réussi à IPrintTicketProvider2 ::BindPrinter doivent être libérées lorsque le nombre de références d’un objet IPrintTicketProvider2 est égal à zéro. Notez que le fournisseur ne doit pas fermer le handle passé à l’appel pour BindPrinter. Le gestionnaire de tickets d’impression peut créer plusieurs fournisseurs pour le même appareil, dans différentes versions, si plusieurs versions sont prises en charge.