Fungsi DocumentEvent
Fungsi DocumentEvent adalah penanganan aktivitas untuk peristiwa yang terkait dengan pencetakan dokumen.
HRESULT DocumentEvent(
_In_ HANDLE hPrinter,
_In_ HDC hdc,
INT iEsc,
ULONG cbIn,
_In_ PVOID pvIn,
ULONG cbOut,
_Out_ PVOID pvOut
);
hPrinter [in]
Handel ke objek printer. Gunakan fungsi OpenPrinter atau AddPrinter untuk mengambil handel printer.
hdc [in]
Handel konteks perangkat yang dihasilkan oleh panggilan CreateDC. Ini nol jika iEsc diatur ke DOCUMENTEVENT_CREATEDCPRE. Untuk pembatasan pencetakan dari aplikasi 32-bit pada Windows versi 64-bit, lihat Komentar.
iEsc
Kode escape yang mengidentifikasi peristiwa yang akan ditangani. Parameter ini bisa menjadi salah satu konstanta bilangan bulat berikut.
Terus-menerus | Aktivitas |
---|---|
|
GDI akan memproses panggilan ke fungsi AbortDoc-nya. |
|
GDI baru saja memproses panggilan ke fungsi CreateDC atau CreateIC-nya. Kode escape ini tidak boleh digunakan kecuali telah ada panggilan sebelumnya ke DocumentEvent dengan iEsc diatur ke DOCUMENTEVENT_CREATEDCPRE. |
|
GDI akan memproses panggilan ke fungsi CreateDC atau CreateIC-nya. |
|
GDI akan memproses panggilan ke fungsi DeleteDC-nya. |
|
GDI baru saja memproses panggilan ke fungsi EndDoc-nya. |
|
GDI akan memproses panggilan ke fungsi EndDoc-nya. |
|
GDI akan memproses panggilan ke fungsi EndPage-nya. |
|
GDI akan memproses panggilan ke fungsi ExtEscape-nya. |
|
Peristiwa DOCUMENTEVENT_QUERYFILTER mewakili kesempatan bagi penampung untuk mengkueri driver untuk daftar peristiwa XXX DOCUMENTEVENT_ yang akan direspons driver. Kejadian ini dikeluarkan tepat sebelum panggilan ke DocumentEvent yang melewati peristiwa DOCUMENTEVENT_CREATEDCPRE. |
|
GDI baru saja memproses panggilan ke fungsi ResetDC-nya. Kode escape ini tidak boleh digunakan kecuali telah ada panggilan sebelumnya ke DocumentEvent dengan iEsc diatur ke DOCUMENTEVENT_RESETDCPRE. |
|
GDI akan memproses panggilan ke fungsi ResetDC-nya. |
|
GDI baru saja memproses panggilan ke fungsi StartDoc-nya. |
|
GDI akan memproses panggilan ke fungsi StartDoc-nya. |
|
GDI akan memproses panggilan ke fungsi StartPage-nya. |
cbIn
Ukuran, dalam byte, dari buffer yang diacu oleh pvIn.
pvIn [in]
Penunjuk ke buffer. Apa yang dikandung buffer bergantung pada nilai iEsc, seperti yang diperlihatkan dalam tabel berikut.
Terus-menerus | pvin Contents |
---|---|
|
Tidak digunakan. |
|
pvIn berisi alamat penunjuk ke struktur DEVMODE yang ditentukan dalam parameter pvOut dalam panggilan sebelumnya ke fungsi ini, di mana parameter iEsc diatur ke DOCUMENTEVENT_CREATEDCPRE. |
|
pvIn menunjuk ke struktur DOCEVENT_CREATEDCPRE yang didokumenkan dalam Windows Driver Development Kit. |
|
Tidak digunakan. |
|
Tidak digunakan. |
|
Tidak digunakan. |
|
Tidak digunakan. |
|
pvIn menunjuk ke struktur DOCEVENT_ESCAPE yang didokumenkan dalam Windows Driver Development Kit. |
|
Sama seperti untuk DOCUMENTEVENT_CREATEDCPRE. |
|
pvIn berisi alamat penunjuk ke struktur DEVMODE yang ditentukan dalam parameter pvOut dalam panggilan sebelumnya ke fungsi ini, di mana parameter iEsc diatur ke DOCUMENTEVENT_RESETDCPRE. |
|
pvIn berisi alamat pointer ke struktur DEVMODE yang disediakan oleh pemanggil ResetDC. |
|
pvIn menunjuk ke LONG yang menentukan pengidentifikasi pekerjaan cetak yang dikembalikan oleh StartDoc. |
|
pvIn berisi alamat pointer ke struktur DOCINFO yang disediakan oleh pemanggil StartDoc. |
|
Tidak digunakan. |
cbOut
Value | Makna |
---|---|
IDOCUMENTEVENT_QUERYFILTER | Ukuran, dalam byte, dari penunjuk buffer ke oleh pvOut. |
DOCUMENTEVENT_ESCAPE | Nilai yang digunakan sebagai parameter cbOutput untuk ExtEscape. |
Untuk semua nilai lainnya | iEsc tidak digunakan. |
pvOut [out]
Penunjuk ke buffer. Konten buffer bergantung pada nilai yang disediakan untuk iEsc, seperti yang diperlihatkan dalam tabel berikut.
Terus-menerus | Isi pvOut |
---|---|
|
Penunjuk ke struktur DEVMODE yang disediakan driver, yang digunakan GDI alih-alih yang disediakan oleh pemanggil CreateDC. (Jika NULL, GDI menggunakan struktur yang disediakan pemanggil.) |
|
Penunjuk ke buffer yang digunakan sebagai parameter lpszOutData untuk ExtEscape. |
|
Pointer ke buffer yang berisi struktur DOCEVENT_FILTER yang didokumenkan dalam Windows Driver Development Kit. |
|
Penunjuk ke struktur DEVMODE yang disediakan driver, yang digunakan GDI alih-alih yang disediakan oleh pemanggil ResetDC. (Jika NULL, GDI menggunakan struktur yang disediakan pemanggil.) |
Nilai pengembalian fungsi tergantung pada escape yang disediakan untuk iEsc. Untuk beberapa kode escape, nilai pengembalian tidak digunakan (lihat di bawah). Jika fungsi memasok nilai pengembalian, fungsi tersebut harus menjadi salah satu dari yang berikut ini.
Tampilkan Nilai | Makna |
---|---|
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. |
Daftar berikut menunjukkan kode escape mana yang memerlukan nilai pengembalian dan mana yang tidak, dan menjelaskan arti DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE, dan DOCUMENTEVENT_UNSUPPORTED mengembalikan kode.
Tampilkan Nilai | Makna |
---|---|
DOCUMENTEVENT_ABORTDOC | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_CREATEDCPOST | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_CREATEDCPRE | DOCUMENTEVENT_FAILURE - GDI tidak membuat konteks perangkat atau konteks informasi, dan menyediakan nilai pengembalian 0 untuk CreateDC atau CreateIC. |
DOCUMENTEVENT_DELETEDC | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_ENDDOCPOST | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_ENDDOCPRE atau DOCUMENTEVENT_ENDDOC | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_ENDPAGE | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_ESCAPE | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_QUERYFILTER | Lihat Keterangan. |
DOCUMENTEVENT_RESETDCPOST | Nilai pengembalian tidak digunakan dan tidak boleh dibaca. |
DOCUMENTEVENT_RESETDCPRE | DOCUMENTEVENT_FAILURE - GDI tidak mengatur ulang konteks perangkat, dan memberikan nilai pengembalian 0 untuk ResetDC. |
DOCUMENTEVENT_STARTDOCPOST | DOCUMENTEVENT_FAILURE - GDI memanggil AbortDoc untuk menghentikan dokumen, lalu menyediakan nilai pengembalian SP_ERROR untuk StartDoc. |
DOCUMENTEVENT_STARTDOCPRE atau DOCUMENTEVENT_STARTDOC | DOCUMENTEVENT_FAILURE - GDI tidak memulai dokumen, dan menyediakan nilai pengembalian SP_ERROR untuk StartDoc. |
DOCUMENTEVENT_STARTPAGE | DOCUMENTEVENT_FAILURE - GDI tidak memulai halaman, dan menyediakan nilai pengembalian SP_ERROR untuk StartPage. |
Untuk nilai iEsc DOCUMENTEVENT_QUERYFILTER, penampung dapat menginterpretasikan nilai DOCUMENTEVENT_SUCCESS yang dikembalikan oleh DocumentEvent dengan dua cara, tergantung pada apakah driver memodifikasi anggota tertentu dari struktur DOCEVENT_FILTER (yang didokumentasikan dalam Windows Driver Development Kit ). (Parameter pvOut menunjuk ke struktur ini.) Ketika penampung mengalokasikan memori untuk struktur jenis ini, ia menginisialisasi dua anggota struktur ini, cElementsReturned dan cElementsNeeded, ke nilai yang diketahui. Setelah DocumentEvent kembali, penampung menentukan apakah nilai anggota ini telah berubah, dan menggunakan informasi tersebut untuk menginterpretasikan nilai pengembalian DocumentEvent . Tabel berikut ini meringkas situasi ini.
Tampilkan Nilai | Status cElementsReturned dan 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 dalam memanggil DocumentEvent untuk semua peristiwa. |
DOCUMENTEVENT_SUCCESS |
Driver menulis 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 aDocEventCall dari DOCEVENT_FILTER (yang didokumentasikan dalam Windows Driver Development Kit ). |
DOCUMENTEVENT_UNSUPPORTED |
Tidak berlaku |
Pengandar tidak mendukung DOCUMENTEVENT_QUERYFILTER. Penampung tidak dapat mengambil filter peristiwa dari driver, sehingga tetap dalam memanggil DocumentEvent 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 dalam memanggil DocumentEvent untuk semua peristiwa. |
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. (Untuk informasi selengkapnya, lihat dokumentasi untuk struktur DOCEVENT_CREATEDCPRE di Kit Pengembangan Driver Windows.)
- Jika pekerjaan sedang ditampung, pvIn-pszDevice> menunjuk ke nama port printer.
Catatan
Pembatasan berikut berlaku saat menjalankan aplikasi 32-bit pada Windows versi 64-bit. Satu-satunya fungsi GDI yang harus dipanggil DocumentEvent adalah ExtEscape, dan hanya escape privat yang harus digunakan. Panggilan DocumentEvent ke fungsi GDI lainnya dapat menghasilkan perilaku yang tidak terdefinisi.
Persyaratan | Value |
---|---|
Klien minimum yang didukung |
Windows Vista [hanya aplikasi desktop] |
Server minimum yang didukung |
Windows Server 2008 [hanya aplikasi desktop] |
Header |
|
Nama Unicode dan ANSI |
DocumentEventW (Unicode) dan DocumentEventA (ANSI) |