Fungsi StartXpsPrintJob1 (xpsprint.h)
[StartXpsPrintJob1 tidak didukung dan dapat diubah atau tidak tersedia di masa mendatang. ]
Membuat tugas cetak untuk mengirim isi dokumen XPS ke printer. Fungsi ini menciptakan jalur cetak yang lebih efisien daripada StartXpsPrintJob.
Sintaks
HRESULT StartXpsPrintJob1(
[in] LPCWSTR printerName,
[in, optional] LPCWSTR jobName,
[in, optional] LPCWSTR outputFileName,
[in, optional] HANDLE progressEvent,
[in, optional] HANDLE completionEvent,
[out, optional] IXpsPrintJob **xpsPrintJob,
[out] IXpsOMPackageTarget **printContentReceiver
);
Parameter
[in] printerName
Nama pencetak yang akan dikaitkan dengan pekerjaan ini.
[in, optional] jobName
Nama pekerjaan yang ditentukan pengguna yang akan dikaitkan dengan pekerjaan ini. Anda dapat mengatur parameter ini ke NULL jika pekerjaan tidak memerlukan nama terpisah yang ditentukan pengguna.
[in, optional] outputFileName
Nama 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, Anda harus mengatur parameter ini ke NULL.
[in, optional] progressEvent
Handel kejadian yang disinyalkan ketika salah satu perubahan pekerjaan cetak berikut ini terjadi:
- ID pekerjaan ditetapkan ke tugas cetak
- Pencetakan halaman telah selesai
- Pencetakan dokumen telah selesai
- Tugas cetak telah dibatalkan atau telah berakhir karena kesalahan
XPS Print API tidak mengatur ulang peristiwa ini—itulah tanggung jawab pemanggil.
Atur parameter ini ke NULL jika Anda tidak ingin diberi tahu tentang kemajuan.
[in, optional] completionEvent
Handel kejadian yang disinyalkan ketika pekerjaan cetak selesai. Kejadian ini dijamin akan disinyalkan tepat sekali per panggilan StartXpsPrintJob1 . XPS Print API tidak mengatur ulang peristiwa ini—itulah tanggung jawab pemanggil.
Atur parameter ini ke NULL jika tidak ingin diberi tahu tentang penyelesaian.
[out, optional] xpsPrintJob
Penunjuk ke antarmuka IXpsPrintJob yang mewakili pekerjaan cetak yang dibuat StartXpsPrintJob1 . Untuk mendapatkan status pekerjaan cetak atau membatalkannya, gunakan antarmuka IXpsPrintJob . Atur parameter ini ke NULL jika Anda tidak membutuhkannya.
[out] printContentReceiver
Penunjuk ke antarmuka IXpsOMPackageTarget yang dibuat fungsi ini. Parameter ini diperlukan dan Anda tidak dapat mengaturnya ke NULL.
Untuk mengirim konten dokumen ke pekerjaan cetak yang dibuat fungsi ini, gunakan antarmuka IXpsOMPackageWriter yang Anda buat dengan memanggil metode CreateXpsOMPackageWriter antarmuka IXpsOMPackageTarget yang dikembalikan dalam xpsOMPackageTarget.
Mengembalikan nilai
Metode mengembalikan HRESULT. Nilai yang mungkin termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Metode berhasil. |
|
printerName atau xpsOMPackageTarget adalah NULL. |
|
Tidak cukup memori untuk membuat objek IXpsPrintJob baru. |
Keterangan
StartXpsPrintJob1 adalah fungsi asinkron, dan oleh karena itu dapat kembali sebelum penampung cetak membuat atau memulai pekerjaan cetak.
Jangan gunakan antarmuka yang dikembalikan di xpsPrintJob dan xpsOMPackageTarget hingga StartXpsPrintJob1 berhasil dikembalikan.
Setelah penelepon mulai mengirim data, ini adalah praktik pemrograman yang baik untuk memantau peristiwa kemajuan yang disinyalkan 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 hanya disinyalkan sekali. Untuk mencegah kehilangan data, ini adalah praktik pemrograman yang baik bagi pemanggil untuk memantau peristiwa penyelesaian dan memastikan bahwa utas maupun aplikasi yang membuat pekerjaan cetak dihentikan sampai peristiwa penyelesaian telah disinyalkan.
Status pekerjaan tidak disimpan atau diantrekan oleh penampung cetak. Karena pemrosesan pekerjaan tidak menunggu status dibaca setelah peristiwa disinyalkan, 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 StartXpsPrintJob1 gagal, penampung cetak memperbarui status pekerjaan, memberi sinyal peristiwa penyelesaian dan kemajuan, dan mengembalikan kode kesalahan. Untuk mendapatkan status pekerjaan cetak yang gagal, panggil IXpsPrintJob::GetJobStatus.
StartXpsPrintJob1 memanggil DuplicateHandle on 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, kami sarankan pemanggil untuk menutup handel ini hanya setelah peristiwa completionEvent diberi sinyal dan pemanggil mengamatinya.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 7 dengan SP1, Windows Vista, dan Suplemen Pembaruan Platform untuk Windows Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 R2 dengan Sp1, Windows Server 2008, dan Tambahan Pembaruan Platform untuk Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | xpsprint.h |
| Pustaka | XpsPrint.lib |
| DLL | XpsPrint.dll |