Fungsi StartXpsPrintJob (xpsprint.h)

Artikel
03/15/2023

[StartXpsPrintJob tidak didukung dan dapat diubah atau tidak tersedia di masa mendatang. ]

Mulai mencetak aliran dokumen XPS ke printer.

Sintaks

HRESULT StartXpsPrintJob(
  [in]  LPCWSTR            printerName,
  [in]  LPCWSTR            jobName,
  [in]  LPCWSTR            outputFileName,
  [in]  HANDLE             progressEvent,
  [in]  HANDLE             completionEvent,
  [in]  UINT8              *printablePagesOn,
  [in]  UINT32             printablePagesOnCount,
  [out] IXpsPrintJob       **xpsPrintJob,
  [out] IXpsPrintJobStream **documentStream,
  [out] IXpsPrintJobStream **printTicketStream
);

Parameter

[in] printerName

Nama pencetak yang akan dikaitkan dengan pekerjaan ini.

[in] jobName

Nama pekerjaan yang ditentukan pengguna untuk dikaitkan dengan pekerjaan ini. Jika pekerjaan tidak memerlukan nama terpisah yang ditentukan pengguna, parameter ini dapat diatur ke NULL.

[in] outputFileName

Nama file dari file atau port tempat output pekerjaan ini akan dialihkan. Mengatur nilai ini akan menyebabkan output pekerjaan cetak diarahkan ke file atau port yang ditentukan. Untuk mengirim tugas cetak ke pencetak yang ditentukan oleh printerName, parameter ini harus diatur ke NULL.

[in] progressEvent

Handel peristiwa yang disinyalir ketika perubahan pekerjaan cetak berikut terjadi:

ID pekerjaan ditetapkan ke pekerjaan cetak
Pencetakan halaman telah selesai
Pencetakan dokumen telah selesai
Tugas cetak telah dibatalkan atau telah berakhir karena kesalahan

Catatan Kejadian ini tidak akan disinyalir hingga aplikasi mulai mengirim data ke pekerjaan cetak.

XPS Print API tidak mengatur ulang kejadian ini—itulah tanggung jawab pemanggil.

Jika tidak ada pemberitahuan kemajuan yang diperlukan, parameter ini dapat diatur ke NULL.

[in] completionEvent

Handel peristiwa yang disinyalir ketika pekerjaan cetak selesai. Kejadian ini dijamin akan disinyalir tepat sekali per panggilan StartXpsPrintJob . XPS Print API tidak mengatur ulang kejadian ini—itulah tanggung jawab pemanggil.

Jika tidak ada pemberitahuan penyelesaian yang diperlukan, parameter ini dapat diatur ke NULL.

[in] printablePagesOn

Parameter mereferensikan array UINT8 yang elemennya menentukan subset halaman dokumen yang akan dicetak. Seperti yang ditunjukkan dalam tabel berikut, nilai setiap elemen menunjukkan apakah halaman akan dicetak.

Nilai Elemen Array	Makna
0	Jangan cetak halaman.
Bukan nol	Cetak halaman.

Peristiwa kemajuan hanya akan disinyalir untuk halaman yang ditunjuk untuk pencetakan.

Elemen dalam array mewakili semua halaman yang ditunjuk untuk pencetakan, di semua dokumen paket XPS. Misalnya, jika paket berisi dua dokumen yang masing-masing memiliki tiga halaman, array yang diperlihatkan dalam tabel berikut menunjuk pencetakan halaman 0 dan 2 dari dokumen 1, dan halaman 0 dan 2 dari dokumen 2.

Indeks elemen	Nilai Elemen	Cetak?	Nomor dokumen	Nomor halaman
5	1	Ya	2	2
4	0	Tidak	2	1
3	1	Ya	2	0
2	1	Ya	1	2
1	0	Tidak	1	1
0	1	Ya	1	0

Jika printablePagesOnADALAH NULL, semua halaman dalam paket akan dicetak.

Jika printablePagesOn memiliki lebih banyak elemen daripada halaman dalam paket, elemen yang berlebihan akan diabaikan.

Jika array memiliki lebih sedikit elemen daripada ada halaman dalam dokumen, nilai elemen array terakhir dari array diterapkan ke halaman yang tersisa. Aturan ini memudahkan untuk menentukan rentang yang terbuka atau yang hanya mendapatkan beberapa halaman dari dokumen besar yang dicetak.

[in] printablePagesOnCount

Jumlah elemen dalam array yang dirujuk oleh printablePagesOn. Jika printablePagesOnADALAH NULL, parameter ini diabaikan.

[out] xpsPrintJob

Penunjuk ke antarmuka IXpsPrintJob yang mewakili pekerjaan cetak yang dibuat oleh StartXpsPrintJob. Untuk mendapatkan status pekerjaan cetak atau membatalkannya, gunakan antarmuka IXpsPrintJob . Jika IXpsPrintJob tidak diperlukan, parameter ini dapat diatur ke NULL.

[out] documentStream

Penunjuk ke antarmuka IXpsPrintJobStream tempat pemanggil menulis dokumen XPS yang akan dicetak oleh pekerjaan cetak ini.

[out] printTicketStream

Penunjuk ke antarmuka IXpsPrintJobStream yang digunakan oleh pemanggil untuk menulis tiket cetak tingkat pekerjaan yang akan dikaitkan dengan pekerjaan ini. Jika parameter ini diatur ke NULL, tiket cetak (jika ada) dari dokumen XPS yang ditulis ke documentStream akan digunakan.

Nilai kembali

Metode mengembalikan HRESULT. Nilai yang mungkin termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut.

Menampilkan kode	Deskripsi
S_OK	Metode berhasil.
E_POINTER	printerName atau documentStream adalah NULL.
E_OUTOFMEMORY	Memori tidak cukup untuk membuat objek IXpsPrintJob baru.

Keterangan

StartXpsPrintJob adalah fungsi asinkron, yang dapat kembali sebelum penampung cetak membuat atau memulai pekerjaan cetak.

Antarmuka yang dikembalikan dalam xpsPrintJob, documentStream, dan printTicketStream tidak boleh digunakan sampai StartXpsPrintJob berhasil dikembalikan.

Setelah pemanggil mulai mengirim data, pemanggil harus memantau peristiwa kemajuan yang disinyalir ke peristiwa yang diteruskan dalam progressEvent. Ketika peristiwa disinyalkan, pemanggil harus memanggil IXpsPrintJob::GetJobStatus untuk mendapatkan status pekerjaan cetak saat ini.

Ketika pekerjaan cetak selesai, baik berhasil atau tidak, peristiwa yang diteruskan dalam completionEvent diberi sinyal sekali dan hanya sekali. Untuk mencegah kehilangan data, pemanggil harus memantau peristiwa ini dan utas atau aplikasi pemanggil tidak boleh dihentikan sampai peristiwa telah disinyalir.

Status pekerjaan tidak disimpan atau diantrekan oleh penampung cetak. Karena pemrosesan pekerjaan tidak menunggu status dibaca setelah peristiwa disinyalir, pemanggil mungkin melewatkan beberapa perubahan status, tergantung pada penundaan antara waktu aplikasi menerima pemberitahuan perubahan dan waktu yang disebut IXpsPrintJob::GetJobStatus. Untuk menerima pemberitahuan berikutnya, aplikasi harus mengatur ulang peristiwa kemajuan setelah menerima pemberitahuan.

Jika panggilan ke StartXpsPrintJob gagal, status pekerjaan akan diperbarui, peristiwa penyelesaian dan kemajuan akan diberi sinyal, dan kode kesalahan akan dikembalikan. Untuk mendapatkan status pekerjaan cetak yang gagal, panggil IXpsPrintJob::GetJobStatus.

StartXpsPrintJob memanggil DuplicateHandle pada completionEvent dan progressEvent untuk memastikan bahwa mereka tetap valid selama masa pakai pekerjaan. Karena penampung cetak menggunakan handel duplikat untuk peristiwa, pemanggil dapat menutup handel ini kapan saja tanpa memengaruhi eksekusi pekerjaan. Namun, prosedur yang direkomendasikan adalah agar penelepon menutup handel ini hanya setelah peristiwa completionEvent diberi sinyal dan diamati oleh pemanggil.

Antarmuka IXpsPrintJobStream yang dikembalikan dalam documentStream dan printTicketStream adalah aliran tulis-saja yang tidak mengizinkan pencarian tetapi dapat ditutup. Pemanggil menulis dokumen XPS dan mencetak konten tiket ke aliran ini, lalu memanggil Tutup setelah semua data ditulis. Panggilan ke metode Tulis aliran aman untuk utas; namun, jika panggilan tersebut dilakukan dari utas yang berbeda, mereka tidak dijamin akan berkomitmen pada aliran dalam urutan yang diharapkan.

Catatan Saat mencetak ke file, aplikasi bertanggung jawab untuk memberikan nilai yang akan diteruskan dalam parameter outputFileName untuk operasi cetak-ke-file. Untuk mencetak ke printer yang menggunakan pengandar yang keluaran ke port FILE: , pemanggil harus mengambil nama file dari pengguna dengan menampilkan dialog file umum.

Persyaratan


Klien minimum yang didukung	Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	xpsprint.h
Pustaka	XpsPrint.lib
DLL	XpsPrint.dll

Lihat juga

Dokumen

StartXpsPrintJob1

Spesifikasi Kertas XML

Bagikan melalui