Udostępnij przez

Zdarzenia dokumentu sterownika XPS

Ważne

Nowoczesna platforma drukowania jest preferowanym sposobem komunikacji z drukarkami w systemie Windows. Zalecamy używanie sterownika klasy skrzynki odbiorczej IPP firmy Microsoft wraz z aplikacjami do obsługi drukowania (PSA), aby dostosować środowisko drukowania w systemie Windows 10 i 11 na potrzeby opracowywania urządzeń drukarki.

Aby uzyskać więcej informacji, zobacz Print Support App v1 and v2 design guide (Przewodnik projektowania aplikacji do obsługi wydruku w wersji 1 i 2).

Obsługa drukowania w ramach programu Microsoft Windows Presentation Foundation (WPF) wysyła zdarzenia powiadomień do sterowników wydruku XPSDrv podczas buforowania dokumentów, podobnie jak odpowiednio obsługa drukowania GDI wysyła powiadomienia do sterowników wydruku GDI. WPF również wykorzystuje tę samą funkcję DDI DrvDocumentEvent, z której korzysta wsparcie drukowania GDI, ale zostały zdefiniowane nowe zdarzenia do obsługi zdarzeń przetwarzania Dokumentów XPS. Obsługa drukowania GDI będzie nadal wydawać programy obsługi zdarzeń DrvDocumentEvent do sterowników wydruku opartych na interfejsie GDI i sterowników wydruku XPSDrv na potrzeby drukowania aplikacji Microsoft Win32.

Omówienie mechanizmu obsługi zdarzeń DrvDocumentEvent

W razie potrzeby sterowniki wydruku XPSDrv mogą wyeksportować program obsługi zdarzeń DrvDocumentEvent z modułu konfiguracji w celu przechwycenia funkcji przetwarzania dokumentów. Nowe zdarzenia związane z dokumentami XPS są identyfikowane przez symboliczną nazwę rozpoczynającą się od "DOCUMENTEVENT_XPS_".

Obsługa wydruku WPF wywołuje funkcję DrvDocumentEvent sterownika wydruku XPSDrv podczas spoolowania dokumentu do drukowania. Każde wywołanie odbywa się w innym kroku procesu. Krok przetwarzania każdego wywołania jest identyfikowany przez wartość argumentu iEsc . Zawartość, do której odwołują się argumenty pvIn i pvOut różni się w zależności od kroku przetwarzania.

W poniższych podsekcjach w tym temacie opisano tylko zdarzenia przetwarzania dokumentów XPS generowane przez obsługę drukowania WPF.

Opis procedury obsługi zdarzeń DrvDocumentEvent

Procedura obsługi zdarzeń DrvDocumentEvent ma następujący format wywołujący. Definicje kodu i parametrów w tej sekcji są przeznaczone tylko dla informacji.

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

Parametry

hPrinter
Uchwyt drukarki, który zapewnia obsługa wydruku WPF.

hdc
Kontekst urządzenia dostarczony przez wywołującego, wygenerowany przez wywołanie CreateDC. Ten parametr jest zerowy, jeśli dla parametru iEsc ustawiono wartość DOCUMENTEVENT_CREATEDCPRE.

Po wydrukowaniu dokumentu system będzie używać tych samych wartości zdarzeń zarówno dla dokumentów XPS, jak i GDI. Sterownik musi mieć świadomość tego podobieństwa i określić typ zadania na podstawie hdc. hdc jest równe INVALID_HANDLE_VALUE dla wszystkich wydarzeń DOCUMENTEVENT_XPS_Xxx. To sprawdzenie określi właściwą interpretację wartości zdarzeń DrvDocumentEvent na podstawie aplikacji wywołującej. Ta kontrola ma zastosowanie tylko do sterowników wydruku XPSDrv.

iEsc
Kod ucieczki dostarczony przez wywołującego, który identyfikuje zdarzenie do obsłużenia. Ten parametr może być jedną z następujących stałych całkowitych.

DOCUMENTEVENT_QUERYFILTER
Obsługa drukowania WPF wysyła to zdarzenie w celu zapytania sterownika wydruku o listę zdarzeń przetwarzania dokumentów XPS, na które sterownik odpowie. To zdarzenie jest generowane przed jakimikolwiek innymi zdarzeniami związanymi z dokumentami XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
Obsługa drukowania WPF wysyła to zdarzenie, zanim doda element FixedDocumentSequence do pliku buforu XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Obsługa drukowania WPF wysyła to zdarzenie po dodaniu FixedDocumentSequence do pliku bufora XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
Obsługa drukowania WPF wysyła to zdarzenie, zanim doda element FixedDocument do pliku buforu XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Obsługa drukowania WPF wysyła to zdarzenie po dodaniu elementu FixedDocument do pliku buforu XPS.

DOCUMENTEVENT_XPS_ADDDOCUMENTSEKWENCJIBILETDRUKUPREFIKS
WPF ma dodać PrintTicket do FixedDocumentSequence (poziom zadania).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST (dodanie sekwencji dokumentów z usunięciem pliku PrintTicket)
WPF powinna zwolnić dane zwracane przez sterownik podczas odpowiedniego zdarzenia DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF ma zamiar dodać PrintTicket do FixedDocument (poziom dokumentu).

DOCUMENTEVENT_XPS_DODAJDRUKOWANIEBILETUPODCZASFIXEDDOCUMENT
WPF powinno zwolnić dane zwracane przez sterownik podczas odpowiedniego zdarzenia DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF ma dodać PrintTicket do FixedPage (poziom strony).

DOKUMENT_EVENT_XPS_DODAJ_LISTĘ_DRUKU_STAŁEJ_STRONY_POST
WPF zwalnia dane, które sterownik zwraca podczas odpowiedniego zdarzenia DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

DOCUMENTEVENT_XPS_CANCELJOB
Obsługa drukowania WPF wysyła to zdarzenie przed wywołaniem akcji anulowania zadania.

DOCUMENTEVENT_XPS_COMMITJOB
WPF zakończył zapisywanie daty w bieżącym pliku.

cbIn
Rozmiar w bajtach buforu, do którego odwołuje się parametr pvln . Ta wartość jest dostarczana przez obsługę drukowania WPF i odczytywana przez program obsługi zdarzeń.

pvIn
Wskaźnik dostarczony przez obiekt wywołujący. Użycie tego parametru zależy od wartości iEsc , jak opisano na poniższej liście. (W przypadku zdarzeń DOCUMENTEVENT_XPS_Xxx , które nie są wyświetlane na tej liście, pvIn nie jest używane).

DOCUMENTEVENT_QUERYFILTER
pvIn wskazuje na strukturę PDOCEVENT_FILTER (tę samą co w przypadku DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn wskazuje strukturę PrintPropertiesCollection (zobacz Winspool.h), która zawiera trzy właściwości:

  • EscapeCode jest wartością EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode jest wartością zdarzenia.

  • JobIdentifier, czyli wartość EPrintPropertyType::kPropertyTypeInt32 (ULONG). Identyfikator JobIdentifier jest wymagany do wywołania metod GetJob() i SetJob().

  • JobName, czyli wartość EPrintPropertyType:: kPropertyTypeString (UNICODE).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Tak samo jak w przypadku DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn wskazuje strukturę PrintPropertiesCollection (zobacz Winspool.h), która zawiera dwie właściwości:

  • EscapeCode to wartość typu EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode jest wartością zdarzenia.

  • DocumentNumber, czyli wartość typu EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Tak samo jak w przypadku DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn wskazuje strukturę PrintPropertiesCollection (zobacz Winspool.h), która zawiera dwie właściwości:

  • EscapeCode to wartość typu EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PageNumber, czyli jest to wartość EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
Tak samo jak w przypadku DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDDOCUMENTSEKWENCJIBILETDRUKUPREFIKS
pvIn wskazuje strukturę PrintPropertiesCollection (zobacz Winspool.h), która zawiera cztery właściwości:

  • EscapeCode jest typu EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode jest wartością zdarzenia.

  • JobIdentifier, czyli wartość EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • JobName, czyli wartość EPrintPropertyType:: kPropertyTypeString (UNICODE).

  • PrintTicket, czyli wartość EPrintPropertyType:: kPropertyTypeByte.

Należy przydzielić strukturę PrintPropertiesCollection wraz z jej właściwościami podczas zdarzenia "PRE" i zwolnić ją podczas odpowiedniego zdarzenia "POST". Możesz ustawić wartość pvOut na wartość NULL , aby wskazać, że zdarzenie jest obsługiwane, ale nie interesuje cię zmiana opcji PrintTicket dla danego dokumentu lub strony. Wtyczka nigdy nie powinna odłączać się pomiędzy zdarzeniami „PRE” i „POST”.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn jest tym samym wskaźnikiem co pvOut z DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

Kierowca musi zwolnić pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn wskazuje strukturę PrintPropertiesCollection (zobacz Winspool.h), która zawiera trzy właściwości:

  • EscapeCode to wartość typu EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode jest wartością zdarzenia.

  • DocumentNumber, czyli wartość typu EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, czyli wartość EPrintPropertyType:: kPropertyTypeByte.

Należy przydzielić strukturę PrintPropertiesCollection wraz z jej właściwościami podczas zdarzenia "PRE" i zwolnić ją podczas odpowiedniego zdarzenia "POST". Możesz ustawić wartość pvOut na wartość NULL , aby wskazać, że zdarzenie jest obsługiwane, ale nie interesuje cię zmiana opcji PrintTicket dla danego dokumentu lub strony. Wtyczka nigdy nie powinna odłączać się pomiędzy zdarzeniami „PRE” i „POST”.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn jest tym samym wskaźnikiem co pvOut z DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

Kierowca musi zwolnić pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn wskazuje strukturę PrintPropertiesCollection (zobacz Winspool.h), która zawiera trzy właściwości:

  • EscapeCode to wartość typu EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode jest wartością zdarzenia.

  • „PageNumber”, czyli EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, czyli typ EPrintPropertyType:: kPropertyTypeByte.

Należy przydzielić strukturę PrintPropertiesCollection wraz z jej właściwościami podczas zdarzenia "PRE" i zwolnić ją podczas odpowiedniego zdarzenia "POST". Możesz ustawić wartość pvOut na wartość NULL , aby wskazać, że zdarzenie jest obsługiwane, ale nie interesuje cię zmiana opcji PrintTicket dla danego dokumentu lub strony. Wtyczka nigdy nie powinna odłączać się pomiędzy zdarzeniami „PRE” i „POST”.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn jest tym samym wskaźnikiem co pvOut z DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

Kierowca musi zwolnić pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn ma wartość NULL.

cbOut
Jeśli parametr iEsc zawiera DOCUMENTEVENT_QUERYFILTER, obsługa drukowania WPF zapewnia rozmiar buforu, do którego odwołuje się parametr pvOut w parametrze cbOut . Dla wszystkich innych wartości iEsc nie jest używany cbOut .

pvOut
Wskaźnik do buforu, który zapewnia obsługa wydruku WPF. Rozmiar buforu i zawartość zależą od wartości parametru iEsc . Poniższa lista zawiera opis zawartości buforu pvOut dla każdej wartości iEsc .

DOCUMENTEVENT_QUERYFILTER
Wskaźnik dostarczony przez wywołującego do bufora, który zawiera strukturę DOCEVENT_FILTER.

DOCUMENTEVENT_XPS_ADDDOCUMENTSEKWENCJIBILETDRUKUPREFIKS
Wskaźnik do struktury PrintPropertiesCollection (zobacz Winspool.h), która zawiera właściwość "PrintTicket" typu EPrintPropertyType::kPropertyTypeBuffer. Ta właściwość jest zawsze obecna. Jeśli parametr PrintTicket nie jest dostępny, wartość PrintPropertyValue.propertyBlob.pBuf ma wartość NULL.

Właściwość zawiera XML PrintTicket, z którego program Microsoft Windows Presentation Foundation (WPF) użyje PrintTicket zamiast tego dostarczonego przez wywołującego XPSDocumentWriter. (Jak pvOut ma wartość NULL lub właściwość nie jest obecna lub dane właściwości mają wartość NULL, WPF używa PrintTicket dostarczonego przez wywołującego).

Po przetworzeniu tego zdarzenia WPF wywoła DocumentEvent z DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST, co pozwoli sterownikowi zwolnić pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
null

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Wskaźnik do struktury PrintPropertiesCollection (zobacz Winspool.h), która zawiera właściwość "PrintTicket" typu EPrintPropertyType::PropertyTypeBuffer. Ta właściwość jest zawsze obecna. Jeśli parametr PrintTicket nie jest dostępny, wartość PrintPropertyValue.propertyBlob.pBuf ma wartość NULL.

Właściwość zawiera PrintTicket w formacie XML, z którego WPF będzie korzystać, zastępując ten dostarczony przez wywołującego XPSDocumentWriter. (Jak pvOut ma wartość NULL lub właściwość nie jest obecna lub dane właściwości mają wartość NULL, WPF używa PrintTicket dostarczonego przez wywołującego).

Po przetworzeniu tego zdarzenia WPF użyje DocumentEvent z DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST, aby sterownik zwolnił pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
null

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Wskaźnik do struktury PrintPropertiesCollection (zobacz Winspool.h), która zawiera właściwość "PrintTicket" typu EPrintPropertyType:: PropertyTypeBuffer. Ta właściwość jest zawsze obecna. Jeśli parametr PrintTicket nie jest dostępny, wartość PrintPropertyValue.propertyBlob.pBuf ma wartość NULL.

Właściwość zawiera PrintTicket w formacie XML, z którego WPF będzie korzystać, zastępując ten dostarczony przez wywołującego XPSDocumentWriter. (Jak pvOut ma wartość NULL lub właściwość nie jest obecna lub dane właściwości mają wartość NULL, WPF używa PrintTicket dostarczonego przez wywołującego).

Po przetworzeniu tego zdarzenia WPF wywoła DocumentEvent z dokumentem DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST, aby sterownik mógł zwolnić pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
null

Wartość zwracana

Funkcja DrvDocumentEvent zwraca jedną z następujących wartości:

DOCUMENTEVENT_SUCCESS
Sterownik pomyślnie obsłużył zidentyfikowany kod ucieczki iEsc .

DOCUMENTEVENT_FAILURE (Niepowodzenie Zdjęcia Dokumentu)
Sterownik obsługuje kod ucieczki zidentyfikowany jako iEsc, ale wystąpił błąd.

DOCUMENTEVENT_UNSUPPORTED
Sterownik nie obsługuje określonego kodu ucieczki iEsc .

Dokument XPS: struktury zdarzeń i wartości kodów zdarzeń

Poniższy przykład kodu przedstawia struktury i stałe używane przez nowe zdarzenia dokumentu 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;

Struktury w poprzednim przykładzie kodu są zdefiniowane w pliku Winspool.h.

Następujące kody ucieczki są zdefiniowane w pliku 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
  • Last updated on