Méthode IPrintOemPrintTicketProvider ::BindPrinter (prcomoem.h)

Article
02/27/2024

La méthode IPrintOemPrintTicketProvider ::BindPrinter permet au pilote principal d’associer un ensemble d’identificateurs de ressources uniformes (URI) d’espace de noms privés à un appareil. Cette méthode permet également au plug-in de mettre en cache des informations (telles que le handle d’imprimante) qui peuvent être utilisées ultérieurement.

Syntaxe

HRESULT BindPrinter(
  [in]  HANDLE     hPrinter,
  [in]  INT        version,
  [out] POEMPTOPTS pOptions,
  [out] INT        *cNamespaces,
  [out] BSTR       **ppNamespaces
);

Paramètres

[in] hPrinter

La poignée d’impression du spouleur, qui est fournie par Unidrv. 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 sur cet objet sont relatifs à l’imprimante associée à ce handle.

[in] version

Numéro de version principal du schéma d’impression. Windows Vista prend uniquement en charge la version 1.

[out] pOptions

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

OEMPT_DEFAULT

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

OEMPT_NOSNAPSHOT

Le système ne place pas d’encodage binaire (objet BLOB) de la structure DEVMODEW privée 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.

L’objet OEM appelé doit définir la valeur pointée vers ce paramètre.

[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 est pointé *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

IPrintOemPrintTicketProvider ::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

Le plug-in 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 . Ces deux fonctions sont décrites dans la documentation Microsoft Windows SDK. 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.

La liaison à un appareil permet au fournisseur de mettre en cache certains objets et de gérer ce dont il aura besoin pour les futurs services de ticket d’impression ou de fonctionnalités d’impression sur cet appareil. Par exemple, le handle d’imprimante dans hPrinter peut être mis en cache. IPrintOemPrintTicketProvider ::BindPrinter est garanti pour être appelé une seule fois.

Un objet IPrintOemPrintTicketProvider ne doit pas être en mesure de lier plusieurs fois. Le gestionnaire de tickets d’impression utilise toujours différentes instances d’objet IPrintOemPrintTicketProvider pour la liaison à différents appareils. Toutes les ressources acquises lors d’un appel réussi à IPrintOemPrintTicketProvider ::BindPrinter doivent être libérées lorsque le nombre de références d’un objet IPrintOemPrintTicketProvider 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.