Fonction DrvDocumentEvent (winddiui.h)

  • Article

La fonction DrvDocumentEvent d’une DLL d’imprimante peut gérer certains événements associés à l’impression d’un document.

Syntaxe

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

Paramètres

hPrinter

Handle d’imprimante fourni par l’appelant.

hdc

Handle de contexte d’appareil fourni par l’appelant, généré par un CreateDC Cette valeur est nulle si iEsc est défini sur DOCUMENTEVENT_CREATEDCPRE. Pour connaître les restrictions d’impression à partir d’une application 32 bits sur une version 64 bits de Windows, consultez la section Remarques ci-dessous.

iEsc

Code d’échappement fourni par l’appelant identifiant l’événement à gérer.

Pour connaître les restrictions d’impression à partir d’une application 32 bits sur une version 64 bits de Windows, consultez la section Remarques ci-dessous.

Ce paramètre peut être l’une des constantes entières suivantes :

Constante iEsc Événement
DOCUMENTEVENT_ABORTDOC GDI est sur le point de traiter un appel à sa fonction AbortDoc .
DOCUMENTEVENT_CREATEDCPOST GDI vient de traiter un appel à sa fonction CreateDC ou CreateIC . Ce code d’échappement ne doit pas être utilisé, sauf s’il y a eu un appel précédent à DrvDocumentEvent avec iEsc défini sur DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE GDI est sur le point de traiter un appel à sa fonction CreateDC ou CreateIC .
DOCUMENTEVENT_DELETEDC GDI est sur le point de traiter un appel à sa fonction DeleteDC .
DOCUMENTEVENT_ENDDOCPOST GDI vient de traiter un appel à sa fonction EndDoc .
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC GDI est sur le point de traiter un appel à sa fonction EndDoc .
DOCUMENTEVENT_ENDPAGE GDI est sur le point de traiter un appel à sa fonction EndPage .
DOCUMENTEVENT_ESCAPE GDI est sur le point de traiter un appel à sa fonction ExtEscape .
DOCUMENTEVENT_QUERYFILTER L’événement DOCUMENTEVENT_QUERYFILTER représente une opportunité pour le spouleur d’interroger le pilote pour obtenir la liste des événements DOCUMENTEVENT_XXX auxquels le pilote répondra. Cet événement est émis juste avant un appel à DrvDocumentEvent qui passe l’événement DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST GDI vient de traiter un appel à sa fonction ResetDC . Ce code d’échappement ne doit pas être utilisé, sauf s’il y a eu un appel précédent à DrvDocumentEvent avec iEsc défini sur DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE GDI est sur le point de traiter un appel à sa fonction ResetDC .
DOCUMENTEVENT_STARTDOCPOST GDI vient de traiter un appel à sa fonction StartDoc .
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC GDI est sur le point de traiter un appel à sa fonction StartDoc .
DOCUMENTEVENT_STARTPAGE GDI est sur le point de traiter un appel à sa fonction StartPage .

cbIn

Taille fournie par l’appelant, en octets, de la mémoire tampon pointée par pvIn.

[in] pvIn

Pointeur fourni par l’appelant, dont l’utilisation dépend de la valeur fournie pour iEsc, comme suit :

Constante iEsc Contenu de pvIn
DOCUMENTEVENT_ABORTDOC Non utilisé.
DOCUMENTEVENT_CREATEDCPOST pvIn contient l’adresse d’un pointeur vers la structure DEVMODEW spécifiée dans le paramètre pvOut d’un appel précédent à cette fonction, pour laquelle le paramètre iEsc a été défini sur DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE pvIn pointe vers une structure DOCEVENT_CREATEDCPRE .
DOCUMENTEVENT_DELETEDC Non utilisé.
DOCUMENTEVENT_ENDDOCPOST Non utilisé.
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC Non utilisé.
DOCUMENTEVENT_ENDPAGE Non utilisé.
DOCUMENTEVENT_ESCAPE pvIn pointe vers une structure DOCEVENT_ESCAPE .
DOCUMENTEVENT_QUERYFILTER Identique à pour DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST pvIn contient l’adresse d’un pointeur vers la structure DEVMODEW spécifiée dans le paramètre pvOut d’un appel précédent à cette fonction, pour lequel le paramètre iEsc a été défini sur DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE pvIn contient l’adresse d’un pointeur vers la structure DEVMODEW fournie par l’appelant de la fonction ResetDC .
DOCUMENTEVENT_STARTDOCPOST pvIn pointe vers un LONG qui spécifie l’identificateur de travail d’impression retourné par la fonction StartDoc .
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC pvIn contient l’adresse d’un pointeur vers une structure DOCINFO fournie par l’appelant de la fonction StartDoc .
DOCUMENTEVENT_STARTPAGE Non utilisé.

cbOut

Si iEsc est DOCUMENTEVENT_ESCAPE

Valeur fournie par la fonction utilisée comme paramètre cbOutput pour la fonction ExtEscape .

Si iEsc est DOCUMENTEVENT_QUERYFILTER

Taille fournie par l’appelant, en octets, du pointeur de la mémoire tampon vers par pvOut.

Pour toutes les autres valeurs iEsc

Non utilisé.

[out] pvOut

Pointeur fourni par une fonction vers une mémoire tampon de sortie, dont l’utilisation dépend de la valeur fournie pour iEsc, comme suit :

Constante iEsc contenu pvOut
DOCUMENTEVENT_CREATEDCPRE Pointeur vers une structure DEVMODEW fournie par le pilote, que GDI utilise au lieu de celle fournie par l’appelant CreateDC . (Si la valeur est NULL, GDI utilise la structure fournie par l’appelant.)
DOCUMENTEVENT_ESCAPE Pointeur de mémoire tampon utilisé comme paramètre lpszOutData pour la fonction ExtEscape .
DOCUMENTEVENT_QUERYFILTER Pointeur vers la mémoire tampon fournie par l’appelant contenant une structure DOCEVENT_FILTER .
DOCUMENTEVENT_RESETDCPRE Pointeur vers une structure DEVMODEW fournie par le pilote, que GDI utilise au lieu de celle fournie par l’appelant de fonction ResetDC . (Si la valeur est NULL, GDI utilise la structure fournie par l’appelant.)
Toutes les autres valeurs iEsc Non utilisé.

Valeur retournée

La valeur de retour de la fonction dépend de l’échappement fourni pour iEsc. Pour certains codes d’échappement, la valeur de retour n’est pas utilisée (voir la deuxième liste de valeurs). Si la fonction fournit une valeur de retour, elle doit être l’une des suivantes :

Code de retour Description
DOCUMENTEVENT_FAILURE Le pilote prend en charge le code d’échappement identifié par iEsc, mais une défaillance s’est produite.
DOCUMENTEVENT_SUCCESS Le pilote a correctement géré le code d’échappement identifié par iEsc.
DOCUMENTEVENT_UNSUPPORTED Le pilote ne prend pas en charge le code d’échappement identifié par iEsc.

Remarques

Une DLL d’interface d’imprimante peut éventuellement fournir une fonction DrvDocumentEvent pour effectuer le prétraitement ou le post-traitement des appels GDI associés au rendu d’un document. Les appels à la fonction DrvDocumentEvent sont effectués à partir du client GDI en mode utilisateur, lorsqu’une application effectue des appels dans le client GDI.

Pour une valeur iEsc de DOCUMENTEVENT_QUERYFILTER, le spouleur peut interpréter une valeur de DOCUMENTEVENT_SUCCESS retournée par DrvDocumentEvent de deux manières, selon que le pilote a ou non modifié certains membres de la structure DOCEVENT_FILTER . (Le paramètre pvOut pointe vers cette structure.) Lorsque le spouleur alloue de la mémoire pour une structure de ce type, il initialise deux membres de cette structure, cElementsReturned et cElementsNeeded, aux valeurs connues. Après le retour de DrvDocumentEvent , le spouleur détermine si les valeurs de ces membres ont changé et utilise ces informations pour interpréter la valeur de retour DrvDocumentEvent . Le tableau suivant récapitule cette situation.

Valeur retournée État de cElementsReturned, cElementsNeeded Signification
DOCUMENTEVENT_SUCCESS Le pilote n’a apporté aucune modification à l’un ou l’autre des membres. Le spouleur interprète cette valeur de retour comme équivalente à DOCUMENTEVENT_UNSUPPORTED. Le spouleur ne pouvant pas récupérer le filtre d’événements à partir du pilote, il persiste à appeler DrvDocumentEvent pour tous les événements.
DOCUMENTEVENT_SUCCESS Le pilote a écrit à l’un ou aux deux membres. Le spouleur accepte cette valeur de retour sans interprétation. Si le pilote a écrit à un seul de cElementsNeededed etcElementsReturned, le spouleur considère que le membre inchangé a une valeur zéro. Le spouleur filtre tous les événements répertoriés dans le membre aDocEventCall de DOCEVENT_FILTER.
DOCUMENTEVENT_UNSUPPORTED Non applicable Le pilote ne prend pas en charge DOCUMENTEVENT_QUERYFILTER. Le spouleur ne pouvant pas récupérer le filtre d’événements à partir du pilote, il persiste à appeler DrvDocumentEvent pour tous les événements.
DOCUMENTEVENT_FAILURE Non applicable Le pilote prend en charge DOCUMENTEVENT_QUERYFILTER, mais il a rencontré une erreur interne. Le spouleur ne pouvant pas récupérer le filtre d’événements à partir du pilote, il persiste à appeler DrvDocumentEvent pour tous les événements.

Si le nom de code d’échappement n’a pas de suffixe ou est suffixe avec PRE, le client GDI appelle DrvDocumentEvent juste avant d’appeler le moteur de rendu GDI en mode noyau. Si le nom de code d’échappement est suffixe par POST, le client GDI appelle DrvDocumentEvent juste après le retour du moteur de rendu GDI en mode noyau.

Si le code d’échappement fourni dans le paramètre iEsc est DOCUMENTEVENT_CREATEDCPRE, les règles suivantes s’appliquent :

  • Si le travail est envoyé directement à l’imprimante sans mise en file d’attente, pvIn --> pszDevice pointe vers le nom de l’imprimante. (Pour plus d’informations, consultez la structure DOCEVENT_CREATEDCPRE .)

  • Si le travail est en cours de mise en file d’attente, pvIn --> pszDevice pointe vers le nom du port d’imprimante.

La fonction DrvDocumentEvent s’exécute dans le contexte de l’appelant en mode utilisateur de la fonction cliente GDI. Lorsque le spoulage EMF est désactivé, la fonction peut afficher une interface utilisateur. Par exemple, la fonction DrvDocumentEvent pour un pilote FAX peut afficher une boîte de dialogue pour l’utilisateur avant le traitement de la fonction StartDoc de GDI.

Les restrictions suivantes s’appliquent lors de l’exécution d’une application 32 bits sur une version 64 bits de Windows :

  • La seule fonction GDI que DrvDocumentEvent doit appeler est ExtEscape, et seules les échappements privés doivent être utilisés.

  • Les appels DrvDocumentEvent à d’autres fonctions GDI peuvent produire un comportement non défini.

Configuration requise

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

Voir aussi

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER