Fungsi DocumentProperties

Artikel
06/12/2023

Fungsi DocumentProperties mengambil atau memodifikasi informasi inisialisasi printer atau menampilkan lembar properti konfigurasi printer untuk printer yang ditentukan.

Sintaks

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

Parameter

hWnd [in]

Handel ke jendela induk lembar properti konfigurasi printer.

hPrinter [in]

Handel ke objek printer. Gunakan fungsi OpenPrinter atau AddPrinter untuk mengambil handel printer.

pDeviceName [in]

Penunjuk ke string yang dihentikan null yang menentukan nama perangkat tempat lembar properti konfigurasi printer ditampilkan.

pDevModeOutput [out]

Penunjuk ke struktur DEVMODE yang menerima data konfigurasi printer yang ditentukan oleh pengguna.

pDevModeInput [in]

Penunjuk ke struktur DEVMODE yang digunakan sistem operasi untuk menginisialisasi kontrol lembar properti.

Parameter ini hanya digunakan jika bendera DM_IN_BUFFER diatur dalam parameter fMode . Jika DM_IN_BUFFER tidak diatur, sistem operasi menggunakan DEVMODE default printer.

fMode [in]

Operasi yang dilakukan fungsi. Jika parameter ini nol, fungsi DocumentProperties mengembalikan jumlah byte yang diperlukan oleh struktur data DEVMODE driver printer. Jika tidak, gunakan satu atau beberapa konstanta berikut untuk membangun nilai untuk parameter ini; namun, perhatikan bahwa untuk mengubah pengaturan cetak, aplikasi harus menentukan setidaknya satu nilai input dan satu nilai output.

Nilai	Makna
DM_IN_BUFFER	Nilai input. Sebelum meminta, menyalin, atau memperbarui, fungsi menggabungkan pengaturan cetak driver printer saat ini dengan pengaturan dalam struktur DEVMODE yang ditentukan oleh parameter pDevModeInput . Fungsi ini memperbarui struktur hanya untuk anggota yang ditentukan oleh anggota dmFields struktur DEVMODE. Nilai ini juga didefinisikan sebagai DM_MODIFY. Dalam kasus konflik selama penggabungan, pengaturan dalam struktur DEVMODE yang ditentukan oleh pDevModeInput mengambil alih pengaturan cetak driver printer saat ini.
DM_IN_PROMPT	Nilai input. Fungsi ini menyajikan lembar properti Penyetelan Cetak driver printer lalu mengubah pengaturan dalam struktur data DEVMODE printer ke nilai yang ditentukan oleh pengguna. Nilai ini juga didefinisikan sebagai DM_PROMPT.
DM_OUT_BUFFER	Nilai output. Fungsi ini menulis pengaturan cetak driver printer saat ini, termasuk data privat, ke struktur data DEVMODE yang ditentukan oleh parameter pDevModeOutput . Pemanggil harus mengalokasikan buffer yang cukup besar untuk berisi informasi. Jika kumpulan bit DM_OUT_BUFFER jelas, parameter pDevModeOutput bisa NULL. Nilai ini juga didefinisikan sebagai DM_COPY.

Nilai kembali

Jika parameter fMode adalah nol, nilai yang dikembalikan adalah ukuran buffer yang diperlukan untuk memuat data inisialisasi driver printer. Perhatikan bahwa buffer ini dapat lebih besar dari struktur DEVMODE jika driver printer menambahkan data privat ke struktur.

Jika fungsi menampilkan lembar properti, nilai yang dikembalikan adalah IDOK atau IDCANCEL, tergantung pada tombol mana yang dipilih pengguna.

Jika fungsi tidak menampilkan lembar properti dan berhasil, nilai yang dikembalikan adalah IDOK.

Jika fungsi gagal, nilai yang dikembalikan kurang dari nol.

Keterangan

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.

String yang ditujukkan oleh parameter pDeviceName dapat diperoleh dengan memanggil fungsi GetPrinter .

Struktur DEVMODE yang benar-benar digunakan oleh driver printer berisi bagian independen perangkat (seperti yang didefinisikan di atas) diikuti oleh bagian khusus driver yang bervariasi dalam ukuran dan konten dengan setiap driver dan versi driver. Karena ketergantungan driver ini, sangat penting bagi aplikasi untuk mengkueri driver untuk ukuran struktur DEVMODE yang benar sebelum mengalokasikan buffer untuk itu.

Untuk membuat perubahan pada pengaturan cetak yang lokal untuk aplikasi, aplikasi harus mengikuti langkah-langkah berikut:

Dapatkan jumlah byte yang diperlukan untuk struktur DEVMODE lengkap dengan memanggil DocumentProperties dan menentukan nol dalam parameter fMode .
Alokasikan memori untuk struktur DEVMODE penuh.
Dapatkan pengaturan printer saat ini dengan memanggil DocumentProperties. Teruskan penunjuk ke struktur DEVMODE yang dialokasikan di Langkah 2 sebagai parameter pDevModeOutput dan tentukan nilai DM_OUT_BUFFER .
Ubah anggota yang sesuai dari struktur DEVMODE yang dikembalikan dan tunjukkan anggota mana yang diubah dengan mengatur bit yang sesuai di anggota dmFieldsdari DEVMODE.
Panggil DocumentProperties dan teruskan kembali struktur DEVMODE yang dimodifikasi sebagai parameter pDevModeInput dan pDevModeOutput dan tentukan nilai DM_IN_BUFFER dan DM_OUT_BUFFER (yang digabungkan menggunakan operator OR). Struktur DEVMODE yang dikembalikan oleh panggilan ketiga ke DocumentProperties dapat digunakan sebagai argumen dalam panggilan ke fungsi CreateDC .

Untuk membuat handel ke konteks perangkat printer menggunakan pengaturan printer saat ini, Anda hanya perlu memanggil DocumentProperties dua kali, seperti yang dijelaskan di atas. Panggilan pertama mendapatkan ukuran DEVMODE penuh dan panggilan kedua menginisialisasi DEVMODE dengan pengaturan printer saat ini. Teruskan DEVMODE yang diinisialisasi ke CreateDC untuk mendapatkan handel ke konteks perangkat printer.

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	DocumentPropertiesW (Unicode) dan DocumentPropertiesA (ANSI)

Lihat juga

Pencetakan
Cetak Fungsi API Spooler
AdvancedDocumentProperties
CreateDC
DEVMODE
GetPrinter
OpenPrinter