Fonction DrvPrinterEvent (winddiui.h)

La fonction DrvPrinterEvent d’une DLL d’imprimante est appelée par le spouleur d’impression lors du traitement des événements spécifiques à l’imprimante qui peuvent nécessiter une action du pilote d’imprimante.

Syntaxe

BOOL DrvPrinterEvent(
  [in] LPWSTR pPrinterName,
       int    DriverEvent,
       DWORD  Flags,
       LPARAM lParam
);

Paramètres

[in] pPrinterName

Pointeur fourni par l’appelant vers une chaîne de nom d’imprimante terminée par NULL. Le format de chaîne peut être \Machine\PrinterName pour spécifier une imprimante distante ou PrinterName pour spécifier une imprimante locale.

DriverEvent

Code d’événement fourni par l’appelant identifiant l’événement. Les codes d’événement suivants sont définis :

Code de l’événement	Définition
PRINTER_EVENT_ADD_CONNECTION	Le spouleur vient de terminer le traitement d’un appel à sa fonction AddPrinterConnection , qui permet à un utilisateur client de se connecter à une imprimante distante créée précédemment.
PRINTER_EVENT_ATTRIBUTES_CHANGED	Les bits d’attribut d’une imprimante ont été modifiés. En réponse à l’appel d’une application à la fonction SetPrinter , le spouleur appelle la fonction DrvPrinterEvent du pilote d’imprimante, en passant le code d’événement dans l’appel. Lorsque ce code d’événement est utilisé, le paramètre lParam pointe vers une structure PRINTER_EVENT_ATTRIBUTES_INFO qui décrit l’ancien et le nouveau attributs.
PRINTER_EVENT_CACHE_DELETE	Le spouleur supprime le cache de fichiers du client.
PRINTER_EVENT_CACHE_REFRESH	Le spouleur met à jour les fichiers mis en cache du client.
PRINTER_EVENT_CONFIGURATION_CHANGE	Réservé.
PRINTER_EVENT_CONFIGURATION_UPDATE	La configuration de l’imprimante a changé. Lorsque ce code d’événement est utilisé, le paramètre lParam pointe vers une chaîne Unicode qui contient une notification mise en forme selon le schéma de notification Bidi.
PRINTER_EVENT_DELETE_CONNECTION	Le spouleur vient de terminer le traitement d’un appel à sa fonction DeletePrinterConnection , qui permet à un utilisateur client de supprimer une connexion d’imprimante.
PRINTER_EVENT_DELETE	Le spouleur vient de terminer le traitement d’un appel à sa fonction DeletePrinter, ce qui permet à un administrateur de supprimer une imprimante instance.
PRINTER_EVENT_INITIALIZE	Le spouleur vient de terminer le traitement d’un appel à sa fonction AddPrinter , qui permet à un administrateur de rendre une imprimante disponible sur un serveur, ou de sa fonction SetPrinter , qui permet à un administrateur de modifier l’état d’une imprimante. Dans une connexion de rendu côté client, l’ordinateur client vient d’ajouter l’imprimante GUID. L’événement PRINTER_EVENT_INITIALIZE spécifie une valeur de paramètre NULL lParam pour les appels DrvPrinterEvent sur Windows Vista et les versions antérieures. Pour Windows 7 et versions ultérieures, le paramètre lParam est un handle de jeton utilisateur. Les pilotes d’impression peuvent utiliser le handle de jeton retourné pour interroger les données utilisateur ou emprunter l’identité de l’utilisateur.

Flags

Indicateur de bits fourni par l’appelant, défini comme suit :

Valeur

Définition

PRINTER_EVENT_FLAG_NO_UI

Si elle est définie, la fonction ne doit pas afficher d’interface utilisateur. Pendant l’installation d’un processeur d’impression, d’un moniteur d’impression ou d’un pilote d’imprimante, la seule façon dont une interface utilisateur est autorisée est l’utilisation de la directive VendorSetup . Pour plus d’informations, consultez Entrées de fichier INFd’imprimante et Opérations de configuration d’imprimante personnalisées .

Attention

La directive VendorSetup est déconseillée et ne doit pas être utilisée par les nouveaux pilotes v3 ou v4 que vous développez. Ces informations sur VendorSetup sont fournies à titre de référence uniquement ou pour la maintenance des pilotes v3 existants qui utilisent déjà cette directive INF.

lParam

Non utilisé, sauf si le paramètre DriverEvent est défini sur PRINTER_EVENT_ATTRIBUTES_CHANGED. Dans ce cas, lParam contient l’adresse d’une structure PRINTER_EVENT_ATTRIBUTES_INFO. (Voir la description précédente du paramètre DriverEvent .) Pour toutes les autres valeurs du paramètre DriverEvent , le paramètre lParam est NULL.

Valeur retournée

Si l’opération réussit, la fonction doit retourner TRUE ; dans le cas contraire, elle doit retourner FALSE. Actuellement, toutefois, la seule fois où la valeur de retour de la fonction est vérifiée est lorsque le spouleur a appelé DrvPrinterEvent pendant le traitement de la fonction AddPrinter , avec DriverEvent défini sur PRINTER_EVENT_INITIALIZE. Si DrvPrinterEvent retourne FALSE dans ce cas, le spouleur ne crée pas l’imprimante et provoque à la place l’échec de AddPrinter .

Remarques

Toutes les DLL d’interface d’imprimante doivent fournir une fonction DrvPrinterEvent , et la fonction doit prendre en charge le code d’événement PRINTER_EVENT_INITIALIZE. La prise en charge de tous les autres codes d’événement est facultative.

Les paramètres du Registre stockés lors de la gestion d’un événement PRINTER_EVENT_INITIALIZE doivent être stockés sous la clé HKEY_LOCAL_MACHINE en appelant SetPrinterData. Pour les codes d’événement PRINTER_EVENT_INITIALIZE et PRINTER_EVENT_DELETE, le spouleur vérifie que l’appelant dispose de privilèges d’administration et appelle DrvPrinterEvent lors de l’emprunt d’identité de l’appelant.

En revanche, si vous devez stocker des paramètres dans le Registre lors de la gestion d’un événement PRINTER_EVENT_ADD_CONNECTION, la DLL de l’interface d’imprimante doit les écrire sous la clé HKEY_CURRENT_USER afin qu’ils soient stockés par utilisateur. Ensuite, si un utilisateur avec un profil itinérant se connecte à un autre système, la connexion suit l’utilisateur. La fonction DrvPrinterEvent est appelée uniquement lorsque l’utilisateur établit la connexion pour la première fois, et non lorsque l’utilisateur se connecte ensuite à d’autres systèmes à l’aide du profil itinérant.

Pour les codes d’événement PRINTER_EVENT_ADD_CONNECTION et PRINTER_EVENT_DELETE_CONNECTION, le contexte d’exécution de la fonction DrvPrinterEvent est l’application appelante (généralement le dossier d’impression), et la fonction peut afficher une interface utilisateur. Pour tous les autres codes d’événement, le contexte d’exécution est le spouleur d’impression et une interface utilisateur ne peut pas être affichée.

Un pilote FAX peut, par exemple, afficher une interface utilisateur lorsqu’une connexion est établie, qui peut inviter l’utilisateur à entrer le nom et le numéro de téléphone de l’utilisateur (expéditeur fax) et enregistrer les informations jusqu’à ce que la connexion soit supprimée.

Un exemple du type de fichier qui peut être stocké dans un cache client est un fichier de métriques de police volumineux qui contient trop d’informations pour être écrites dans le Registre. Lorsque le code d’événement de la fonction DrvPrinterEvent est PRINTER_EVENT_CACHE_REFRESH, la DLL de l’interface d’imprimante peut recharger le fichier à partir du serveur pour vérifier que le cache est à jour.

Configuration requise

Condition requise	Valeur
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	winddiui.h (incluez Winddiui.h)