Bagikan melalui

Peristiwa dokumen driver XPS

  • Artikel

Penting

Platform cetak modern adalah sarana komunikasi pilihan Windows dengan printer. Kami menyarankan agar Anda menggunakan driver kelas kotak masuk IPP Microsoft, bersama dengan Print Support Apps (PSA), untuk menyesuaikan pengalaman cetak di Windows 10 dan 11 untuk pengembangan perangkat printer.

Untuk informasi selengkapnya, lihat Platform cetak modern dan panduan desain aplikasi dukungan Cetak.

Dukungan cetak Microsoft Windows Presentation Foundation (WPF) mengirimkan peristiwa pemberitahuan driver cetak XPSDrv selama penampungan dokumen mirip dengan cara dukungan cetak GDI mengirim pemberitahuan ke driver cetak GDI. Dukungan cetak WPF juga menggunakan fungsi DDI DrvDocumentEvent yang sama dengan yang digunakan dukungan cetak GDI, tetapi peristiwa baru telah didefinisikan untuk mendukung peristiwa pemrosesan Dokumen XPS. Dukungan cetak GDI akan terus mengeluarkan penanganan aktivitas DrvDocumentEvent ke driver cetak berbasis GDI dan driver cetak XPSDrv untuk pencetakan aplikasi Microsoft Win32.

Gambaran umum penanganan aktivitas DrvDocumentEvent

Jika perlu, driver cetak XPSDrv dapat mengekspor penanganan aktivitas DrvDocumentEvent dari modul konfigurasi untuk mencegat fungsi pemrosesan dokumen. Peristiwa terkait Dokumen XPS baru diidentifikasi dengan nama simbolis yang dimulai dengan "DOCUMENTEVENT_XPS_".

Dukungan cetak WPF memanggil fungsi DrvDocumentEvent dari driver cetak XPSDrv saat membungkus dokumen untuk pencetakan. Setiap panggilan terjadi pada langkah yang berbeda dalam proses. Langkah pemrosesan setiap panggilan diidentifikasi oleh nilai argumen iEsc . Konten buffer yang dirujuk oleh argumen pvIn dan pvOut bervariasi, tergantung pada langkah pemrosesan.

Sub bagian berikut dalam topik ini hanya menjelaskan peristiwa pemrosesan Dokumen XPS yang dihasilkan oleh dukungan cetak WPF.

Deskripsi penanganan aktivitas DrvDocumentEvent

Penanganan aktivitas DrvDocumentEvent memiliki format panggilan berikut. Definisi kode dan parameter di bagian ini hanya untuk informasi.

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

Parameter

hPrinter
Handel pencetak yang disediakan oleh dukungan cetak WPF.

hdc
Konteks perangkat yang disediakan penelepon menangani panggilan CreateDC yang dihasilkan. Parameter ini nol jika iEsc diatur ke DOCUMENTEVENT_CREATEDCPRE.

Ketika dokumen dicetak, sistem akan menggunakan nilai peristiwa yang sama untuk dokumen XPS dan GDI. Driver harus menyadari kesamaan ini dan menentukan jenis pekerjaan berdasarkan hdc. hdc sama dengan INVALID_HANDLE_VALUE untuk semua peristiwa DOCUMENTEVENT_XPS_Xxx . Pemeriksaan ini akan menentukan interpretasi yang tepat dari nilai peristiwa DrvDocumentEvent berdasarkan aplikasi panggilan. Pemeriksaan ini hanya berlaku untuk driver cetak XPSDrv.

iEsc
Kode escape yang disediakan penelepon yang mengidentifikasi peristiwa yang akan ditangani. Parameter ini bisa menjadi salah satu konstanta bilangan bulat berikut.

DOCUMENTEVENT_QUERYFILTER
Dukungan cetak WPF mengirimkan kejadian ini untuk mengkueri driver cetak untuk daftar peristiwa pemrosesan Dokumen XPS yang akan direspons driver. Kejadian ini dikeluarkan sebelum peristiwa terkait Dokumen XPS lainnya.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
Dukungan cetak WPF mengirimkan kejadian ini sebelum menambahkan FixedDocumentSequence ke file spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Dukungan cetak WPF mengirimkan kejadian ini setelah menambahkan FixedDocumentSequence ke file spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
Dukungan cetak WPF mengirimkan kejadian ini sebelum menambahkan FixedDocument ke file spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Dukungan cetak WPF mengirimkan peristiwa ini setelah menambahkan FixedDocument ke file spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF akan menambahkan PrintTicket ke FixedDocumentSequence (Tingkat Pekerjaan).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF harus membebaskan data yang dikembalikan driver pada peristiwa DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE yang sesuai.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF akan menambahkan PrintTicket ke FixedDocument (Tingkat Dokumen).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF harus membebaskan data yang dikembalikan driver pada peristiwa DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE yang sesuai.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF akan menambahkan PrintTicket ke FixedPage (Tingkat Halaman).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF membebaskan data yang dikembalikan driver pada peristiwa DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE yang sesuai.

DOCUMENTEVENT_XPS_CANCELJOB
Dukungan cetak WPF mengirimkan kejadian ini sebelum memanggil tindakan batalkan pekerjaan.

DOCUMENTEVENT_XPS_COMMITJOB
WPF selesai menulis tanggal ke file saat ini.

cbIn
Ukuran, dalam byte, dari buffer yang dirujuk parameter pvln . Nilai ini disediakan oleh dukungan cetak WPF dan dibaca oleh penanganan aktivitas.

pvIn
Penunjuk yang disediakan penelepon. Penggunaan parameter ini tergantung pada nilai iEsc , seperti yang dijelaskan daftar berikut. (Untuk DOCUMENTEVENT_XPS_Kejadian Xxx yang tidak ditampilkan dalam daftar ini, pvIn tidak digunakan.)

DOCUMENTEVENT_QUERYFILTER
pvIn menunjuk ke struktur PDOCEVENT_FILTER (sama seperti untuk DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn menunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi tiga properti:

  • EscapeCode, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode adalah nilai peristiwa.

  • JobIdentifier, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG). JobIdentifier adalah ID yang diperlukan untuk memanggil GetJob() dan SetJob().

  • JobName, yang merupakan nilai EPrintPropertyType:: kPropertyTypeString (UNICODE).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Sama seperti untuk DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn menunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi dua properti:

  • EscapeCode, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode adalah nilai peristiwa.

  • DocumentNumber, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Sama seperti untuk DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn menunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi dua properti:

  • EscapeCode, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PageNumber, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
Sama seperti untuk DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn menunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi empat properti:

  • EscapeCode, yang merupakan EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode adalah nilai peristiwa.

  • JobIdentifier, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • JobName, yang merupakan nilai EPrintPropertyType:: kPropertyTypeString (UNICODE).

  • PrintTicket, yang merupakan nilai EPrintPropertyType:: kPropertyTypeByte.

Anda harus mengalokasikan struktur PrintPropertiesCollection dan propertinya pada peristiwa "PRE" dan membebaskannya pada peristiwa "POST" yang sesuai. Anda dapat mengatur pvOut ke NULL untuk menunjukkan bahwa Anda mendukung peristiwa tetapi tidak tertarik untuk mengubah PrintTicket untuk dokumen atau halaman tertentu. Plug-in tidak boleh membongkar antara peristiwa "PRE" dan "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn adalah penunjuk yang sama dengan pvOut dari DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

Driver harus membebaskan pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn menunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi tiga properti:

  • EscapeCode, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode adalah nilai peristiwa.

  • DocumentNumber, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, yang merupakan nilai EPrintPropertyType:: kPropertyTypeByte.

Anda harus mengalokasikan struktur PrintPropertiesCollection dan propertinya pada peristiwa "PRE" dan membebaskannya pada peristiwa "POST" yang sesuai. Anda dapat mengatur pvOut ke NULL untuk menunjukkan bahwa Anda mendukung peristiwa tetapi tidak tertarik untuk mengubah PrintTicket untuk dokumen atau halaman tertentu. Plug-in tidak boleh membongkar antara peristiwa "PRE" dan "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn adalah pointer yang sama dengan pvOut dari DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

Driver harus membebaskan pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn menunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi tiga properti:

  • EscapeCode, yang merupakan nilai EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode adalah nilai peristiwa.

  • PageNumber, yang merupakan EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, yang merupakan EPrintPropertyType:: kPropertyTypeByte.

Anda harus mengalokasikan struktur PrintPropertiesCollection dan propertinya pada peristiwa "PRE" dan membebaskannya pada peristiwa "POST" yang sesuai. Anda dapat mengatur pvOut ke NULL untuk menunjukkan bahwa Anda mendukung peristiwa tetapi tidak tertarik untuk mengubah PrintTicket untuk dokumen atau halaman tertentu. Plug-in tidak boleh membongkar antara peristiwa "PRE" dan "POST".

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn adalah pointer yang sama dengan pvOut dari DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

Driver harus membebaskan pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn adalah NULL.

cbOut
Jika parameter iEsc berisi DOCUMENTEVENT_QUERYFILTER, dukungan cetak WPF menyediakan ukuran buffer yang dirujuk parameter pvOut dalam parameter cbOut. Untuk semua nilai iEsc lainnya, cbOut tidak digunakan.

pvOut
Penunjuk ke buffer yang disediakan oleh dukungan cetak WPF. Ukuran dan konten buffer bergantung pada nilai parameter iEsc . Daftar berikut ini menjelaskan konten buffer pvOut untuk setiap nilai iEsc .

DOCUMENTEVENT_QUERYFILTER
Penunjuk yang disediakan penelepon ke buffer yang berisi struktur DOCEVENT_FILTER.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Penunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi properti "PrintTicket" jenis EPrintPropertyType::kPropertyTypeBuffer. Properti ini selalu ada. Ketika tidak ada PrintTicket yang tersedia, nilai PrintPropertyValue.propertyBlob.pBuf adalah NULL.

Properti berisi XML PrintTicket, tempat Microsoft Windows Presentation Foundation (WPF) akan menggunakan PrintTicket alih-alih yang disediakan pemanggil XPSDocumentWriter . (Jika pvOut null atau properti tidak ada atau data properti null, WPF menggunakan PrintTicket yang disediakan pemanggil.)

Setelah peristiwa ini diproses, WPF akan memanggil DocumentEvent dengan DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST agar driver merilis pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Penunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi properti "PrintTicket" jenis EPrintPropertyType::P ropertyTypeBuffer. Properti ini selalu ada. Ketika tidak ada PrintTicket yang tersedia, nilai PrintPropertyValue.propertyBlob.pBuf adalah NULL.

Properti berisi XML PrintTicket, tempat WPF akan menggunakan PrintTicket alih-alih yang disediakan pemanggil XPSDocumentWriter . (Jika pvOut null atau properti tidak ada atau data properti null, WPF menggunakan PrintTicket yang disediakan pemanggil.)

Setelah peristiwa ini diproses, WPF akan memanggil DocumentEvent dengan DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST agar driver merilis pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Penunjuk ke struktur PrintPropertiesCollection (lihat Winspool.h) yang berisi properti "PrintTicket" jenis EPrintPropertyType:: PropertyTypeBuffer. Properti ini selalu ada. Ketika tidak ada PrintTicket yang tersedia, nilai PrintPropertyValue.propertyBlob.pBuf adalah NULL.

Properti berisi XML PrintTicket, tempat WPF akan menggunakan PrintTicket alih-alih yang disediakan pemanggil XPSDocumentWriter . (Jika pvOut null atau properti tidak ada atau data properti null, WPF menggunakan PrintTicket yang disediakan pemanggil.)

Setelah peristiwa ini diproses, WPF akan memanggil DocumentEvent dengan DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST agar driver merilis pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Nilai hasil

DrvDocumentEvent mengembalikan salah satu nilai berikut:

DOCUMENTEVENT_SUCCESS
Driver berhasil menangani kode escape yang diidentifikasi iEsc .

DOCUMENTEVENT_FAILURE
Driver mendukung kode escape yang diidentifikasi iEsc , tetapi terjadi kegagalan.

DOCUMENTEVENT_UNSUPPORTED
Driver tidak mendukung kode escape yang diidentifikasi iEsc .

Struktur peristiwa dokumen XPS dan nilai kode peristiwa

Contoh kode berikut menunjukkan struktur dan konstanta yang digunakan peristiwa Dokumen XPS baru.

//
// 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;

Struktur dalam contoh kode sebelumnya didefinisikan dalam Winspool.h.

Kode escape berikut didefinisikan dalam 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