Fonction DocumentEvent

  • Article

La fonction DocumentEvent est un gestionnaire d’événements pour les événements associés à l’impression d’un document.

Syntaxe

HRESULT DocumentEvent(
  _In_  HANDLE hPrinter,
  _In_  HDC    hdc,
        INT    iEsc,
        ULONG  cbIn,
  _In_  PVOID  pvIn,
        ULONG  cbOut,
  _Out_ PVOID  pvOut
);

Paramètres

hPrinter [in]

Un handle vers un objet imprimante. Utilisez la fonction OpenPrinter ou AddPrinter pour récupérer un handle d’imprimante.

hdc [in]

Un handle de contexte de périphérique généré par un appel de CreateDC. Il s’agit de zéro 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 « Remarques ».

iEsc

Un code d’échappement qui identifie l’événement à gérer. Ce paramètre peut être l’une des constantes entières suivantes.

Constant Événement
DOCUMENTEVENT_ABORTDOC
 GDI traite 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 existe un appel précédent à DocumentEvent avec iEsc défini sur DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE
 GDI traite un appel à sa fonction CreateDC ou 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 XXXDOCUMENTEVENT_ auxquels le pilote répond. Cet événement est émis juste avant un appel à DocumentEvent 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 à DocumentEvent 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.

Rcib

La taille, en octets, de la mémoire tampon pointée par pvIn.

pvIn [in]

Pointeur vers une mémoire tampon. Ce que contient la mémoire tampon dépend de la valeur d’iEsc, comme indiqué dans le tableau suivant.

Constant Contenus pvin
DOCUMENTEVENT_ABORTDOC
 Aucun affichage.
DOCUMENTEVENT_CREATEDCPOST
 L’élément pvIn contient l’adresse d’un pointeur vers la structure DEVMODE spé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
 L’élément pvIn pointe vers une structure DOCEVENT_CREATEDCPRE qui est documentée dans le Kit de développement de pilotes Windows.
DOCUMENTEVENT_DELETEDC
 Aucun affichage.
DOCUMENTEVENT_ENDDOCPOST
 Aucun affichage.
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC
 Aucun affichage.
DOCUMENTEVENT_ENDPAGE
 Aucun affichage.
DOCUMENTEVENT_ESCAPE
 L’élément pvIn pointe vers une structure DOCEVENT_ESCAPE qui est documentée dans le Kit de développement de pilotes Windows.
DOCUMENTEVENT_QUERYFILTER
 Identique à DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST
 L’élément pvIn contient l’adresse d’un pointeur vers la structure DEVMODE spé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
 L’élément pvIn contient l’adresse d’un pointeur vers la structure DEVMODE fournie par l’appelant de ResetDC.
DOCUMENTEVENT_STARTDOCPOST
 L’élément pvIn pointe vers un TYPE LONG qui spécifie l’identificateur de travail d’impression retourné par StartDoc.
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC
 L’élément pvIn contient l’adresse d’un pointeur vers une structure DOCINFO fournie par l’appelant de StartDoc.
DOCUMENTEVENT_STARTPAGE
 Aucun affichage.

cbOut

Valeur Signification
IDOCUMENTEVENT_QUERYFILTER La taille, en octets, du pointeur de la mémoire tampon vers le pvOut.
DOCUMENTEVENT_ESCAPE Valeur utilisée comme paramètre cbOutput pour ExtEscape.
Pour toutes les autres valeurs iEsc n’est pas utilisé.

pvOut [out]

Pointeur vers une mémoire tampon. Le contenu de la mémoire tampon dépend de la valeur fournie pour iEsc, comme indiqué dans le tableau suivant.

Constant Contenus pvOut
DOCUMENTEVENT_CREATEDCPRE
 Un pointeur vers une structure DEVMODE 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
 Un pointeur vers une mémoire tampon utilisée comme paramètre lpszOutData pour ExtEscape.
DOCUMENTEVENT_QUERYFILTER
 Un pointeur vers la mémoire tampon contenant une structure DOCEVENT_FILTER qui est documentée dans le Kit de développement de pilotes Windows.
DOCUMENTEVENT_RESETDCPRE
 Pointeur vers une structure DEVMODE fournie par le pilote, que GDI utilise au lieu de celle fournie par l’appelant ResetDC. (Si NULL, GDI utilise la structure fournie par l’appelant.)

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 ci-dessous). Si la fonction fournit une valeur de retour, elle doit être l’une des suivantes.

Valeur de retour Signification
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.

La liste suivante indique les codes d’échappement qui nécessitent une valeur de retour et non, et explique la signification des codes de retour DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE et DOCUMENTEVENT_UNSUPPORTED.

Valeur de retour Signification
DOCUMENTEVENT_ABORTDOC La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_CREATEDCPOST La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_CREATEDCPRE DOCUMENTEVENT_FAILURE : GDI ne crée pas le contexte d’appareil ou le contexte d’informations et fournit une valeur de retour de 0 pour CreateDCou CreateIC.
DOCUMENTEVENT_DELETEDC La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_ENDDOCPOST La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_ENDPAGE La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_ESCAPE La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_QUERYFILTER Consultez la section Notes.
DOCUMENTEVENT_RESETDCPOST La valeur de retour n’est pas utilisée et ne doit pas être lue.
DOCUMENTEVENT_RESETDCPRE DOCUMENTEVENT_FAILURE : GDI ne réinitialise pas le contexte de l’appareil et fournit une valeur de retour de 0 pour ResetDC.
DOCUMENTEVENT_STARTDOCPOST DOCUMENTEVENT_FAILURE : GDI appelle AbortDoc pour arrêter le document, puis fournit une valeur de retour de SP_ERROR pour StartDoc.
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC DOCUMENTEVENT_FAILURE ; GDI ne démarre pas le document et fournit une valeur de retour de SP_ERROR pour StartDoc.
DOCUMENTEVENT_STARTPAGE DOCUMENTEVENT_FAILURE : GDI ne démarre pas la page et fournit une valeur de retour de SP_ERROR pour StartPage.

Notes

Pour une valeur iEsc de DOCUMENTEVENT_QUERYFILTER, le spouleur peut interpréter une valeur DOCUMENTEVENT_SUCCESS retournée par DocumentEvent de deux façons, selon que le pilote a modifié certains membres de la structure DOCEVENT_FILTER (qui est documentée dans le Kit de développement de pilotes Windows). (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 DocumentEvent retourné, le spouleur détermine si les valeurs de ces membres ont changé et utilise ces informations pour interpréter la valeur de retour DocumentEvent . Le tableau suivant récapitule cette situation.

Valeur de retour État de cElementsReturned et 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 du pilote. Il persiste donc à appeler DocumentEvent pour tous les événements.
DOCUMENTEVENT_SUCCESS
 Pilote a écrit à un ou aux deux membres.
 Le spouleur accepte cette valeur de retour sans interprétation. Si le pilote n’a écrit qu’une seule des valeurs cElementsNeeded 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 (qui est documenté dans le Kit de développement de pilotes Windows).
DOCUMENTEVENT_UNSUPPORTED
 Non applicable
 Le pilote ne prend pas en charge DOCUMENTEVENT_QUERYFILTER.
Le spouleur ne parvient pas à récupérer le filtre d’événements du pilote. Il persiste donc à appeler DocumentEvent pour tous les événements.
DOCUMENTEVENT_FAILURE
 Non applicable
 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 du pilote. Il persiste donc à appeler DocumentEvent pour tous les événements.

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 documentation relative à la structure DOCEVENT_CREATEDCPRE dans la Kit de développement de pilotes Windows).
  • Si le travail est en cours depool, pvIn->pszDevice pointe vers le nom du port d’imprimante.

Remarque

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 DocumentEvent doit appeler est ExtEscape, et seules les échappements privés doivent être utilisés. Les appels DocumentEvent à d’autres fonctions GDI peuvent produire un comportement non défini.

Spécifications

Condition requise Value
Client minimal pris en charge
 Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge
 Windows Server 2008 [applications de bureau uniquement]
En-tête
Winspool.h (y compris Windows.h)
Noms Unicode et ANSI
 DocumentEventW (Unicode) et DocumentEventA (ANSI)

Voir aussi