Metode IPrintOemUI::D eviceCapabilities (prcomoem.h)

  • Artikel

Metode ini IPrintOemUI::DeviceCapabilities memungkinkan plug-in antarmuka pengguna untuk menentukan kemampuan perangkat yang disesuaikan.

Sintaks

HRESULT DeviceCapabilities(
  POEMUIOBJ poemuiobj,
  HANDLE    hPrinter,
  PWSTR     pDeviceName,
  WORD      wCapability,
  PVOID     pOutput,
  PDEVMODE  pPublicDM,
  PVOID     pOEMDM,
  DWORD     dwOld,
  DWORD     *dwResult
);

Parameter

poemuiobj

Penunjuk yang disediakan penelepon ke struktur OEMUIOBJ .

hPrinter

Handel yang disediakan penelepon ke perangkat printer.

pDeviceName

Penunjuk yang disediakan penelepon ke string yang mewakili nama perangkat.

wCapability

Bendera yang disediakan penelepon yang menunjukkan jenis informasi yang harus dikembalikan metode. Untuk daftar bendera, lihat deskripsi fungsi DrvDeviceCapabilities .

pOutput

Penunjuk yang disediakan penelepon ke buffer untuk menerima informasi yang diminta. Jenis informasi yang dikembalikan tergantung pada bendera yang ditentukan oleh wCapability.

pPublicDM

Penunjuk yang disediakan penelepon ke struktur DEVMODEW yang divalidasi.

pOEMDM

Penunjuk yang disediakan penelepon ke anggota struktur DEVMODEW privat plug-in antarmuka pengguna.

dwOld

Nilai pengembalian yang disediakan penelepon dari fungsi DrvDeviceCapabilities driver printer, atau dari plug-in antarmuka pengguna lain. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

dwResult

Nilai pengembalian yang bergantung pada bendera yang ditentukan oleh wCapability. Untuk informasi selengkapnya, lihat deskripsi fungsi DrvDeviceCapabilities dan bagian Keterangan berikut.

Nilai kembali

Metode harus mengembalikan salah satu nilai berikut.

Menampilkan kode Deskripsi
S_OK
 Operasi berhasil.
S_DEVCAP_OUTPUT_FULL_REPLACEMENT
 Plug-in berniat menggunakan buffer yang diacu oleh parameter pOutput untuk tujuannya sendiri. Nilai pengembalian ini didefinisikan dalam prcomoem.h. Untuk informasi selengkapnya tentang kapan menggunakan nilai pengembalian ini, lihat bagian Keterangan berikut ini.
E_FAIL
 Operasi gagal.
E_NOTIMPL
 Metode ini tidak diterapkan.

Keterangan

Metode plug-in antarmuka pengguna melakukan jenis operasi yang sama dengan fungsi DrvDeviceCapabilities yang diekspor IPrintOemUI::DeviceCapabilities oleh DLL antarmuka printer mode pengguna. Metode ini menentukan kemampuan yang disediakan oleh printer.

Anda dapat menggunakan metode untuk IPrintOemUI::DeviceCapabilities mendahului dukungan Unidrv untuk suatu kemampuan, atau untuk menambahkan kemampuan yang tidak disediakan driver printer. Driver memanggil IPrintOemUI::DeviceCapabilities dari dalam fungsi DrvDeviceCapabilities-nya .

IPrintOemUI::DeviceCapabilities Jika metode menunjukkan dukungan yang disesuaikan untuk kemampuan (dengan mengatur bit yang sesuai sebagai respons terhadap bendera DC_FIELDS yang diterima), kode yang disesuaikan harus sepenuhnya mendukung kemampuan. Dukungan lengkap biasanya mencakup mengembalikan informasi tentang kemampuan sebagai respons terhadap panggilan ke IPrintOemUI::DeviceCapabilities metode , ditambah menyediakan mode pengguna atau kode mode kernel yang sesuai untuk mengimplementasikan kemampuan.

Jika IPrintOemUI::DeviceCapabilities metode diekspor oleh beberapa plug-in antarmuka pengguna, metode dipanggil dalam urutan plug-in ditentukan untuk penginstalan. Setiap kali metode plug-in dipanggil IPrintOemUI::DeviceCapabilities , nilai input dwOld-nya adalah nilai pengembalian dari metode plug-in IPrintOemUI::DeviceCapabilities yang sebelumnya disebut. Untuk plug-in pertama yang dipanggil, dwOld berisi nilai pengembalian dari fungsi DrvDeviceCapabilities driver printer. Demikian juga, buffer yang diacu oleh pOutput berisi, pada input, konten apa pun yang ditempatkan di sana dengan metode yang sebelumnya disebut IPrintOemUI::DeviceCapabilities atau fungsi DrvDeviceCapabilities .

Agar beberapa plug-in antarmuka pengguna berfungsi bersama satu sama lain, setiap IPrintOemUI::DeviceCapabilities metode harus mematuhi aturan berikut:

  • Jika plug-in antarmuka pengguna tidak mendukung kemampuan yang ditentukan, metodenya IPrintOemUI::DeviceCapabilities seharusnya hanya mengembalikan konten parameter dwOld di dwResult.
  • Jika plug-in antarmuka pengguna mendukung kemampuan, metodenya IPrintOemUI::DeviceCapabilities harus mengabaikan dwOld dan konten buffer yang diarahkan oleh pOutput. Ini harus memberikan nilai pengembalian dan konten buffer yang sesuai untuk menunjukkan bahwa ia mendukung kemampuan yang ditentukan. Jika metode mendeteksi kesalahan, metode harus mengembalikan GDI_ERROR di dwResult.
  • Jika Anda ingin plug-in antarmuka pengguna memodifikasi informasi kemampuan yang diterima dalam buffer yang diarahkan oleh pOutput, metodenya IPrintOemUI::DeviceCapabilities harus memodifikasi konten buffer dan mengembalikan nilai pengembalian yang sesuai di dwResult. Misalnya, jika wCapability DC_FIELDS, metode harus ATAU bit yang perlu diatur dengan bit yang diatur dalam dwOld, dan mengembalikan hasil operasi OR di dwResult.
  • Aturan sebelumnya harus diikuti meskipun konten dwOld yang diterima GDI_ERROR.
Ketika fungsi DrvDeviceCapabilities driver dipanggil dengan set bendera DC_FIELDS, fungsi memanggil semua IPrintOemUI::DeviceCapabilities metode, juga menentukan DC_FIELDS, dan mengembalikan penyatuan semua bit yang ditetapkan ke pemanggil.

Nilai pengembalian S_DEVCAP_OUTPUT_FULL_REPLACEMENT baru di Windows Vista, dan berlaku untuk plug-in antarmuka pengguna Unidrv dan Pscript5. Plug-in harus menggunakan nilai pengembalian S_DEVCAP_OUTPUT_FULL_REPLACEMENT hanya jika memerlukan kontrol penuh atas apa yang ditempatkan di buffer yang ditunjukkan oleh parameter pOutput . Baik driver inti Unidrv maupun Pscript5 tidak akan menempatkan data di buffer pOutput saat plug-in mengembalikan S_DEVCAP_OUTPUT_FULL_REPLACEMENT. Plug-in mungkin perlu mengembalikan nilai ini ketika pengaturan dalam struktur DEVMODEW (yang ditunjukkan oleh parameter pPublicDM dan pOEMDM ) menunjukkan kepada plug-in antarmuka pengguna bahwa ia harus melaporkan data kemampuan perangkat yang berbeda dari yang ditentukan dalam file GPD atau PPD. Misalnya, struktur DEVMODEW yang menentukan pencetakan foto mungkin memerlukan sekumpulan jenis kertas yang berbeda dari yang ditentukan dalam file GPD atau PPD. Dalam situasi seperti itu, dan terlepas dari nilai parameter pOutput dan dwOld , plug-in harus mengembalikan S_DEVCAP_OUTPUT_FULL_REPLACEMENT, dan harus mengatur parameter dwResult ke jumlah jenis kertas yang ingin dilaporkan. Jika pOutput bukan NULL, plug-in juga harus mengisi buffer yang diarahkan oleh pOutput dengan set jenis kertas yang diinginkan, dan harus mengatur dwResult ke jumlah jenis kertas yang ingin dilaporkan oleh plug-in.

Ketika beberapa plug-in antarmuka pengguna aktif pada saat yang sama, dan salah satunya mengembalikan S_DEVCAP_OUTPUT_FULL_REPLACEMENT, driver inti Unidrv atau Pscript5 menginterpretasikan nilai pengembalian ini berarti bahwa plug-in bermaksud memberikan data output pengganti penuh. Akibatnya, driver inti tidak menempatkan data apa pun ke dalam buffer pOutput sebelum memanggil plug-in. (Driver inti memanggil plug-in dalam urutan yang sama yang ditentukan untuk penginstalannya.)

Dalam situasi di mana nilai yang ditempatkan driver inti di buffer pOutput tidak perlu diganti, plug-in harus mengembalikan S_OK. Driver inti Unidrv dan Pscript5 mengenali nilai pengembalian S_DEVCAP_OUTPUT_FULL_REPLACEMENT hanya untuk kemampuan perangkat yang menggunakan buffer pOutput --dengan kata lain, ketika parameter wCapability diatur ke salah satu bendera berikut:

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

Untuk informasi selengkapnya tentang membuat dan menginstal plug-in antarmuka pengguna, lihat Menyesuaikan Driver Printer Microsoft.

Persyaratan

Persyaratan Nilai
Target Platform Desktop
Header prcomoem.h (termasuk Prcomoem.h)

Lihat juga

DrvDeviceCapabilities

IPrintOemUI