Tas Properti Driver Printer V4

Artikel
03/08/2023

Penting

Kami menyarankan agar Anda menggunakan driver kelas kotak masuk IPP Microsoft, bersama dengan Print Support Apps (PSA), untuk menyesuaikan pengalaman cetak di Windows 10 dan 11 untuk pengembangan perangkat printer.

Untuk informasi selengkapnya, lihat Panduan desain aplikasi dukungan cetak.

Model driver cetak v4 menyediakan sejumlah tas properti yang memfasilitasi aliran data dari aplikasi UI yang disesuaikan ke proses penyajian.

Tas properti ini memungkinkan properti kustom dan definisi fitur dibuat dalam UI yang disesuaikan dan kemudian dikonsumsi oleh proses penyajian. Semua tas properti diekspos dengan menggunakan antarmuka IPrinterScriptablePropertyBag di JavaScript atau dengan menggunakan antarmuka IPrinterPropertyBag di lingkungan lain.

Tabel berikut memberikan gambaran umum tentang cara menggunakan komponen yang berbeda untuk mendapatkan objek tas properti dari berbagai bagian driver cetak v4.

Komponen	Deskripsi
Skrip batasan JavaScript	Tas properti driver dan antrean diteruskan ke skrip batasan JavaScript menggunakan parameter scriptContext. Parameter ini berjenis IPrinterScriptContext dan berisi turunan: DriverProperties – mengacu pada tas properti driver. QueueProperties – mengacu pada tas properti antrean. UserProperties – Tas properti pengguna. Tas properti DEVMODE diteruskan ke metode konversi DEVMODE <-> PrintTicket sebagai parameter devModeProperties (yang merupakan jenis IPrinterScriptablePropertyBag). Ini tidak tersedia pada metode lain.
USB Bidi JavaScript	Driver dan tas properti antrean diteruskan ke skrip USB Bidi JavaScript menggunakan parameter scriptContext. Parameter ini berjenis IPrinterScriptContext dan berisi turunan: DriverProperties – mengacu pada tas properti driver. QueueProperties – mengacu pada tas properti antrean.
Aplikasi ekstensi printer	Semua tas properti diteruskan sebagai bagian dari parameter IPrinterExtensionEventArgs ke handler OnDriverEvent. Mereka semua berjenis IPrinterPropertyBag. Mereka ditentukan sebagai berikut: DriverProperties – mengacu pada tas properti driver. UserProperties – Tas properti pengguna. PrinterQueue.GetProperties()– mengacu pada kantong properti antrean
Aplikasi perangkat UWP	Semua tas properti diteruskan selama aktivasi menggunakan objek IPrinterExtensionContext . Mereka ditentukan sebagai: DriverProperties – mengacu pada tas properti driver. UserProperties – Tas properti pengguna. PrinterQueue.GetProperties()– mengacu pada kantong properti antrean
Filter penyajian XPS	Filter XPS dapat mengakses tas properti driver dari dalam Tas Properti Alur Filter Cetak menggunakan nama properti "DriverPropertyBag", atau nilai yang ditentukan XPS_FP_PROPERTY_BAG dari filterpipeline.h. Berikut adalah informasi tentang DriverPropertyBag: Jenis properti: VT_UNKNOWN Deskripsi: Penunjuk ke antarmuka IUnknown. Panggil QueryInterface untuk mendapatkan pointer ke antarmuka IPrinterPropertyBag ke tas properti driver. Dan filter XPS dapat mengakses tas properti antrean dari dalam Tas Properti Alur Filter Cetak menggunakan nama properti "QueuePropertyBag", atau nilai yang ditentukan XPS_FP_QUEUE_PROPERTY_BAG dari filterpipeline.h. Berikut adalah informasi tentang QueuePropertyBag: Jenis properti: VT_UNKNOWN Deskripsi: Penunjuk ke antarmuka IUnknown. Panggil QueryInterface untuk mendapatkan penunjuk ke antarmuka IPrinterPropertyBag ke tas properti antrean.

Dalam implementasi JavaScript, tas properti diteruskan sebagai parameter. Dalam aplikasi ekstensi printer, tas properti diteruskan sebagai anggota argumen peristiwa yang digunakan untuk memulai aplikasi.

Pengakses tas properti yang disediakan oleh antarmuka COM IPrinterQueue, IPrinterExtensionContext dan IPrinterExtensionEventArgs serta pengakses tas properti dalam implementasi Javascript akan memberikan pengecualian jika tas properti tidak ditentukan atau tidak ditemukan. Selain itu, mengkueri properti individual pada antarmuka IPrinterPropertyBag akan memberikan pengecualian jika properti tidak ditemukan. Anda harus menggunakan pernyataan coba tangkap untuk menghindari crash jika properti tidak tersedia.

Tas Properti Driver

Tas properti driver adalah penyimpanan data bagi driver untuk menentukan properti atau blob data sebelumnya untuk penggunaan baca-saja oleh driver. Ini dapat ditentukan dengan menggunakan direktif "PropertyBag" dalam file manifes v4 dan mungkin tidak dimodifikasi saat runtime.

Windows Driver Kit menyertakan proyek templat untuk tas properti driver. Tas properti driver adalah blob biner yang dikompilasi. Visual Studio menyertakan templat untuk membuat tas properti driver yang dikompilasi. File XML yang dihasilkan untuk templat ini bukan tas properti, sebaliknya output yang dikompilasi dari templat ini adalah file tas properti yang harus ditentukan dalam file manifes v4.

Tas Properti Pengguna

Tas properti pengguna memungkinkan mitra untuk menyimpan pengaturan dalam konteks lokal mesin per pengguna. Tas properti ini sangat cocok sebagai mekanisme penyimpanan untuk preferensi pengguna seperti "Jangan tampilkan ini lagi". Tas properti ini tidak dapat dikelola oleh administrator dan tidak disinkronkan antara klien dan server selama berbagi printer. Tas properti pengguna hanya diatur pada runtime dan hanya tersedia untuk ekstensi printer, aplikasi perangkat UWP, dan batasan JavaScript.

Karena batasan JavaScript juga dapat dipanggil di luar konteks pengguna, selama pembongkaran, tas properti pengguna tidak tersedia saat ini dan Windows akan mengembalikan HRESULT_FROM_WIN32 (ERROR_NOT_FOUND).

Tas Properti DEVMODE

Tas properti DEVMODE digunakan untuk mengatur konten di bagian privat struktur DEVMODE. Selama panggilan ConvertPrintTicketToDevMode, JavaScript dipanggil untuk mengisi konten tas properti DEVMODE. Selama panggilan ConvertDevModeToPrintTicket, JavaScript dipanggil untuk membaca pengaturan yang bertahan dari tas properti DEVMODE dan menyimpannya kembali di PrintTicket.

Tas properti ini dibatasi ukurannya hingga kurang dari 60 KB (jumlah pastinya akan bervariasi berdasarkan ukuran bagian DEVMODE yang dialokasikan), karena harus diserialisasikan ke dalam struktur DEVMODE untuk menghindari kehilangan data dalam beberapa skenario. Ukuran yang tepat yang tersedia akan bervariasi per driver karena ditentukan oleh ukuran bagian publik DEVMODE ditambah bagian privat yang dikelola oleh modul konfigurasi.

Tas properti DEVMODE menggunakan file XML untuk menentukan anggota tas properti dan menggunakan CONVERTPrintTicketToDevMode dan convertDevModeToPrintTicket API untuk menangani konversi. File pemetaan XML DEVMODE harus ditentukan dalam manifes v4 dengan menggunakan direktif DevModeMap.

Cuplikan kode berikut menunjukkan Sampel XML Pemetaan Tas Properti DEVMODE.

<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns="https://schemas.microsoft.com/windows/2011/08/printing/devmodemap">
  <Property Name="FabrikamAccountCode">
    <String Length="32"></String>
  </Property>  
</Properties>

Cuplikan layar berikut menunjukkan Skema XML Pemetaan Tas Properti DEVMODE, dan dapat ditemukan di jalur berikut di folder penginstalan WDK: \Include\um\printerdriverdevmodemap.xsd.pr

skema xml pemetaan tas properti devmode.

File XML untuk pemetaan tas properti DEVMODE divalidasi oleh alat INFGate.

Tas Properti Antrean

Tas properti antrean menyimpan pengaturan konfigurasi per antrean, termasuk pemetaan formulir ke baki dan konfigurasi properti printer seperti opsi yang dapat diinstal. Properti yang ditentukan driver dan properti printer dapat dikonfigurasi di PowerShell, sedangkan formulir ke pemetaan baki dapat dikonfigurasi di UI properti printer. Ekstensi printer tidak dapat mengedit salah satu nilai properti.

Tas properti antrean dibuat secara otomatis untuk banyak driver cetak v4, tetapi driver juga dapat menyediakan properti tambahan untuk dikonfigurasi menggunakan file XML. File XML ini tidak boleh dikompilasi menggunakan alat tas properti driver. Tas properti antrean tersedia untuk printer yang didukung oleh driver cetak v4 yang melakukan salah satu hal berikut:

Tentukan beberapa baki, ATAU
Tentukan opsi yang dapat diinstal dalam file GPD atau PPD, ATAU
Tentukan tas properti antrean dalam manifes driver menggunakan arahan QueueProperties.

Administrator mengonfigurasi tas properti antrean menggunakan PowerShell. Command-lets (cmdlet) berikut adalah anak dari objek printer, yang dapat diperoleh menggunakan cmdlet Get-Printer.

Nama Cmdlet	Deskripsi
Get-PrinterProperty -printerName <printerName> -name <propertyName*>	Mengambil satu atau beberapa properti (-name mendukung globbing).
Set-PrinterProperty -inputObject <printerPropertyObject>	Mengubah properti antrean cetak menggunakan printerPropertyObject yang bertahan.
Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value>	Mengubah properti yang ditentukan ke nilai yang ditentukan.

Opsi yang dapat diinstal

Opsi ini, misalnya, status duplexer, akan diekspos ke dalam tas properti antrean sebagai properti individual. Setiap properti akan diberi nama sebagai berikut, di mana nama fitur didasarkan pada nama fitur dari file GPD atau PPD driver:

Config:<feature name>

Misalnya, Config:DuplexUnit

Nilai properti adalah nama kata kunci untuk opsi yang telah dipilih oleh administrator. Misalnya, Terinstal. Opsi yang dapat diinstal dapat diedit menggunakan cmdlet Set-PrinterProperty yang sama yang digunakan untuk properti antrean.

Dimulai dengan Windows 8.1, pengguna dengan hak Administrator, atau pengguna yang membuat antrean cetak dapat mengubah opsi Yang Dapat Diinstal dan pengaturan konfigurasi per antrean untuk tas properti antrean dari aplikasi perangkat UWP.

Pemetaan Formulir ke Baki

Untuk printer dengan driver cetak v4, dan dengan lebih dari satu baki, pemetaan "formulir ke baki" diekspos melalui tas properti antrean di properti bernama "FormTrayTable".

Properti ini diformat sebagai string yang dihentikan null yang berisi pasangan format <tray name>, <form name>, di mana nama formulir adalah salah satu dari berikut ini:

Jika ukuran kertas dipetakan ke dalam Skema Cetak dalam file GPD atau PPD (baik dengan menggunakan kata kunci standar *PaperSize/*PageSize, atau *(MS)PrintSchemaKeywordMap), maka nama formulir akan mengikuti format berikut:

PrintSchema:<Paper Size name>

Misalnya, PrintSchema:NorthAmericaLetter
Jika formulir adalah formulir yang ditentukan pengguna, seperti yang ditentukan oleh bendera FORM_USER, maka nama formulir akan menjadi sebagai berikut. Indeks formulir adalah nilai yang sama yang digunakan dalam database formulir penampung. Ini konsisten dengan indeks yang digunakan ketika ukuran kertas ditentukan dalam PrintTicket sebagai berikut:

UserForm<form index>

Misalnya, UserForm123
Jika tidak, nama formulir akan mengikuti format berikut, di mana nama formulir adalah nama yang ditentukan dalam GPD *PaperSize atau *PageSize PPD.

Config:<name>

Misalnya, Config:_8_5x16

Contoh lengkap string akan dibaca sebagai berikut:

Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0

Filter penyajian harus membaca pengaturan PageMediaSize PrintTicket yang masuk, dan mencari nilai tersebut dalam nilai nama formulir dari FormTrayTable.

Sampel XML Tas Properti Antrean

Cuplikan kode berikut menunjukkan sintaks XML yang dapat digunakan untuk tiga properti, Name1, Name2, Name3 dan elemen turunannya:

<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns= "https://schemas.microsoft.com/windows/2011/08/printing/queueproperties">
  <Property Name="Name1">
    <String>String1</String>
  </Property>
  <Property Name="Name2">
    <Int32>3244</Int32>
  </Property>
  <Property Name="Name3">
    <Bool>true</Bool>
  </Property>
</Properties>

Skema XML Tas Properti Antrean

Cuplikan layar berikut menunjukkan skema XML tas properti antrean, dan dapat ditemukan di jalur berikut di folder penginstalan WDK: \Include\um\printqueueproperties.xsd.

skema xml tas properti antrean.