Événements du document du pilote XPS

Article
10/16/2024

Important

La plateforme d’impression moderne est le moyen privilégié de Windows pour communiquer avec les imprimantes. Nous vous recommandons d’utiliser le pilote de classe IPP en boîte de Microsoft, ainsi que les applications de support d’impression (PSA), pour personnaliser l’expérience d’impression dans Windows 10 et 11 pour le développement de périphériques d’impression.

Pour plus d’informations, veuillez consulter la section Plateforme d’impression moderne et le Guide de conception des applications de support d’impression.

Le support d'impression de Microsoft Windows Presentation Foundation (WPF) envoie aux pilotes d'impression XPSDrv des événements de notification pendant le spooling des documents, de la même manière que le support d'impression GDI envoie des notifications aux pilotes d'impression GDI. Le support d'impression WPF utilise également la même fonction DDI DrvDocumentEvent que le support d'impression GDI, mais de nouveaux événements ont été définis pour prendre en charge les événements de traitement des documents XPS. Le support d'impression GDI continuera à émettre des gestionnaires d'événements DrvDocumentEvent pour les pilotes d'impression basés sur GDI et les pilotes d'impression XPSDrv pour l'impression d'applications Microsoft Win32.

Présentation du gestionnaire d'événements DrvDocumentEvent

Si nécessaire, les pilotes d'impression XPSDrv peuvent exporter le gestionnaire d'événements DrvDocumentEvent du module de configuration pour intercepter les fonctions de traitement des documents. Les nouveaux événements liés au document XPS sont identifiés par un nom symbolique commençant par « DOCUMENTEVENT_XPS_ ».

Le support d'impression WPF appelle la fonction DrvDocumentEvent du pilote d'impression XPSDrv pendant qu'il met le document en file d'attente pour l'impression. Chaque appel intervient à une étape différente du processus. L'étape de traitement de chaque appel est identifiée par la valeur de l'argument iEsc. Le contenu des tampons référencés par les arguments pvIn et pvOut varie en fonction de l'étape de traitement.

Les sous-sections suivantes de cette rubrique décrivent uniquement les événements de traitement des documents XPS produits par le support d'impression WPF.

Description du gestionnaire d'événements DrvDocumentEvent

Le gestionnaire d'événement DrvDocumentEvent a le format d'appel suivant. Le code et les définitions de paramètres de cette section sont donnés à titre d'information.

INT
  DrvDocumentEvent(
    HANDLE  hPrinter,
    HDC  hdc,
    int  iEsc,
    ULONG  cbIn,
    PVOID  pvIn,
    ULONG  cbOut,
    PVOID  pvOut
    );

Paramètres

hPrinter
La poignée d'imprimante fournie par le support d'impression WPF.

hdc
Un gestionnaire de contexte d'appareil fourni par l'appelant et généré par un appel CreateDC. Ce paramètre est égal à zéro si iEsc a pour valeur DOCUMENTEVENT_CREATEDCPRE.

Lorsqu'un document est imprimé, le système utilise les mêmes valeurs d'événement pour les documents XPS et GDI. Le pilote doit être conscient de cette similitude et déterminer le type de travail en fonction de la dhc. hdc est égal à INVALID_HANDLE_VALUE pour tous les événements DOCUMENTEVENT_XPS_Xxx. Ce contrôle permet de déterminer l'interprétation correcte des valeurs de l'événement DrvDocumentEvent en fonction de l'application appelante. Cette vérification s'applique uniquement aux pilotes d'impression XPSDrv.

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

DOCUMENTEVENT_QUERYFILTER
Le support d'impression WPF envoie cet événement pour demander au pilote d'impression une liste d'événements de traitement de documents XPS auxquels le pilote répondra. Ce problème est émis avant tout autre événement lié au document XPS.

DOCUMENTEVENT_XPS_ADDFEDDOCUMENTSEQUENCEPRE
Le support d'impression WPF envoie cet événement avant d'ajouter FixedDocumentSequence au fichier spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Le support d'impression WPF envoie cet événement après avoir ajouté FixedDocumentSequence au fichier spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
Le support d'impression WPF envoie cet événement avant d'ajouter FixedDocument au fichier spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Le support d'impression WPF envoie cet événement après avoir ajouté FixedDocument au fichier spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF est sur le point d'ajouter un PrintTicket à la FixedDocumentSequence (Job Level).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF doit libérer les données que le pilote renvoie sur l'événement DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE correspondant.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF est sur le point d'ajouter un PrintTicket au FixedDocument (niveau document).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF doit libérer les données que le pilote renvoie sur l'événement DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE correspondant.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF est sur le point d'ajouter un PrintTicket à la page fixe (niveau de la page).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF libère les données que le pilote renvoie sur l'événement DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE correspondant.

DOCUMENTEVENT_XPS_CANCELJOB
Le support d'impression WPF envoie cet événement avant d'appeler une action d'annulation de travail.

DOCUMENTEVENT_XPS_COMMITJOB
WPF a fini d'écrire la date dans le fichier courant.

Rcib
Taille, en octets, du tampon auquel le paramètre pvln fait référence. Cette valeur est fournie par le support d'impression WPF et lue par le gestionnaire de l'événement.

pvIn
Un pointeur fourni par l'appelant. L'utilisation de ce paramètre dépend de la valeur de l'iEsc, comme le décrit la liste suivante. (Pour les événements DOCUMENTEVENT_XPS_Xxx qui ne figurent pas dans cette liste, pvIn n'est pas utilisé).

DOCUMENTEVENT_QUERYFILTER
pvIn pointe vers une structure PDOCEVENT_FILTER (la même que pour DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFEDDOCUMENTSEQUENCEPRE
pvIn pointe vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient trois propriétés :

EscapeCode, qui est une valeur EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode est la valeur de l'événement.
JobIdentifier, qui est une valeur de EPrintPropertyType::kPropertyTypeInt32 (ULONG). Le JobIdentifier est l'ID nécessaire pour appeler GetJob() et SetJob().
JobName, qui est une valeur EPrintPropertyType: : kPropertyTypeString (UNICODE).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Identique à la valeur DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn pointe vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient deux propriétés :

EscapeCode, qui est une valeur EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode est la valeur de l'événement.
DocumentNumber, qui est une valeur de EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Même chose que pour DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn pointe vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient deux propriétés :

EscapeCode, qui est une valeur EPrintPropertyType::kPropertyTypeInt32 (ULONG).
Numéro de page, qui est une valeur de EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
Identique à DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn pointe vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient quatre propriétés :

EscapeCode, qui est un EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode est la valeur de l'événement.
JobIdentifier, qui est une valeur de EPrintPropertyType::kPropertyTypeInt32 (ULONG).
JobName, qui est une valeur EPrintPropertyType: : kPropertyTypeString (UNICODE).
PrintTicket, qui est une valeur EPrintPropertyType: : kPropertyTypeByte.

Vous devez allouer la structure PrintPropertiesCollection et ses propriétés lors de l'événement « PRE » et la libérer lors de l'événement « POST » correspondant. Vous pouvez attribuer la valeur NULL à pvOut pour indiquer que vous soutenez l'événement mais que vous n'êtes pas intéressé par la modification du PrintTicket pour un document ou une page donné(e). Le plug-in ne doit jamais se décharger entre les événements « PRE » et « POST ».

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn est le même pointeur que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

Le pilote doit libérer pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn pointe vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient trois propriétés :

EscapeCode, qui est une valeur EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode est la valeur de l'événement.
DocumentNumber, qui est une valeur de EPrintPropertyType::kPropertyTypeInt32 (ULONG).
PrintTicket, qui est une valeur EPrintPropertyType: : kPropertyTypeByte.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn est le même pointeur que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

Le pilote doit libérer pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn pointe vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient trois propriétés :

EscapeCode, qui est une valeur EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode est la valeur de l'événement.
PageNumber, qui est un EPrintPropertyType::kPropertyTypeInt32 (ULONG).
PrintTicket, qui est un EPrintPropertyType: : kPropertyTypeByte.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn est le même pointeur que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

Le pilote doit libérer pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn est NULL.

cbOut
Si le paramètre iEsc contient DOCUMENTEVENT_QUERYFILTER, le support d'impression WPF fournit la taille du tampon que le paramètre pvOut référence dans le paramètre cbOut. Pour toutes les autres valeurs de iEsc, cbOut n'est pas utilisé.

pvOut
Pointeur vers un tampon fourni par le support d'impression WPF. La taille et le contenu de la mémoire tampon dépendent de la valeur du paramètre iEsc. La liste suivante décrit le contenu de la mémoire tampon pvOut pour chaque valeur iEsc.

DOCUMENTEVENT_QUERYFILTER
Pointeur fourni par l'appelant vers un tampon contenant une structure DOCEVENT_FILTER.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Un pointeur vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient une propriété « PrintTicket » de type EPrintPropertyType::kPropertyTypeBuffer. Cette propriété est toujours présente. Si aucun PrintTicket n'est disponible, la valeur de PrintPropertyValue.propertyBlob.pBuf est NULL.

Cette propriété contient le PrintTicket XML, à partir duquel la Microsoft Windows Presentation Foundation (WPF) utilisera le PrintTicket au lieu de celui fourni par l'appelant de XPSDocumentWriter. (Si pvOut est NULL, si la propriété n'est pas présente ou si les données de la propriété sont NULL, WPF utilise le PrintTicket fourni par l'appelant).

Après le traitement de cet événement, WPF appelle DocumentEvent avec DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST pour que le pilote libère pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Pointeur sur une structure PrintPropertiesCollection (voir Winspool.h) qui contient une propriété « PrintTicket » de type EPrintPropertyType::PropertyTypeBuffer. Cette propriété est toujours présente. Si aucun PrintTicket n'est disponible, la valeur de PrintPropertyValue.propertyBlob.pBuf est NULL.

Cette propriété contient le PrintTicket XML, à partir duquel WPF utilisera le PrintTicket au lieu de celui fourni par l'appelant XPSDocumentWriter. (Si pvOut est NULL, si la propriété n'est pas présente ou si les données de la propriété sont NULL, WPF utilise le PrintTicket fourni par l'appelant).

Après le traitement de cet événement, WPF appelle DocumentEvent avec DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST pour que le pilote libère pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Pointeur sur une structure PrintPropertiesCollection (voir Winspool.h) contenant une propriété « PrintTicket » de type EPrintPropertyType: : PropertyTypeBuffer. Cette propriété est toujours présente. Si aucun PrintTicket n'est disponible, la valeur de PrintPropertyValue.propertyBlob.pBuf est NULL.

Après le traitement de cet événement, WPF appelle DocumentEvent avec DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST pour que le pilote libère pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Valeur retournée

DrvDocumentEvent renvoie l'une des valeurs suivantes :

DOCUMENTEVENT_SUCCESS
Le pilote a traité avec succès le code d'échappement identifié par iEsc.

DOCUMENTEVENT_FAILURE
Le pilote prend en charge le code d'échappement identifié par iEsc, mais une erreur s'est produite.

DOCUMENTEVENT_UNSUPPORTED
Le pilote ne prend pas en charge le code d'échappement identifié par iEsc.

Structures des événements du document XPS et valeurs des codes d'événement

L'exemple de code suivant montre les structures et les constantes utilisées par les nouveaux événements XPS Document.

//
// structures used in XPS Document events
//
 
typedef enum
    {
        kPropertyTypeString = 1,
        kPropertyTypeInt32,
        kPropertyTypeInt64,
        kPropertyTypeByte,
        kPropertyTypeTime,
        kPropertyTypeDevMode,
        kPropertyTypeSD,
        kPropertyTypeNotificationReply,
        kPropertyTypeNotificationOptions,

    } EPrintPropertyType;

    typedef struct
    {
        EPrintPropertyType       ePropertyType;
        union
        {
            BYTE                 propertyByte;
            PWSTR                propertyString;
            LONG                 propertyInt32;
            LONGLONG             propertyInt64;
            struct {
                DWORD  cbBuf;
                LPVOID pBuf;
            }                    propertyBlob;
        } value;

    }PrintPropertyValue;

    typedef struct
    {
        WCHAR*                  propertyName;
        PrintPropertyValue      propertyValue;

    }PrintNamedProperty;

    typedef struct
    {
        ULONG                   numberOfProperties;
        PrintNamedProperty*     propertiesCollection;

    }PrintPropertiesCollection;

Les structures de l'exemple de code précédent sont définies dans Winspool.h.

Les codes d'échappement suivants sont définis dans Winddiui.h.

//
 // Escape code for XPS Document events
//
#define DOCUMENTEVENT_QUERYFILTER                                     14
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE                 1
// DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE must have same value as //DOCUMENTEVENT_CREATEDCPRE for Winspool.drv to query the driver for supported events and reset the cached events.
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE                         2
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE        3                           
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST                            4
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST                        5
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST                13
// DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST must have same value as //DOCUMENTEVENT_STARTDOCPOST for Winspool.drv to signal the tray balloon that //the document is completed
#define DOCUMENTEVENT_XPS_CANCELJOB                                   6
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE      7
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE              8
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE                  9
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST                 10
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST             11
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST     12

Partager via

Événements du document du pilote XPS

Présentation du gestionnaire d'événements DrvDocumentEvent

Description du gestionnaire d'événements DrvDocumentEvent

Paramètres

Valeur retournée

Structures des événements du document XPS et valeurs des codes d'événement

Commentaires

Ressources supplémentaires