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

Article
02/26/2024

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’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 schéma de ticket d’impression ou 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 (blob - objet binaire volumineux) 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 (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 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 de ticket d’impression dans devMODEW-to-print ticket ou print ticket-to-DEVMODEW conversions. 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 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

IPrintTicketProvider2 ::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 les handles dont il aura besoin pour les futurs services de fonctionnalités de ticket d’impression ou 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 pour 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 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 IPrintTicketProvider2 ne doit pas être en mesure de lier plusieurs fois. Le gestionnaire de tickets d’impression utilise toujours différentes instances d’objet IPrintTicketProvider2 pour la liaison à différents appareils. Toutes les ressources acquises lors d’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é dans l’appel à 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.