IPrintOemUI2 ::D ocumentEvent, méthode (prcomoem.h)
La méthode IPrintOemUI2::DocumentEvent permet à un plug-in d’interface utilisateur de remplacer l’implémentation par défaut du module d’interface utilisateur du pilote principal du DrvDocumentEvent DDI.
Syntaxe
HRESULT DocumentEvent(
HANDLE hPrinter,
HDC hdc,
INT iEsc,
ULONG cbIn,
PVOID pvIn,
ULONG cbOut,
PVOID pvOut,
PINT piResult
);
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 appel CreateDC. Il s’agit de zéro si iEsc est DOCUMENTEVENT_CREATEDCPRE.
iEsc
Code d’échappement fourni par l’appelant identifiant l’événement à gérer. Ce paramètre peut être l’une des constantes entières suivantes :
| Code d’échappement | Signification |
|---|---|
| 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 à DrvDocumentEvent avec 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 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 de 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.
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 structure DEVMODEW 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 | 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 de DOCEVENT_ESCAPE. |
| DOCUMENTEVENT_QUERYFILTER | Identique à DOCUMENTEVENT_CREATEDCPRE. |
| DOCUMENTEVENT_RESETDCPOST | pvIn contient l’adresse d’un pointeur vers la structure DEVMODEW 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 | pvIn contient l’adresse d’un pointeur vers une structure DEVMODEW fournie par l’appelant de ResetDC (décrit dans la documentation du Kit de développement logiciel (SDK) Microsoft Windows). |
| DOCUMENTEVENT_STARTDOCPOST | pvIn pointe vers un TYPE LONG qui spécifie l’identificateur de travail d’impression retourné par StartDoc (décrit dans la documentation du Kit de développement logiciel (SDK) Windows). |
|
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC |
pvIn contient l’adresse d’un pointeur vers une structure DOCINFO fournie par l’appelant de StartDoc (les deux décrites dans la documentation du Kit de développement logiciel (SDK) Windows). |
| DOCUMENTEVENT_STARTPAGE | Non utilisé. |
cbOut
Si iEsc est DOCUMENTEVENT_ESCAPE :
Valeur fournie par la fonction utilisée comme paramètre cbOutput pour 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é.
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. CreateDC, extEscapeet ResetDC sont décrits dans la documentation du Kit de développement logiciel (SDK) Windows.
| 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 extEscape. |
| DOCUMENTEVENT_QUERYFILTER | Pointeur fourni par l’appelant vers 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 ResetDC. (Si NULL, GDI utilise la structure fournie par l’appelant.) |
| Toutes les autres valeurs iEsc | Non utilisé. |
piResult
Pointeur vers un emplacement de mémoire qui reçoit l’une des valeurs suivantes :
| Valeur de retour | Définition |
|---|---|
| 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. Consultez également la section Remarques pour plus d’informations. |
| DOCUMENTEVENT_UNSUPPORTED | Le pilote ne prend pas en charge le code d’échappement identifié par iEsc . |
Valeur de retour
Cette méthode doit retourner l’une des valeurs suivantes. Pour plus d’informations, consultez la section Remarques.
| Retourner le code | Description |
|---|---|
|
Le plug-in d’interface utilisateur implémente cette méthode. |
|
Le plug-in d’interface utilisateur n’implémente pas cette méthode. |
Remarques
La méthode IPrintOemUI2::DocumentEvent d’un plug-in d’interface utilisateur effectue les mêmes types d’opérations que le DRVDocumentEvent DDI exporté par des DLL d’interface d’imprimante en mode utilisateur. Pour plus d’informations sur les événements de document et leur traitement, consultez la description de la DrvDocumentEvent DDI.
Si vous fournissez un plug-in d’interface utilisateur, le DrvDocumentEvent DDI du pilote d’imprimante appelle la méthode IPrintOemUI2::DocumentEvent. DrvDocumentEvent DDI effectue son propre traitement pour l’événement spécifié, puis appelle la méthode IPrintOemUI2::DocumentEvent pour gérer un traitement supplémentaire de l’événement.
Lorsque cette méthode est appelée avec une valeur du paramètre iEsc de DOCUMENTEVENT_QUERYFILTER et retourne avec *piResult == DOCUMENTEVENT_SUCCESS, le spouleur peut interpréter cette valeur de deux façons, selon que certains membres de la structure DOCEVENT_FILTER ont changé de valeurs. Pour plus d’informations, consultez la section Notes pour DrvDocumentEvent.
Lorsque l’événement DOCUMENTEVENT_QUERYFILTER est déclenché, le pilote principal appelle les plug-ins dans l’ordre dans lequel ils ont été installés, jusqu’à ce qu’un d’eux retourne S_OK, ou jusqu’à ce que tous les plug-ins aient été appelés et qu’aucun d’entre eux n’ait retourné S_OK. De cette façon, au plus un plug-in est autorisé à gérer l’événement DOCUMENTEVENT_QUERYFILTER, et le filtre qu’il spécifie est appliqué à tous les plug-ins de la chaîne de plug-ins.
Pour un enregistreur de plug-in qui implémente l’interface IPrintOemUI2, mais n’a pas besoin de prendre en charge la méthode IPrintOemUI2::DocumentEvent, cette méthode doit retourner E_NOTIMPL pour toutes les valeurs de iEsc. Si vous devez implémenter cette méthode, elle doit retourner S_OK pour toutes les valeurs de iEsc. Cela signale au pilote principal que cette méthode a géré l’événement approprié. Le pilote principal utilise la valeur que cette méthode place dans piResult comme valeur de retour pour la DrvDocumentEvent DDI.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Bureau |
| d’en-tête | prcomoem.h (include Prcomoem.h) |