Fungsi DrvDocumentEvent (winddiui.h)

Artikel
08/08/2023

Fungsi DrvDocumentEvent antarmuka printer DLL dapat menangani peristiwa tertentu yang terkait dengan pencetakan dokumen.

Sintaks

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

Parameter

hPrinter

Handel printer yang disediakan penelepon.

hdc

Handel konteks perangkat yang disediakan penelepon, yang dihasilkan oleh CreateDC Ini nol jika iEsc diatur ke DOCUMENTEVENT_CREATEDCPRE. Untuk pembatasan pencetakan dari aplikasi 32-bit pada Windows versi 64-bit, lihat bagian Keterangan di bawah ini.

iEsc

Kode escape yang disediakan penelepon yang mengidentifikasi peristiwa yang akan ditangani.

Untuk pembatasan pencetakan dari aplikasi 32-bit pada Windows versi 64-bit, lihat bagian Keterangan di bawah ini.

Parameter ini bisa menjadi salah satu konstanta bilangan bulat berikut:

Konstanta iEsc	Kejadian
DOCUMENTEVENT_ABORTDOC	GDI akan memproses panggilan ke fungsi AbortDoc-nya .
DOCUMENTEVENT_CREATEDCPOST	GDI baru saja memproses panggilan ke fungsi CreateDC atau CreateIC-nya . Kode escape ini tidak boleh digunakan kecuali telah ada panggilan sebelumnya ke DrvDocumentEvent dengan iEsc diatur ke DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE	GDI akan memproses panggilan ke fungsi CreateDC atau CreateIC-nya .
DOCUMENTEVENT_DELETEDC	GDI akan memproses panggilan ke fungsi DeleteDC-nya .
DOCUMENTEVENT_ENDDOCPOST	GDI baru saja memproses panggilan ke fungsi EndDoc-nya .
DOCUMENTEVENT_ENDDOCPRE atau DOCUMENTEVENT_ENDDOC	GDI akan memproses panggilan ke fungsi EndDoc-nya .
DOCUMENTEVENT_ENDPAGE	GDI akan memproses panggilan ke fungsi EndPage-nya .
DOCUMENTEVENT_ESCAPE	GDI akan memproses panggilan ke fungsi ExtEscape-nya .
DOCUMENTEVENT_QUERYFILTER	Peristiwa DOCUMENTEVENT_QUERYFILTER mewakili kesempatan bagi penampung untuk mengkueri driver untuk daftar peristiwa DOCUMENTEVENT_XXX yang akan direspons driver. Kejadian ini dikeluarkan tepat sebelum panggilan ke DrvDocumentEvent yang melewati peristiwa DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	GDI baru saja memproses panggilan ke fungsi ResetDC-nya . Kode escape ini tidak boleh digunakan kecuali telah ada panggilan sebelumnya ke DrvDocumentEvent dengan iEsc diatur ke DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	GDI akan memproses panggilan ke fungsi ResetDC-nya .
DOCUMENTEVENT_STARTDOCPOST	GDI baru saja memproses panggilan ke fungsi StartDoc-nya .
DOCUMENTEVENT_STARTDOCPRE atau DOCUMENTEVENT_STARTDOC	GDI akan memproses panggilan ke fungsi StartDoc-nya .
DOCUMENTEVENT_STARTPAGE	GDI akan memproses panggilan ke fungsi StartPage-nya .

cbIn

Ukuran yang disediakan penelepon, dalam byte, dari buffer yang diacu oleh pvIn.

[in] pvIn

Penunjuk yang disediakan penelepon, yang penggunaannya tergantung pada nilai yang disediakan untuk iEsc, sebagai berikut:

Konstanta iEsc	Isi pvIn
DOCUMENTEVENT_ABORTDOC	Tidak digunakan.
DOCUMENTEVENT_CREATEDCPOST	pvIn berisi alamat penunjuk ke struktur DEVMODEW yang ditentukan dalam parameter pvOut dalam panggilan sebelumnya ke fungsi ini, di mana parameter iEsc diatur ke DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE	pvIn menunjuk ke struktur DOCEVENT_CREATEDCPRE .
DOCUMENTEVENT_DELETEDC	Tidak digunakan.
DOCUMENTEVENT_ENDDOCPOST	Tidak digunakan.
DOCUMENTEVENT_ENDDOCPRE atau DOCUMENTEVENT_ENDDOC	Tidak digunakan.
DOCUMENTEVENT_ENDPAGE	Tidak digunakan.
DOCUMENTEVENT_ESCAPE	pvIn menunjuk ke struktur DOCEVENT_ESCAPE .
DOCUMENTEVENT_QUERYFILTER	Sama seperti DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	pvIn berisi alamat pointer ke struktur DEVMODEW yang ditentukan dalam parameter pvOut dalam panggilan sebelumnya ke fungsi ini, di mana parameter iEsc diatur ke DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	pvIn berisi alamat pointer ke struktur DEVMODEW yang disediakan oleh pemanggil fungsi ResetDC .
DOCUMENTEVENT_STARTDOCPOST	pvIn menunjuk ke LONG yang menentukan pengidentifikasi pekerjaan cetak yang dikembalikan oleh fungsi StartDoc .
DOCUMENTEVENT_STARTDOCPRE atau DOCUMENTEVENT_STARTDOC	pvIn berisi alamat pointer ke struktur DOCINFO yang disediakan oleh pemanggil fungsi StartDoc .
DOCUMENTEVENT_STARTPAGE	Tidak digunakan.

cbOut

Jika iEsc DOCUMENTEVENT_ESCAPE

Nilai yang disediakan fungsi yang digunakan sebagai parameter cbOutput untuk fungsi ExtEscape .

Jika iEsc DOCUMENTEVENT_QUERYFILTER

Ukuran yang disediakan penelepon, dalam byte, dari penunjuk buffer ke oleh pvOut.

Untuk semua nilai iEsc lainnya

Tidak digunakan.

[out] pvOut

Pointer yang disediakan fungsi ke buffer output, yang penggunaannya tergantung pada nilai yang disediakan untuk iEsc, sebagai berikut:

Konstanta iEsc	Konten pvOut
DOCUMENTEVENT_CREATEDCPRE	Penunjuk ke struktur DEVMODEW yang disediakan driver, yang digunakan GDI alih-alih yang disediakan oleh pemanggil CreateDC . (Jika NULL, GDI menggunakan struktur yang disediakan pemanggil.)
DOCUMENTEVENT_ESCAPE	Penunjuk buffer yang digunakan sebagai parameter lpszOutData untuk fungsi ExtEscape .
DOCUMENTEVENT_QUERYFILTER	Penunjuk yang disediakan penelepon ke buffer yang berisi struktur DOCEVENT_FILTER .
DOCUMENTEVENT_RESETDCPRE	Penunjuk ke struktur DEVMODEW yang disediakan driver, yang digunakan GDI alih-alih yang disediakan oleh pemanggil fungsi ResetDC . (Jika NULL, GDI menggunakan struktur yang disediakan pemanggil.)
Semua nilai iEsc lainnya	Tidak digunakan.

Mengembalikan nilai

Nilai pengembalian fungsi tergantung pada escape yang disediakan untuk iEsc. Untuk beberapa kode escape, nilai yang dikembalikan tidak digunakan (lihat daftar nilai kedua). Jika fungsi memasok nilai pengembalian, itu harus salah satu dari yang berikut:

Menampilkan kode	Deskripsi
DOCUMENTEVENT_FAILURE	Driver mendukung kode escape yang diidentifikasi oleh iEsc, tetapi terjadi kegagalan.
DOCUMENTEVENT_SUCCESS	Driver berhasil menangani kode escape yang diidentifikasi oleh iEsc.
DOCUMENTEVENT_UNSUPPORTED	Driver tidak mendukung kode escape yang diidentifikasi oleh iEsc.

Keterangan

DLL antarmuka printer dapat secara opsional menyediakan fungsi DrvDocumentEvent untuk melakukan pra-pemrosesan atau pasca-pemrosesan panggilan GDI yang terkait dengan penyajian dokumen. Panggilan ke fungsi DrvDocumentEvent dilakukan dari klien GDI mode pengguna, ketika aplikasi melakukan panggilan ke klien GDI.

Untuk nilai iEsc DOCUMENTEVENT_QUERYFILTER, penampung dapat menginterpretasikan nilai DOCUMENTEVENT_SUCCESS yang dikembalikan oleh DrvDocumentEvent dengan dua cara, tergantung pada apakah driver memodifikasi anggota tertentu dari struktur DOCEVENT_FILTER . (Parameter pvOut menunjuk ke struktur ini.) Ketika spooler mengalokasikan memori untuk struktur jenis ini, penampung menginisialisasi dua anggota struktur ini, cElementsReturned dan cElementsNeeded, ke nilai yang diketahui. Setelah DrvDocumentEvent kembali, penampung menentukan apakah nilai anggota ini telah berubah, dan menggunakan informasi tersebut untuk menginterpretasikan nilai pengembalian DrvDocumentEvent . Tabel berikut ini meringkas situasi ini.

Nilai kembali	Status cElementsReturned, cElementsNeeded	Makna
DOCUMENTEVENT_SUCCESS	Driver tidak membuat perubahan pada salah satu anggota.	Penampung menginterpretasikan nilai pengembalian ini setara dengan DOCUMENTEVENT_UNSUPPORTED. Penampung tidak dapat mengambil filter peristiwa dari driver, sehingga tetap memanggil DrvDocumentEvent untuk semua peristiwa.
DOCUMENTEVENT_SUCCESS	Pengemudi menulis surat kepada satu atau kedua anggota.	Penampung menerima nilai pengembalian ini tanpa interpretasi. Jika driver hanya menulis ke salah satu cElementsNeeded dan cElementsReturned, penampung menganggap anggota yang tidak berubah memiliki nilai nol. Penampung memfilter semua peristiwa yang tercantum dalam anggota DOCEVENT_FILTER aDocEventCall.
DOCUMENTEVENT_UNSUPPORTED	Tidak berlaku	Driver tidak mendukung DOCUMENTEVENT_QUERYFILTER. Penampung tidak dapat mengambil filter peristiwa dari driver, sehingga tetap memanggil DrvDocumentEvent untuk semua peristiwa.
DOCUMENTEVENT_FAILURE	Tidak berlaku	Driver mendukung DOCUMENTEVENT_QUERYFILTER, tetapi mengalami kesalahan internal. Penampung tidak dapat mengambil filter peristiwa dari driver, sehingga tetap memanggil DrvDocumentEvent untuk semua peristiwa.

Jika nama kode escape tidak memiliki akhiran atau diakhiri dengan PRE, klien GDI memanggil DrvDocumentEvent tepat sebelum memanggil mesin rendering GDI mode kernel. Jika nama kode escape diakhiri dengan POST, klien GDI memanggil DrvDocumentEvent tepat setelah mesin penyajian GDI mode kernel kembali.

Jika kode escape yang disediakan dalam parameter iEsc DOCUMENTEVENT_CREATEDCPRE, aturan berikut berlaku:

Jika pekerjaan dikirim langsung ke printer tanpa menampung, pvIn --> pszDevice menunjuk ke nama printer. (Lihat struktur DOCEVENT_CREATEDCPRE untuk informasi selengkapnya.)
Jika pekerjaan sedang ditampung, pvIn --> pszDevice menunjuk ke nama port printer.

Fungsi DrvDocumentEvent dijalankan dalam konteks pemanggil mode pengguna fungsi klien GDI. Saat penampungan EMF dinonaktifkan, fungsi dapat menampilkan antarmuka pengguna. Misalnya, fungsi DrvDocumentEvent untuk driver FAX mungkin menampilkan kotak dialog kepada pengguna sebelum fungsi StartDoc GDI diproses.

Pembatasan berikut berlaku saat menjalankan aplikasi 32-bit pada Windows versi 64-bit:

Satu-satunya fungsi GDI yang harus dipanggil DrvDocumentEvent adalah ExtEscape, dan hanya escape privat yang harus digunakan.
Panggilan DrvDocumentEvent ke fungsi GDI lainnya dapat menghasilkan perilaku yang tidak terdefinisi.

Persyaratan

Persyaratan	Nilai
Target Platform	Desktop
Header	winddiui.h (termasuk Winddiui.h)

Lihat juga

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER