Fungsi DocumentEvent

  • Artikel

Fungsi DocumentEvent adalah penanganan aktivitas untuk peristiwa yang terkait dengan pencetakan dokumen.

Sintaks

HRESULT DocumentEvent(
  _In_  HANDLE hPrinter,
  _In_  HDC    hdc,
        INT    iEsc,
        ULONG  cbIn,
  _In_  PVOID  pvIn,
        ULONG  cbOut,
  _Out_ PVOID  pvOut
);

Parameter

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
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 DocumentEvent 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 XXX DOCUMENTEVENT_ yang akan direspons driver. Kejadian ini dikeluarkan tepat sebelum panggilan ke DocumentEvent 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 DocumentEvent 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, 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
DOCUMENTEVENT_ABORTDOC
 Tidak digunakan.
DOCUMENTEVENT_CREATEDCPOST
 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.
DOCUMENTEVENT_CREATEDCPRE
 pvIn menunjuk ke struktur DOCEVENT_CREATEDCPRE yang didokumenkan dalam Windows Driver Development Kit.
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 yang didokumenkan dalam Windows Driver Development Kit.
DOCUMENTEVENT_QUERYFILTER
 Sama seperti untuk DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST
 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.
DOCUMENTEVENT_RESETDCPRE
 pvIn berisi alamat pointer ke struktur DEVMODE yang disediakan oleh pemanggil ResetDC.
DOCUMENTEVENT_STARTDOCPOST
 pvIn menunjuk ke LONG yang menentukan pengidentifikasi pekerjaan cetak yang dikembalikan oleh StartDoc.
DOCUMENTEVENT_STARTDOCPRE atau DOCUMENTEVENT_STARTDOC
 pvIn berisi alamat pointer ke struktur DOCINFO yang disediakan oleh pemanggil StartDoc.
DOCUMENTEVENT_STARTPAGE
 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
DOCUMENTEVENT_CREATEDCPRE
 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.)
DOCUMENTEVENT_ESCAPE
 Penunjuk ke buffer yang digunakan sebagai parameter lpszOutData untuk ExtEscape.
DOCUMENTEVENT_QUERYFILTER
 Pointer ke buffer yang berisi struktur DOCEVENT_FILTER yang didokumenkan dalam Windows Driver Development Kit.
DOCUMENTEVENT_RESETDCPRE
 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 hasil

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.

Keterangan

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

Persyaratan Value
Klien minimum yang didukung
 Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung
 Windows Server 2008 [hanya aplikasi desktop]
Header
Winspool.h (termasuk Windows.h)
Nama Unicode dan ANSI
 DocumentEventW (Unicode) dan DocumentEventA (ANSI)

Baca juga