DrvDocumentEvent, fonction (winddiui.h)
La fonction DrvDocumentEvent d’une interface 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 Il s’agit de zéro si est défini sur DOCUMENTEVENT_CREATEDCPRE. Pour plus d’informations sur l’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 plus d’informations sur l’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 traite un appel à sa fonction AbortDoc. |
| DOCUMENTEVENT_CREATEDCPOST | GDI vient de traiter un appel à son CreateDC ou fonction CreateIC. Ce code d’échappement ne doit pas être utilisé, sauf s’il existe un appel précédent à DrvDocumentEvent avec défini sur DOCUMENTEVENT_CREATEDCPRE. |
| DOCUMENTEVENT_CREATEDCPRE | GDI traite un appel à son CreateDC ou fonction CreateIC. |
| DOCUMENTEVENT_DELETEDC | GDI traite un appel à sa fonction DeleteDC. |
| DOCUMENTEVENT_ENDDOCPOST | GDI vient de traiter un appel à sa fonction EndDoc. |
| DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC | GDI traite un appel à sa fonction EndDoc. |
| DOCUMENTEVENT_ENDPAGE | GDI traite un appel à sa fonction EndPage. |
| DOCUMENTEVENT_ESCAPE | GDI traite un appel à sa fonction ExtEscape. |
| DOCUMENTEVENT_QUERYFILTER | L’événement DOCUMENTEVENT_QUERYFILTER représente une opportunité pour que le spouleur interroge le pilote pour obtenir la liste des événements DOCUMENTEVENT_XXX auxquels le pilote répond. Cet événement est émis juste avant un appel à DrvDocumentEvent qui transmet 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 existe un appel précédent à DrvDocumentEvent avec iEsc défini sur DOCUMENTEVENT_RESETDCPRE. |
| DOCUMENTEVENT_RESETDCPRE | GDI traite un appel à sa fonction ResetDC. |
| DOCUMENTEVENT_STARTDOCPOST | GDI vient de traiter un appel à sa fonction StartDoc. |
| DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC | GDI traite un appel à sa fonction StartDoc. |
| DOCUMENTEVENT_STARTPAGE | GDI traite 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 pvIn |
|---|---|
| DOCUMENTEVENT_ABORTDOC | Non utilisé. |
| DOCUMENTEVENT_CREATEDCPOST | pvIn contient l’adresse d’un pointeur vers la structureDEVMODEWspécifiée dans le paramètre pvOut dans 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 de 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 de DOCEVENT_ESCAPE. |
| DOCUMENTEVENT_QUERYFILTER | Identique à DOCUMENTEVENT_CREATEDCPRE. |
| DOCUMENTEVENT_RESETDCPOST | pvIn contient l’adresse d’un pointeur vers la structureDEVMODEWspécifiée dans le paramètre pvOut dans un appel précédent à cette fonction, pour laquelle le paramètre iEsc a été défini sur DOCUMENTEVENT_RESETDCPRE. |
| DOCUMENTEVENT_RESETDCPRE | pvIn contient l’adresse d’un pointeur vers la structureDEVMODEWfournie par l’appelant de la fonctionResetDC. |
| DOCUMENTEVENT_STARTDOCPOST | pvIn pointe vers un type 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 pvOut.
Pour toutes les autres valeurs iEsc
Non utilisé.
[out] pvOut
Pointeur fourni par la 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 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 fourni par l’appelant pour la mémoire tampon 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 NULL, GDI utilise la structure fournie par l’appelant.) |
| Toutes les autres valeurs iEsc | Non utilisé. |
Valeur de retour
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 :
| Retourner le code | 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 réussi à gérer 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 un prétraitement ou une 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 au client GDI.
Pour une valeur iEsc de DOCUMENTEVENT_QUERYFILTER, le spouleur peut interpréter une valeur DOCUMENTEVENT_SUCCESS retournée par DrvDocumentEvent de deux façons, selon que le pilote a 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. Une fois DrvDocumentEvent retourné, 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 de retour | État de cElementsReturned, cElementsNeeded | Signification |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | Le pilote n’a apporté aucune modification à l’un ou l’autre membre. | Le spouleur interprète cette valeur de retour comme équivalente à DOCUMENTEVENT_UNSUPPORTED. Le spouleur ne parvient pas à récupérer le filtre d’événements à partir du pilote. Il persiste donc à appeler DrvDocumentEvent pour tous les événements. |
| DOCUMENTEVENT_SUCCESS | Pilote a écrit à un ou les deux membres. | Le spouleur accepte cette valeur de retour sans interprétation. Si le pilote n’a écrit qu’une seule cElementsNeed et cElementsReturned, le spouleur considère que le membre inchangé a la valeur zéro. Le spouleur filtre tous les événements répertoriés dans le membre aDocEventCall de DOCEVENT_FILTER. |
| DOCUMENTEVENT_UNSUPPORTED | Sans objet | Le pilote ne prend pas en charge DOCUMENTEVENT_QUERYFILTER. Le spouleur ne parvient pas à récupérer le filtre d’événements à partir du pilote. Il persiste donc à appeler DrvDocumentEvent pour tous les événements. |
| DOCUMENTEVENT_FAILURE | Sans objet | Le pilote prend en charge DOCUMENTEVENT_QUERYFILTER, mais a rencontré une erreur interne. Le spouleur ne parvient pas à récupérer le filtre d’événements à partir du pilote. Il persiste donc à appeler DrvDocumentEvent pour tous les événements. |
Si le nom du 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 du code d’échappement est suffixe avec 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 spooling, pvIn --> pszDevice pointe vers le nom de l’imprimante. (Pour plus d’informations, consultez la structure DOCEVENT_CREATEDCPRE.)
Si le travail est en cours depool, 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 à 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 qui DrvDocumentEvent doit appeler est extEscape, et seules les échappements privés doivent être utilisés.
DrvDocumentEvent appels à d’autres fonctions GDI peuvent produire un comportement non défini.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Bureau |
| d’en-tête | winddiui.h (include Winddiui.h) |