Fungsi SetPrinter
Fungsi SetPrinter mengatur data untuk printer tertentu atau mengatur status printer yang ditentukan dengan menjeda pencetakan, melanjutkan pencetakan, atau menghapus semua pekerjaan cetak.
Sintaks
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
Parameter
-
hPrinter [in]
-
Handel ke pencetak. Gunakan fungsi OpenPrinter, OpenPrinter2, atau AddPrinter untuk mengambil handel printer.
-
Level [in]
-
Jenis data yang disimpan fungsi ke dalam buffer yang ditujukkan oleh pPrinter. Jika parameter Perintah tidak sama dengan nol, parameter Level harus nol.
Nilai ini bisa 0, 2, 3, 4, 5, 6, 7, 8, atau 9.
-
pPrinter [in]
-
Penunjuk ke buffer yang berisi data yang akan diatur untuk printer, atau berisi informasi untuk perintah yang ditentukan oleh parameter Perintah . Jenis data dalam buffer ditentukan oleh nilai Level.
Tingkat Struktur - 0
Jika parameter PerintahPRINTER_CONTROL_SET_STATUS, pPrinter harus berisi nilai DWORD yang menentukan status printer baru untuk diatur. Untuk daftar nilai status yang mungkin, lihat Anggota status struktur PRINTER_INFO_2 . Perhatikan bahwa PRINTER_STATUS_PAUSED dan PRINTER_STATUS_PENDING_DELETION bukan nilai status yang valid untuk ditetapkan.
Jika Level adalah 0, tetapi parameter Command tidak PRINTER_CONTROL_SET_STATUS, pPrinter harus NULL.- 2
Struktur PRINTER_INFO_2 yang berisi informasi terperinci tentang printer. - 3
Struktur PRINTER_INFO_3 yang berisi informasi keamanan printer. - 4
Struktur PRINTER_INFO_4 yang berisi informasi printer minimal, termasuk nama printer, nama server, dan apakah printer bersifat jarak jauh atau lokal. - 5
Struktur PRINTER_INFO_5 yang berisi informasi printer seperti atribut printer dan pengaturan waktu habis. - 6
Struktur PRINTER_INFO_6 yang menentukan nilai status printer. - 7
Struktur PRINTER_INFO_7 . Anggota dwAction dari struktur ini menunjukkan apakah SetPrinter harus menerbitkan, membatalkan penerbitan, menerbitkan ulang, atau memperbarui data printer di layanan direktori. - 8
Struktur PRINTER_INFO_8 yang menentukan pengaturan printer default global. - 9
Struktur PRINTER_INFO_9 yang menentukan pengaturan printer default per pengguna. -
Command [in]
-
Tindakan yang harus dilakukan.
Jika parameter Level bukan nol, atur nilai parameter ini ke nol. Dalam hal ini, printer mempertahankan statusnya saat ini dan fungsi mengonfigurasi ulang data printer seperti yang ditentukan oleh parameter Level dan pPrinter .
Jika parameter Level adalah nol, atur nilai parameter ini ke salah satu nilai berikut.
Nilai Makna - PRINTER_CONTROL_PAUSE
Jeda pencetak. - PRINTER_CONTROL_PURGE
Hapus semua tugas cetak pada pencetak. - PRINTER_CONTROL_RESUME
Lanjutkan pencetak yang dijeda. - PRINTER_CONTROL_SET_STATUS
Atur status pencetak.
Atur parameter pPrinter ke penunjuk ke nilai DWORD yang menentukan status printer baru.
Menampilkan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah nilai bukan nol.
Jika fungsi gagal, nilai yang dikembalikan adalah nol.
Jika Level adalah 7 dan tindakan penerbitan gagal, SetPrinter mengembalikan ERROR_IO_PENDING dan mencoba menyelesaikan tindakan di latar belakang. Jika Level adalah 7 dan tindakan pembaruan gagal, SetPrinter mengembalikan ERROR_FILE_NOT_FOUND.
Keterangan
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.
Anda tidak dapat menggunakan SetPrinter untuk mengubah printer default.
Untuk mengubah pengaturan printer saat ini, panggil fungsi GetPrinter untuk mengambil pengaturan saat ini ke dalam struktur PRINTER_INFO_2 , ubah anggota struktur tersebut seperlunya, lalu panggil SetPrinter.
Fungsi SetPrinter mengabaikan anggota pServerName, AveragePPM, Status, dan cJobs dari struktur PRINTER_INFO_2 .
Menjeda pencetak menangguhkan penjadwalan semua tugas cetak untuk printer tersebut, kecuali untuk satu tugas cetak yang mungkin sedang dicetak. Tugas cetak dapat dikirimkan ke pencetak yang dijeda, tetapi tidak ada tugas yang akan dijadwalkan untuk mencetak pada pencetak tersebut hingga pencetakan dilanjutkan. Jika pencetak dibersihkan, semua tugas cetak untuk printer tersebut dihapus, kecuali untuk tugas cetak saat ini.
Jika Anda menggunakan SetPrinter untuk mengubah struktur DEVMODE default untuk printer (secara global mengatur default printer), Anda harus terlebih dahulu memanggil fungsi DocumentProperties untuk memvalidasi struktur DEVMODE .
Untuk struktur PRINTER_INFO_2 dan PRINTER_INFO_3 yang berisi penunjuk ke deskriptor keamanan, fungsi hanya dapat mengatur komponen pendeskripsi keamanan yang memiliki izin untuk diubah oleh penelepon. Untuk mengatur komponen deskriptor keamanan tertentu, Anda harus menentukan hak akses yang diperlukan saat Anda memanggil fungsi OpenPrinter atau OpenPrinter2 untuk mengambil handel ke printer. Tabel berikut ini memperlihatkan hak akses yang diperlukan untuk mengubah berbagai komponen pendeskripsi keamanan.
| Izin akses | Komponen deskriptor keamanan |
|---|---|
| WRITE_OWNER | Pemilik Grup utama |
| WRITE_DAC | Daftar kontrol akses diskresi (DACL) |
| ACCESS_SYSTEM_SECURITY | Daftar kontrol akses sistem (SACL) |
Jika deskriptor keamanan berisi komponen yang tidak memiliki hak akses untuk diubah oleh pemanggil, SetPrinter gagal. Komponen pendeskripsi keamanan yang tidak ingin Anda ubah harus NULL atau tidak ada, sebagaimana mestinya. Jika Anda tidak ingin mengubah deskriptor keamanan, dan memanggil SetPrinter dengan struktur PRINTER_INFO_2 , atur anggota pSecurityDescriptor dari struktur tersebut ke NULL.
Firewall Koneksi Internet (ICF) memblokir port printer secara default, tetapi pengecualian untuk Berbagi File dan Cetak dapat diaktifkan. Jika SetPrinter dipanggil oleh admin komputer, setPrinter akan mengaktifkan pengecualian. Jika dipanggil oleh non-admin dan pengecualian belum diaktifkan, panggilan gagal.
Anda dapat menggunakan tingkat 7 dengan struktur PRINTER_INFO_7 untuk menerbitkan, membatalkan penerbitan, atau memperbarui data layanan direktori untuk printer. Data layanan direktori untuk printer mencakup semua data yang disimpan di bawah kunci SPLDS_* dengan panggilan ke fungsi SetPrinterDataEx untuk printer. Sebelum memanggil SetPrinter, atur anggota PRINTER_INFO_7 pszObjectGUID ke NULL dan atur anggota dwAction ke salah satu nilai berikut.
| Nilai | Deskripsi |
|---|---|
|
DSPRINT_PUBLISH |
Menerbitkan data layanan direktori. |
|
DSPRINT_REPUBLISH |
Data layanan direktori untuk printer tidak diterbitkan dan kemudian diterbitkan lagi, menyegarkan semua properti dalam printer yang diterbitkan. Menerbitkan ulang juga mengubah GUID printer yang diterbitkan. Gunakan nilai ini jika Anda menduga data printer yang diterbitkan telah rusak. |
|
DSPRINT_UNPUBLISH |
Membatalkan penerbitan data layanan direktori. |
|
DSPRINT_UPDATE |
Updates data layanan direktori. Ini sama dengan DSPRINT_PUBLISH, kecuali bahwa SetPrinter gagal dengan ERROR_FILE_NOT_FOUND jika printer belum diterbitkan. Gunakan DSPRINT_UPDATE untuk memperbarui properti yang diterbitkan tetapi tidak memaksa penerbitan. Pengandar pencetak harus selalu menggunakan DSPRINT_UPDATE daripada DSPRINT_PUBLISH. |
DSPRINT_PENDING bukan nilai dwAction yang valid untuk SetPrinter.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung |
Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung |
Windows 2000 Server [hanya aplikasi desktop] |
| Header |
|
| Pustaka |
|
| DLL |
|
| Nama Unicode dan ANSI |
SetPrinterW (Unicode) dan SetPrinterA (ANSI) |