Méthode IPrintTicketProvider ::BindPrinter (prdrvcom.h)

Article
02/29/2024

La méthode IPrintTicketProvider ::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’identificateurs de ressources uniformes (URI) d’espace de noms privés à 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

La poignée d’impression du spouleur, qui est fournie par le pilote principal. Le fournisseur ne doit pas fermer ce handle à aucun 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 binaire de grande taille) 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 place pas d’encodage binaire (objet BLOB) de la partie privée de la structure DEVMODEW dans le ticket d’impression lors d’une conversion d’un DEVMODEW en ticket d’impression. Utilisez cette valeur si tous les membres DEVMODEW publics et privés sont entièrement représentés dans le ticket d’impression.

[out] pDevModeFlags

Pointeur vers une variable de type DWORD qui reçoit un ensemble d’indicateurs de bits qui indiquent quels membres DEVMODEW publics ne doivent pas être traités par le shim du ticket d’impression dans les conversions de ticket d’impression devMODEW ou de ticket d’impression à 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, soit l’imprimante ne prend pas en charge plusieurs types de médias, soit le fournisseur est responsable de la prise en charge de plusieurs types de médias. (Tous les indicateurs de bits DM_XXX sont définis dans wingdi.h et décrits dans le Microsoft Windows SDK.) Par défaut, le shim du ticket d’impression gère tous les membres qui sont représentés dans le membre dmFlags de la structure DEVMODEW par défaut.

[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 vers lequel pointe 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 retournée

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

Code de retour	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ée dans le paramètre version .

Remarques

La liaison à un appareil permet au fournisseur de mettre en cache certains objets et gère ce dont il aura besoin pour les futurs services de ticket d’impression ou 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 IPrintTicketProvider ::BindPrinter est garantie d’être appelée une seule fois.

Le pilote est responsable de l’allocation de la mémoire pour le tableau vers lequel pointe le paramètre ppNamespaces et des 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 obligatoire pour contenir les espaces de noms des mots clés du schéma d’impression ou de l’infrastructure de schéma d’impression.

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