Événements de document du pilote XPS
Important
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 le Guide de conception d’application de support d’impression.
La prise en charge de l’impression de Microsoft Windows Presentation Foundation (WPF) envoie des événements de notification des pilotes d’impression XPSDrv pendant lepooling de documents de la même façon que la prise en charge de l’impression GDI envoie des notifications aux pilotes d’impression GDI. La prise en charge de l’impression WPF utilise également la même fonction DrvDocumentEvent DDI que celle utilisée par la prise en charge de l’impression GDI, mais de nouveaux événements ont été définis pour prendre en charge les événements de traitement de documents XPS. La prise en charge de l’impression GDI continuera à émettre des gestionnaires d’événements DrvDocumentEvent aux pilotes d’impression basés sur GDI et aux pilotes d’impression XPSDrv pour l’impression d’applications Microsoft Win32.
Vue d’ensemble du gestionnaire d’événements DrvDocumentEvent
Si nécessaire, les pilotes d’impression XPSDrv peuvent exporter le gestionnaire d’événements DrvDocumentEvent à partir du module de configuration pour intercepter les fonctions de traitement de documents. Les nouveaux événements liés au document XPS sont identifiés par un nom symbolique commençant par « DOCUMENTEVENT_XPS_ ».
La prise en charge de l’impression WPF appelle la fonction DrvDocumentEvent du pilote d’impression XPSDrv pendant qu’elle pool le document pour l’impression. Chaque appel se produit à 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 mémoires tampons référencées 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 de documents XPS que la prise en charge de l’impression WPF produit.
Description du gestionnaire d’événements DrvDocumentEvent
Le gestionnaire d’événements DrvDocumentEvent a le format d’appel suivant. Le code et les définitions de paramètres de cette section ne sont que pour des informations.
INT
DrvDocumentEvent(
HANDLE hPrinter,
HDC hdc,
int iEsc,
ULONG cbIn,
PVOID pvIn,
ULONG cbOut,
PVOID pvOut
);
Paramètres
hPrinter
Handle d’imprimante fourni par la prise en charge de l’impression WPF.
Hdc
Handle de contexte d’appareil fourni par l’appelant que génère un appel CreateDC . Ce paramètre est égal à zéro si iEsc est défini sur 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 connaître cette similarité et déterminer le type du travail basé sur le hdc. hdc est égal à INVALID_HANDLE_VALUE pour tous les événements DOCUMENTEVENT_XPS_Xxx . Cette case activée détermine l’interprétation appropriée des valeurs d’événement DrvDocumentEvent en fonction de l’application appelante. Cette case activée s’applique uniquement aux pilotes d’impression XPSDrv.
iEsc
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
La prise en charge de l’impression WPF envoie cet événement pour interroger le pilote d’impression pour obtenir la liste des événements de traitement de documents XPS auxquels le pilote répondra. Cet événement est émis avant tout autre événement lié au document XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
La prise en charge de l’impression WPF envoie cet événement avant d’ajouter FixedDocumentSequence au fichier depool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
La prise en charge de l’impression WPF envoie cet événement après avoir ajouté FixedDocumentSequence au fichier depool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
La prise en charge de l’impression WPF envoie cet événement avant d’ajouter FixedDocument au fichier depool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
La prise en charge de l’impression WPF envoie cet événement après avoir ajouté FixedDocument au fichier depool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF est sur le point d’ajouter un PrintTicket à FixedDocumentSequence (niveau de travail).
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF doit libérer les données retournées par le pilote sur l’événement de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE correspondant.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF est sur le point d’ajouter un PrintTicket au FixedDocument (niveau du document).
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF doit libérer les données retournées par le pilote sur l’événement de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE correspondant.
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF est sur le point d’ajouter un PrintTicket à la page fixe (niveau de page).
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF libère les données retournées par le pilote sur l’événement de DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE correspondant.
DOCUMENTEVENT_XPS_CANCELJOB
La prise en charge de l’impression WPF envoie cet événement avant d’appeler une action d’annulation de travail.
DOCUMENTEVENT_XPS_COMMITJOB
WPF a terminé d’écrire la date dans le fichier actif.
Rcib
Taille, en octets, de la mémoire tampon référencée par le paramètre pvln . Cette valeur est fournie par la prise en charge de l’impression WPF et lue par le gestionnaire d’événements.
pvIn
Pointeur fourni par l’appelant. L’utilisation de ce paramètre dépend de la valeur iEsc , comme décrit dans la liste suivante. (Pour le DOCUMENTEVENT_XPS_Événements Xxx qui ne sont pas affichés dans cette liste, pvIn n’est pas utilisé.)
DOCUMENTEVENT_QUERYFILTER
pvIn pointe vers une structure PDOCEVENT_FILTER (identique à celle de DOCUMENTEVENT_QUERYFILTER).
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn pointe vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient trois propriétés :
EscapeCode, qui est EPrintPropertyType ::kPropertyTypeInt32 (ULONG). EscapeCode est la valeur de l’événement.
JobIdentifier, qui est une valeur EPrintPropertyType ::kPropertyTypeInt32 (ULONG). JobIdentifier est l’ID nécessaire pour appeler GetJob() et SetJob().
JobName, qui est une valeur EPrintPropertyType :: kPropertyTypeString (UNICODE).
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Identique à 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 EPrintPropertyType ::kPropertyTypeInt32 (ULONG).
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Identique à 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).
PageNumber, qui est une valeur 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 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 sur l’événement « PRE » et la libérer sur l’événement « POST » correspondant. Vous pouvez définir pvOut sur NULL pour indiquer que vous prenez en charge l’événement, mais n’êtes pas intéressé par la modification de PrintTicket pour un document ou une page donné. Le plug-in ne doit jamais 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 conducteur 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 EPrintPropertyType ::kPropertyTypeInt32 (ULONG).
PrintTicket, qui est une valeur EPrintPropertyType :: kPropertyTypeByte.
Vous devez allouer la structure PrintPropertiesCollection et ses propriétés sur l’événement « PRE » et la libérer sur l’événement « POST » correspondant. Vous pouvez définir pvOut sur NULL pour indiquer que vous prenez en charge l’événement, mais n’êtes pas intéressé par la modification de PrintTicket pour un document ou une page donné. Le plug-in ne doit jamais décharger entre les événements « PRE » et « POST ».
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn est le même pointeur que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.
Le conducteur 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.
Vous devez allouer la structure PrintPropertiesCollection et ses propriétés sur l’événement « PRE » et la libérer sur l’événement « POST » correspondant. Vous pouvez définir pvOut sur NULL pour indiquer que vous prenez en charge l’événement, mais n’êtes pas intéressé par la modification de PrintTicket pour un document ou une page donné. Le plug-in ne doit jamais décharger entre les événements « PRE » et « POST ».
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn est le même pointeur que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.
Le conducteur doit libérer pvIn.
DOCUMENTEVENT_XPS_CANCELJOB
pvIn est NULL.
cbOut
Si le paramètre iEsc contient DOCUMENTEVENT_QUERYFILTER, la prise en charge de l’impression WPF fournit la taille de la mémoire tampon référencée par le paramètre pvOut dans le paramètre cbOut . Pour toutes les autres valeurs d’iEsc, cbOut n’est pas utilisé.
pvOut
Pointeur vers une mémoire tampon que la prise en charge de l’impression WPF fournit. 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 une mémoire tampon qui contient une structure DOCEVENT_FILTER.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
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. Quand aucun PrintTicket n’est disponible, la valeur de PrintPropertyValue.propertyBlob.pBuf est NULL.
La propriété contient le printTicket XML, à partir duquel Microsoft Windows Presentation Foundation (WPF) utilisera le PrintTicket au lieu de celui que l’appelant XPSDocumentWriter fournit. (Si pvOut a la valeur NULL ou que la propriété n’est pas présente ou que les données de propriété sont NULL, WPF utilise le printTicket fourni par l’appelant.)
Une fois cet événement traité, WPF appelle DocumentEvent avec DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST pour que le pilote libère pvOut.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Pointeur vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient une propriété « PrintTicket » de type EPrintPropertyType ::P ropertyTypeBuffer. Cette propriété est toujours présente. Quand aucun PrintTicket n’est disponible, la valeur de PrintPropertyValue.propertyBlob.pBuf est NULL.
La propriété contient le code XML PrintTicket, à partir duquel WPF utilisera le printTicket au lieu de celui que l’appelant XPSDocumentWriter fournit. (Si pvOut a la valeur NULL ou que la propriété n’est pas présente ou que les données de propriété sont NULL, WPF utilise le printTicket fourni par l’appelant.)
Une fois cet événement traité, WPF appelle DocumentEvent avec DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST pour que le pilote libère pvOut.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Pointeur vers une structure PrintPropertiesCollection (voir Winspool.h) qui contient une propriété « PrintTicket » de type EPrintPropertyType :: PropertyTypeBuffer. Cette propriété est toujours présente. Quand aucun PrintTicket n’est disponible, la valeur de PrintPropertyValue.propertyBlob.pBuf est NULL.
La propriété contient le code XML PrintTicket, à partir duquel WPF utilisera le printTicket au lieu de celui que l’appelant XPSDocumentWriter fournit. (Si pvOut a la valeur NULL ou que la propriété n’est pas présente ou que les données de propriété sont NULL, WPF utilise le printTicket fourni par l’appelant.)
Une fois cet événement traité, WPF appelle DocumentEvent avec DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST pour que le pilote libère pvOut.
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL
Valeur retournée
DrvDocumentEvent retourne l’une des valeurs suivantes :
DOCUMENTEVENT_SUCCESS
Le pilote a réussi à gérer le code d’échappement identifié par iEsc .
DOCUMENTEVENT_FAILURE
Le pilote prend en charge le code d’échappement identifié par iEsc , mais une défaillance s’est produite.
DOCUMENTEVENT_UNSUPPORTED
Le pilote ne prend pas en charge le code d’échappement identifié par iEsc .
Structures d’événements de document XPS et valeurs de code d’événement
L’exemple de code suivant montre les structures et les constantes utilisées par les nouveaux événements de document XPS.
//
// 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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour