Fungsi DrvConvertDevMode (winddiui.h)

Fungsi DrvConvertDevMode antarmuka printer dll mengonversi struktur DEVMODEW printer dari satu versi ke versi lainnya.

Sintaks

BOOL DrvConvertDevMode(
  [in]      LPTSTR   pPrinterName,
  [in]      PDEVMODE pdmIn,
  [out]     PDEVMODE pdmOut,
  [in, out] PLONG    pcbNeeded,
  [in]      DWORD    fMode
);

Parameter

[in] pPrinterName

Penunjuk yang disediakan penelepon ke string nama printer. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut ini.

[in] pdmIn

Penunjuk yang disediakan penelepon ke struktur DEVMODEW input. Jika fMode CDM_DRIVER_DEFAULT, pointer ini adalah NULL.

[out] pdmOut

Penunjuk yang disediakan penelepon ke buffer untuk menerima struktur DEVMODEW output. Jika fMode CDM_CONVERT buffer berisi, pada input, struktur DEVMODEW yang valid menunjukkan versi driver target.

[in, out] pcbNeeded

Penunjuk yang disediakan penelepon ke ukuran, dalam byte, dari buffer yang diacu oleh pdmOut. Pada output, DLL antarmuka printer harus menimpa nilai ukuran yang diterima dengan ukuran aktual struktur DEVMODEW yang dikonversi. Jika buffer yang diterima terlalu kecil, DLL antarmuka printer harus menimpa nilai ukuran yang diterima dengan ukuran buffer yang diperlukan.

[in] fMode

Bendera bit yang disediakan penelepon menunjukkan jenis operasi yang akan dilakukan. Ini bisa menjadi salah satu bendera berikut:

CDM_CONVERT

Fungsi harus mengonversi konten struktur DEVMODEW input (ditujukkan oleh pdmIn) menjadi struktur DEVMODEW baru, dan menempatkan hasilnya dalam struktur DEVMODEW yang diarahkan oleh pdmOut. Konten awal dari struktur DEVMODEW output yang diterima (diarahkan oleh pdmOut) harus digunakan untuk menentukan versi output.

CDM_CONVERT351

Fungsi harus mengonversi konten struktur DEVMODEW input (ditunjukkan oleh pdmIn), membuat struktur DEVMODEW output yang kompatibel dengan Windows NT 3.51, dan menempatkan hasilnya dalam struktur DEVMODEW yang ditunjukkan oleh pdmOut.

Jika driver tidak mendukung struktur DEVMODEW untuk Windows NT 3.51, fungsi harus mengonversi input DEVMODEW ke versi saat ini.

CDM_DRIVER_DEFAULT

Fungsi harus menyalin versi saat ini dari struktur DEVMODEW default-nya ke buffer yang diarahkan oleh pdmOut.

Nilai kembali

Jika operasi berhasil, fungsi harus mengembalikan TRUE; jika tidak, setLastError harus memanggil SetLastError untuk mengatur kode kesalahan, dan mengembalikan FALSE.

Keterangan

Dalam lingkungan klien/server, klien mungkin menjalankan satu versi sistem operasi atau driver printer saat server (penampung) menjalankan yang lain, yang berarti definisi struktur DEVMODEW printer mungkin tidak konsisten antara klien dan server. Fungsi DrvConvertDevMode harus mampu melakukan konversi dari satu versi struktur DEVMODEW printer ke versi lainnya.

Saat mengonversi dari satu versi DEVMODEW ke versi lain, anggota DEVMODEW publik dan privat harus disertakan.

Nama printer yang ditujukan oleh pPrinterName dapat digunakan sebagai argumen input ke fungsi OpenPrinter (dijelaskan dalam dokumentasi Microsoft Windows SDK), yang dapat dipanggil untuk mendapatkan nilai default tersimpan saat bendera CDM_DRIVER_DEFAULT diterima. Perhatikan bahwa string nama printer tidak boleh dimodifikasi dengan cara apa pun sebelum panggilan ke OpenPrinter. Selain itu, panggilan ke OpenPrinter harus berada di utas yang sama seperti yang digunakan untuk memanggil DrvConvertDevMode.

Fungsi harus memverifikasi bahwa pdmIn dan pdmOut (jika berlaku) menunjuk ke struktur DEVMODEW yang valid. Jika tidak, fungsi harus memanggil SetLastError(ERROR_INVALID_PARAMETER) dan mengembalikan FALSE. Jika ukuran DEVMODEW output yang ditentukan oleh pcbNeeded terlalu kecil, driver harus menimpa nilai ukuran yang disediakan oleh pcbNeeded dengan ukuran buffer yang diperlukan, panggil SetLastError(ERROR_INSUFFICIENT_BUFFER), dan kembaliKAN FALSE.

Fungsi DrvConvertDevMode berjalan dalam konteks penampung dan karenanya tidak boleh menampilkan antarmuka pengguna.

Ketika DrvConvertDevMode dipanggil dengan penunjuk struktur NULL DEVMODEW dalam parameter pdmOut untuk mendapatkan ukuran buffer, driver diharapkan untuk mengatur kesalahan terakhir ke ERROR_INSUFFICIENT_BUFFER. Jika kesalahan terakhir tidak diatur ke nilai ini, penampung mengasumsikan kesalahan umum.

Persyaratan

Persyaratan	Nilai
Target Platform	Desktop
Header	winddiui.h (termasuk Winddiui.h)