Fungsi OpenPrinter2

Artikel
06/13/2023

Mengambil handel ke pencetak yang ditentukan, server cetak, atau tipe handel lain dalam subsistem cetak, sambil mengatur beberapa opsi printer.

Sintaks

BOOL OpenPrinter2(
  _In_  LPCTSTR            pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault,
  _In_  PPRINTER_OPTIONS   pOptions
);

Parameter

pPrinterName [in]

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

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

Windows Vista: Jika NULL, ini menunjukkan server cetak lokal.

phPrinter [out]

Penunjuk ke variabel yang menerima handel ke printer yang terbuka atau objek server cetak.

pDefault [in]

Penunjuk ke struktur PRINTER_DEFAULTS . Nilai ini bisa NULL.

pOptions [in]

Penunjuk ke struktur PRINTER_OPTIONS . Nilai ini bisa NULL.

Menampilkan nilai

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

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Jangan panggil metode ini di DllMain.

Catatan

Ini adalah fungsi pemblokiran atau sinkron dan mungkin tidak segera dikembalikan. 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 dengan antarmuka pengguna dapat membuat aplikasi tampak tidak responsif.

Versi ANSI dari fungsi ini tidak diimplementasikan dan mengembalikan ERROR_NOT_SUPPORTED.

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.

Anda dapat memanggil fungsi OpenPrinter2 untuk membuka handel ke server cetak atau untuk menentukan hak akses klien ke server cetak. Untuk melakukan ini, 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 diperlukan. Hak akses dapat menjadi salah satu dari berikut ini.

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 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 OpenPrinter2 akan gagal, dan GetLastError akan mengembalikan nilai ERROR_ACCESS_DENIED.

Ketika pPrinterName adalah printer lokal, maka OpenPrinter2 mengabaikan semua nilai dwFlags yang ditujukan struktur PRINTER_OPTIONS menggunakan pOptions, kecuali PRINTER_OPTION_CLIENT_CHANGE. Jika yang terakhir diteruskan, Maka OpenPrinter2 akan mengembalikan ERROR_ACCESS_DENIED. Oleh karena itu, saat membuka printer lokal, OpenPrinter2 tidak memberikan keuntungan dibandingkan OpenPrinter.

Windows Vista: Data printer yang dikembalikan oleh OpenPrinter2 diambil dari cache lokal kecuali bendera PRINTER_OPTION_NO_CACHE diatur di bidang dwFlags dari struktur PRINTER_OPTIONS yang direferensikan oleh pOptions.

Contoh

Dalam contoh ini, OpenPrinter2 gagal ketika PRINTER_ACCESS_MANAGE_LIMITED diteruskan ke struktur PRINTER_DEFAULTS , dan pengguna tidak memiliki izin yang sesuai.

// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;

// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
                     &printer,                  // Printer handle
                     &defaults,                 // Printer defaults
                     nullptr));                 // Printer options

assert(GetLastError() == ERROR_ACCESS_DENIED);

if (printer)
{
    ClosePrinter(printer);
}

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

Persyaratan

Persyaratan	Nilai
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)
Pustaka	Winspool.lib
DLL	Spoolss.dll
Nama Unicode dan ANSI	OpenPrinter2W (Unicode) dan OpenPrinter2A (ANSI)

Lihat juga

Pencetakan
Cetak Fungsi API Spooler
ClosePrinter
PRINTER_DEFAULTS
PRINTER_OPTIONS
SetJob
SetPrinter
StartDocPrinter
OpenPrinter

Bagikan melalui