Fungsi OpenPrinter

Fungsi OpenPrinter mengambil handel ke printer yang ditentukan atau server cetak atau jenis handel lain dalam subsistem cetak.

Sintaks

BOOL OpenPrinter(
  _In_  LPTSTR             pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault
);

Parameter

pPrinterName [in]

Penunjuk ke string yang dihentikan null yang menentukan nama printer atau server cetak, objek printer, XcvMonitor, atau XcvPort.

Untuk penggunaan objek printer: PrinterName, Job xxxx. Untuk XcvMonitor, gunakan: ServerName, XcvMonitor MonitorName. Untuk XcvPort, gunakan: ServerName, XcvPort PortName.

Jika NULL, ini menunjukkan server printer lokal.

phPrinter [out]

Penunjuk ke variabel yang menerima handel (bukan utas aman) ke printer yang terbuka atau objek server cetak.

Parameter phPrinter dapat mengembalikan handel Xcv untuk digunakan dengan fungsi XcvData. Untuk informasi selengkapnya tentang XcvData, lihat DDK.

pDefault [in]

Penunjuk ke struktur PRINTER_DEFAULTS . Nilai ini bisa NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah nilai bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol.

Keterangan

Jangan panggil metode ini di DllMain.

Catatan

Handel yang diperoleh untuk printer jarak jauh dengan panggilan ke OpenPrinter untuk printer jarak jauh mengakses printer melalui cache lokal di layanan penampung cetak. Cache ini tidak akurat secara real time. Untuk mendapatkan data yang akurat, ganti panggilan OpenPrinter dengan OpenPrinter2 dengan pOptions.dwFlags diatur ke PRINTER_OPTION_NO_CACHE. Perhatikan bahwa hanya OpenPrinter2W yang berfungsi. Fungsi ini mengembalikan handel printer yang menggunakan panggilan Printing API lainnya dan melewati cache lokal. Metode ini memblokir saat menunggu komunikasi jaringan dengan printer jarak jauh, sehingga mungkin tidak segera kembali. Seberapa cepat fungsi ini kembali tergantung pada faktor run-time seperti status jaringan, konfigurasi server cetak, dan faktor implementasi driver printer yang sulit diprediksi saat menulis aplikasi. Memanggil fungsi ini dari utas yang mengelola interaksi antarmuka pengguna mungkin membuat aplikasi tampak tidak responsif.

Catatan

Handel yang diperoleh melalui panggilan ke OpenPrinter untuk printer jarak jauh akan mengakses printer melalui cache lokal di layanan penampung cetak. Cache ini, secara desain, tidak akurat secara real time. Jika Anda perlu mendapatkan data yang akurat, ganti panggilan OpenPrinter dengan OpenPrinter2 dengan pOptions.dwFlags diatur ke PRINTER_OPTION_NO_CACHE. Perhatikan bahwa hanya OpenPrinter2W yang berfungsi. Melakukannya, fungsi mengembalikan handel printer yang membuat panggilan API Pencetakan lainnya untuk melewati cache lokal. Perhatikan bahwa pendekatan ini akan memblokir saat menunggu komunikasi jaringan pulang-pergi ke printer jarak jauh, sehingga mungkin tidak segera kembali. Seberapa cepat fungsi ini kembali tergantung pada faktor run-time seperti status jaringan, konfigurasi server cetak, dan implementasi driver printer - faktor yang sulit diprediksi saat menulis aplikasi. Oleh karena itu memanggil fungsi ini dari utas yang mengelola interaksi dengan antarmuka pengguna dapat membuat aplikasi tampak tidak responsif.

Handel yang ditunjukkan oleh phPrinter tidak aman untuk utas. Jika penelepon perlu menggunakannya secara bersamaan pada beberapa utas, mereka harus menyediakan akses sinkronisasi kustom ke handel printer menggunakan Fungsi Sinkronisasi. Untuk menghindari penulisan kode kustom, aplikasi dapat membuka handel printer pada setiap utas, sesuai kebutuhan.

Parameter pDefault memungkinkan Anda menentukan nilai jenis data dan mode perangkat yang digunakan untuk mencetak dokumen yang dikirimkan oleh fungsi StartDocPrinter . Namun, Anda dapat mengganti nilai-nilai ini dengan menggunakan fungsi SetJob setelah dokumen dimulai.

Pengaturan DEVMODE yang ditentukan dalam struktur PRINTER_DEFAULTS parameter pDefault tidak digunakan ketika nilai anggota pDatatype dari struktur DOC_INFO_1 yang diteruskan dalam parameter pDocInfo dari panggilan StartDocPrinter adalah "RAW". Ketika dokumen tingkat tinggi (seperti file Adobe PDF atau Microsoft Word) atau data printer lainnya (PCL, PS, atau HPGL) dikirim langsung ke printer dengan pDatatype yang diatur ke "RAW", dokumen harus sepenuhnya menjelaskan pengaturan pekerjaan cetak bergaya DEVMODE dalam bahasa yang dipahami oleh perangkat keras.

Anda dapat memanggil fungsi OpenPrinter untuk membuka handel ke server cetak atau untuk menentukan hak akses yang dimiliki klien ke server cetak. Untuk melakukannya, tentukan nama server cetak dalam parameter pPrinterName , atur anggota pDatatype dan pDevMode dari struktur PRINTER_DEFAULTS ke NULL, dan atur anggota DesiredAccess untuk menentukan nilai masker akses server seperti SERVER_ALL_ACCESS. Setelah selesai dengan handel, teruskan ke fungsi ClosePrinter untuk menutupnya.

Gunakan anggota DesiredAccess dari struktur PRINTER_DEFAULTS untuk menentukan hak akses yang Anda butuhkan ke printer. Hak akses dapat menjadi salah satu dari berikut ini. (Jika pDefaultadalah NULL, maka hak akses PRINTER_ACCESS_USE.)

Nilai Akses yang Diinginkan	Makna
PRINTER_ACCESS_ADMINISTER	Untuk melakukan tugas administratif, seperti yang disediakan oleh SetPrinter.
PRINTER_ACCESS_USE	Untuk melakukan operasi pencetakan dasar.
PRINTER_ALL_ACCESS	Untuk melakukan semua tugas administratif dan operasi pencetakan dasar kecuali untuk SYNCHRONIZE (lihat Hak Akses Standar.
PRINTER_ACCESS_MANAGE_LIMITED	Untuk melakukan tugas administratif, seperti yang disediakan oleh SetPrinter dan SetPrinterData. Nilai ini tersedia mulai dari Windows 8.1.
nilai keamanan generik, seperti WRITE_DAC	Untuk mengizinkan hak akses kontrol tertentu. Lihat Hak Akses Standar.

Jika pengguna tidak memiliki izin untuk membuka printer atau server cetak tertentu dengan akses yang diinginkan, panggilan OpenPrinter akan gagal dengan nilai yang dikembalikan nol dan GetLastError akan mengembalikan nilai ERROR_ACCESS_DENIED.

Contoh

Untuk program sampel yang menggunakan fungsi ini, lihat Cara: Mencetak Menggunakan GDI Print API.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Header	Winspool.h (termasuk Windows.h)
Pustaka	Winspool.lib
DLL	Winspool.drv
Nama Unicode dan ANSI	OpenPrinterW (Unicode) dan OpenPrinterA (ANSI)

Lihat juga

Pencetakan

Cetak Fungsi API Spooler

WritePrinter

ClosePrinter

PRINTER_DEFAULTS

SetJob

SetPrinter

StartDocPrinter