Fungsi EnumPrinters

Artikel
06/13/2023

Fungsi EnumPrinters menghitung printer, server cetak, domain, atau penyedia cetak yang tersedia.

Sintaks

BOOL EnumPrinters(
  _In_  DWORD   Flags,
  _In_  LPTSTR  Name,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinterEnum,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded,
  _Out_ LPDWORD pcReturned
);

Parameter

Bendera [in]

Jenis objek cetak yang harus dijumlahkan fungsi. Nilai ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
PRINTER_ENUM_LOCAL	Jika bendera PRINTER_ENUM_NAME juga tidak diteruskan, fungsi mengabaikan parameter Nama , dan menghitung printer yang diinstal secara lokal. Jika PRINTER_ENUM_NAME juga diteruskan, fungsi menghitung printer lokal pada Nama.
PRINTER_ENUM_NAME	Fungsi menghitung printer yang diidentifikasi oleh Nama. Ini bisa berupa server, domain, atau penyedia cetak. Jika NamaNULL, fungsi menghitung penyedia cetak yang tersedia.
PRINTER_ENUM_SHARED	Fungsi ini menghitung printer yang memiliki atribut bersama. Tidak dapat digunakan dalam isolasi; gunakan operasi OR untuk menggabungkan dengan jenis PRINTER_ENUM lain.
PRINTER_ENUM_CONNECTIONS	Fungsi menghitung daftar printer tempat pengguna membuat koneksi sebelumnya.
PRINTER_ENUM_NETWORK	Fungsi ini menghitung printer jaringan di domain komputer. Nilai ini hanya valid jika Tingkat adalah 1.
PRINTER_ENUM_REMOTE	Fungsi ini menghitung printer jaringan dan server cetak di domain komputer. Nilai ini hanya valid jika Tingkat adalah 1.
PRINTER_ENUM_CATEGORY_3D	Fungsi ini hanya menghitung printer 3D.
PRINTER_ENUM_CATEGORY_ALL	Fungsi ini menghitung semua perangkat cetak, termasuk printer 3D.

Jika Level adalah 4, Anda hanya dapat menggunakan konstanta PRINTER_ENUM_CONNECTIONS dan PRINTER_ENUM_LOCAL.

Catatan

Perangkat cetak 3D tidak dijumlahkan secara default. Anda harus menyertakan PRINTER_ENUM_CATEGORY_3D dan PRINTER_ENUM_LOCAL untuk menghitung printer 3D saja. Untuk menyertakan printer 3D, bersama dengan semua printer lokal lainnya, gunakan PRINTER_ENUM_CATEGORY_ALL dan PRINTER_ENUM_LOCAL.

Nama [in]

Jika Tingkat adalah 1, Bendera berisi PRINTER_ENUM_NAME, dan Nama bukan NULL, maka Nama adalah penunjuk ke string yang dihentikan null yang menentukan nama objek yang akan dihitung. String ini bisa menjadi nama server, domain, atau penyedia cetak.

Jika Tingkat adalah 1, Bendera berisi PRINTER_ENUM_NAME, dan Nama adalah NULL, maka fungsi menghitung penyedia cetak yang tersedia.

Jika Tingkat adalah 1, Bendera berisi PRINTER_ENUM_REMOTE, dan Nama ADALAH NULL, maka fungsi menghitung printer di domain pengguna.

Jika Level adalah 2 atau 5,Name adalah penunjuk ke string yang dihentikan null yang menentukan nama server yang printernya akan dijumlahkan. Jika string ini NULL, maka fungsi menghitung printer yang diinstal pada komputer lokal.

Jika Tingkat adalah 4, Nama harus NULL. Fungsi selalu mengkueri di komputer lokal.

Saat NamaNULL, atur Bendera ke PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS menghitung printer yang diinstal pada komputer lokal. Printer ini mencakup printer yang terpasang secara fisik ke komputer lokal serta printer jarak jauh yang memiliki koneksi jaringan.

Jika Nama bukan NULL, atur Bendera ke PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME menghitung printer lokal yang diinstal pada Nama server.

Level [in]

Jenis struktur data yang diacu oleh pPrinterEnum. Nilai yang valid adalah 1, 2, 4, dan 5, yang sesuai dengan struktur data PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4, dan PRINTER_INFO_5 .

Nilai ini bisa 1, 2, 4, atau 5.

pPrinterEnum [out]

Penunjuk ke buffer yang menerima array struktur PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, atau PRINTER_INFO_5 . Setiap struktur berisi data yang menjelaskan objek cetak yang tersedia.

Jika Level adalah 1, array berisi struktur PRINTER_INFO_1 . Jika Level adalah 2, array berisi struktur PRINTER_INFO_2 . Jika Level adalah 4, array berisi struktur PRINTER_INFO_4 . Jika Level adalah 5, array berisi struktur PRINTER_INFO_5 .

Buffer harus cukup besar untuk menerima array struktur data dan string apa pun atau data lain yang menjadi titik anggota struktur. Jika buffer terlalu kecil, parameter pcbNeeded mengembalikan ukuran buffer yang diperlukan.

cbBuf [in]

Ukuran, dalam byte, dari buffer yang ditujukkan oleh pPrinterEnum.

pcbNeeded [out]

Penunjuk ke nilai yang menerima jumlah byte yang disalin jika fungsi berhasil atau jumlah byte yang diperlukan jika cbBuf terlalu kecil.

pcReturned [out]

Penunjuk ke nilai yang menerima jumlah struktur PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4, atau PRINTER_INFO_5 yang dikembalikan fungsi dalam array tempat pPrinterEnum menunjuk.

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

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

Jika EnumPrinters mengembalikan struktur PRINTER_INFO_1 di mana PRINTER_ENUM_CONTAINER ditentukan, ini menunjukkan bahwa ada hierarki objek printer. Aplikasi dapat menghitung hierarki dengan memanggil EnumPrinters lagi, mengatur Nama ke nilai anggota pName struktur PRINTER_INFO_1.

Fungsi EnumPrinters tidak mengambil informasi keamanan. Jika struktur PRINTER_INFO_2 dikembalikan dalam array yang diarahkan oleh pPrinterEnum, anggota pSecurityDescriptor mereka akan diatur ke NULL.

Untuk mendapatkan informasi tentang printer default, panggil GetDefaultPrinter.

Struktur PRINTER_INFO_4 menyediakan cara yang mudah dan sangat cepat untuk mengambil nama printer yang diinstal pada komputer lokal, serta koneksi jarak jauh yang telah dibuat pengguna. Ketika EnumPrinters dipanggil dengan struktur data PRINTER_INFO_4 , fungsi tersebut meminta registri untuk informasi yang ditentukan, lalu segera kembali. Ini berbeda dari perilaku EnumPrinters ketika dipanggil dengan tingkat struktur data PRINTER_INFO_* lainnya. Secara khusus, ketika EnumPrinters dipanggil dengan struktur data tingkat 2 (PRINTER_INFO_2), EnumPrinter melakukan panggilan OpenPrinter pada setiap koneksi jarak jauh. Jika koneksi jarak jauh tidak berfungsi, atau server jarak jauh tidak ada lagi, atau printer jarak jauh tidak ada lagi, fungsi harus menunggu RPC kehabisan waktu dan akibatnya gagal dalam panggilan OpenPrinter . Ini bisa memakan waktu cukup lama. Melewati struktur PRINTER_INFO_4 memungkinkan aplikasi mengambil informasi minimum yang diperlukan; jika informasi lebih rinci diinginkan, panggilan EnumPrinters tingkat 2 berikutnya dapat dilakukan.

Windows Vista: Data printer yang dikembalikan oleh EnumPrinters diambil dari cache lokal ketika nilai Level adalah 4.

Tabel berikut menunjukkan output EnumPrinters untuk berbagai nilai Bendera saat parameter Tingkat diatur ke 1.

Di kolom Parameter nama tabel, Anda harus mengganti nama yang sesuai untuk Penyedia Cetak, Domain, dan Mesin. Misalnya, untuk "Penyedia Cetak", Anda dapat menggunakan nama penyedia cetak jaringan atau nama penyedia cetak lokal. Untuk mengambil nama penyedia cetak, panggil EnumPrinters dengan Nama diatur ke NULL.

Parameter bendera	Parameter nama	Hasil
PRINTER_ENUM_LOCAL (dan tidak PRINTER_ENUM_NAME)	Parameter Nama diabaikan.	Semua printer lokal.
PRINTER_ENUM_NAME	"Penyedia Cetak"	Semua nama domain
PRINTER_ENUM_NAME	"Penyedia Cetak! Domain"	Semua printer dan server cetak di domain komputer
PRINTER_ENUM_NAME	"Penyedia Cetak!! \\Machine"	Semua printer dibagikan di \\Machine
PRINTER_ENUM_NAME	String kosong, ""	Semua printer lokal.
PRINTER_ENUM_NAME	NULL	Semua penyedia cetak di domain komputer
PRINTER_ENUM_CONNECTIONS	Parameter Nama diabaikan.	Semua pencetak jarak jauh yang tersambung
PRINTER_ENUM_NETWORK	Parameter Nama diabaikan.	Semua printer di domain komputer
PRINTER_ENUM_REMOTE	String kosong, ""	Semua printer dan server cetak di domain komputer
PRINTER_ENUM_REMOTE	"Penyedia Cetak"	Sama seperti PRINTER_ENUM_NAME
PRINTER_ENUM_REMOTE	"Penyedia Cetak! Domain"	Semua printer dan server cetak di domain komputer, terlepas dari Domain yang ditentukan.
PRINTER_ENUM_CATEGORY_3D	Parameter Nama diabaikan.	Hanya printer 3D yang dijumlahkan.
PRINTER_ENUM_CATEGORY_ALL	Parameter Nama diabaikan.	Printer 3D dijumlahkan, bersama dengan semua printer lainnya.

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	EnumPrintersW (Unicode) dan EnumPrintersA (ANSI)

Lihat juga

Pencetakan
Cetak Fungsi API Spooler
TambahkanPrinter
DeletePrinter
GetPrinter
PRINTER_INFO_1
PRINTER_INFO_2
PRINTER_INFO_4
PRINTER_INFO_5
SetPrinter

Bagikan melalui