Pastas de propriedades do driver de impressora V4
Importante
A plataforma de impressão moderna é o meio preferido do Windows para se comunicar com as impressoras. Recomendamos que você use o driver de classe de caixa de entrada IPP da Microsoft juntamente com PSA (Aplicativos de Suporte à Impressão) para personalizar a experiência de impressão no Windows 10 e 11 para o desenvolvimento de dispositivos de impressora.
Para obter mais informações, consulte Plataformade impressão moderna e o Guia de design do aplicativo de suporte de impressão.
O modelo de driver de impressão v4 fornece vários recipientes de propriedades que facilitam um fluxo de dados de aplicativos de interface do usuário personalizados para o processo de renderização.
Esses recipientes de propriedades permitem que propriedades personalizadas e definições de recursos sejam criadas em uma interface do usuário personalizada e, em seguida, sejam consumidas pelo processo de renderização. Todos os recipientes de propriedades são expostos usando a interface IPrinterScriptablePropertyBag em JavaScript ou usando a interface IPrinterPropertyBag em outros ambientes.
A tabela a seguir fornece uma visão geral de como usar diferentes componentes para obter o objeto do recipiente de propriedades de diferentes partes de um driver de impressão v4.
| Componente | Descrição |
|---|---|
| Script de restrição JavaScript | Os recipientes de propriedades do driver e da fila são passados para scripts de restrição JavaScript usando o parâmetro scriptContext. Esse parâmetro é do tipo IPrinterScriptContext e contém filhos: DriverProperties – refere-se ao recipiente de propriedades do driver. QueueProperties – refere-se ao recipiente de propriedades da fila. UserProperties – O recipiente de propriedades do usuário. O recipiente de propriedades DEVMODE é passado para <-> os métodos de conversão PrintTicket DEVMODE como o parâmetro devModeProperties (que é do tipo IPrinterScriptablePropertyBag). Não está disponível nos outros métodos. |
| USB Bidi JavaScript | Os pacotes de propriedades do driver e da fila são passados para scripts JavaScript USB Bidi usando o parâmetro scriptContext. Esse parâmetro é do tipo IPrinterScriptContext e contém filhos: DriverProperties – refere-se ao recipiente de propriedades do driver. QueueProperties – refere-se ao recipiente de propriedades da fila. |
| Aplicativo de extensão de impressora | Todos os recipientes de propriedades são passados como parte do parâmetro IPrinterExtensionEventArgs para o manipulador OnDriverEvent. Eles são todos do tipo IPrinterPropertyBag. Eles são especificados da seguinte forma: DriverProperties – refere-se ao recipiente de propriedades do driver. UserProperties – O recipiente de propriedades do usuário. PrinterQueue.GetProperties()– refere-se ao recipiente de propriedades da fila |
| Aplicativo do dispositivo UWP | Todos os recipientes de propriedades são passados durante a ativação usando o objeto IPrinterExtensionContext. Eles são especificados como: DriverProperties – refere-se ao recipiente de propriedades do driver. UserProperties – O recipiente de propriedades do usuário. PrinterQueue.GetProperties()– refere-se ao recipiente de propriedades da fila |
| Filtro de renderização XPS | Os filtros XPS podem acessar o recipiente de propriedades do driver de dentro do Recipiente de Propriedades do Pipeline do Filtro de Impressão usando o nome da propriedade "DriverPropertyBag" ou o valor definido XPS_FP_PROPERTY_BAG de filterpipeline.h. Aqui estão as informações sobre DriverPropertyBag: Tipo de propriedade: VT_UNKNOWN Descrição: Um ponteiro para uma interface IUnknown. Chame QueryInterface para obter um ponteiro para a interface IPrinterPropertyBag para o recipiente de propriedades do driver. E os filtros XPS podem acessar o recipiente de propriedades da fila de dentro do Recipiente de Propriedades do Pipeline de Filtro de Impressão usando o nome da propriedade "QueuePropertyBag" ou o valor definido XPS_FP_QUEUE_PROPERTY_BAG de filterpipeline.h. Aqui estão as informações sobre QueuePropertyBag: Tipo de propriedade: VT_UNKNOWN Descrição: Um ponteiro para uma interface IUnknown. Chame QueryInterface para obter um ponteiro para a interface IPrinterPropertyBag para o recipiente de propriedades da fila. |
Em implementações JavaScript, os recipientes de propriedades são passados como parâmetros. Em aplicativos de extensão de impressora, os recipientes de propriedades são passados como membros do argumento de evento usado para iniciar o aplicativo.
Os acessadores do recipiente de propriedades fornecidos pelas interfaces COM IPrinterQueue, IPrinterExtensionContext e IPrinterExtensionEventArgs, bem como os acessadores do recipiente de propriedades em implementações Javascript, gerarão uma exceção se o recipiente de propriedades não for especificado ou não for encontrado. Além disso, consultar propriedades individuais em uma interface IPrinterPropertyBag gerará exceções se a propriedade não for encontrada. Você deve usar uma instrução try catch para evitar falhas se uma propriedade não estiver disponível.
Recipiente de propriedade de driver
O recipiente de propriedades do driver é um armazenamento de dados para drivers predefinirem propriedades ou blobs de dados para uso somente leitura pelo driver. Ele pode ser especificado usando a diretiva "PropertyBag" no arquivo de manifesto v4 e não pode ser modificado em runtime.
O Windows Driver Kit inclui um projeto de modelo para um recipiente de propriedades do driver. O recipiente de propriedades do driver é um blob binário compilado. O Visual Studio inclui um modelo para gerar um recipiente de propriedades de driver compilado. O arquivo XML gerado para esse modelo não é o recipiente de propriedades, em vez disso, a saída compilada desse modelo é o arquivo do recipiente de propriedades que deve ser especificado no arquivo de manifesto v4.
Recipiente de propriedades do usuário
O recipiente de propriedades do usuário permite que os parceiros armazenem configurações em um contexto local de computador por usuário. Esse recipiente de propriedades é adequado como um mecanismo de armazenamento para preferências do usuário, como "Não mostrar isso novamente". Esse recipiente de propriedades não é gerenciável por administradores e não é sincronizado entre o cliente e o servidor durante o compartilhamento de impressora. O recipiente de propriedades do usuário só é definido em tempo de execução e só está disponível para as extensões de impressora, aplicativos de dispositivo UWP e restrições JavaScript.
Como as restrições de JavaScript também podem ser chamadas fora de um contexto de usuário, durante o despoolamento, o recipiente de propriedades do usuário não está disponível no momento e o Windows retornará HRESULT_FROM_WIN32(ERROR_NOT_FOUND).
Recipiente de propriedades DEVMODE
O recipiente de propriedades DEVMODE é usado para organizar o conteúdo na seção privada da estrutura DEVMODE. Durante as chamadas ConvertPrintTicketToDevMode, o JavaScript é invocado para preencher o conteúdo do recipiente de propriedades DEVMODE. Durante as chamadas ConvertDevModeToPrintTicket, o JavaScript é invocado para ler as configurações persistentes do recipiente de propriedades DEVMODE e armazená-las de volta no PrintTicket.
Esse recipiente de propriedades é limitado em tamanho a menos de 60 KB (a quantidade exata varia de acordo com o tamanho das seções alocadas do DEVMODE), pois ele deve ser serializado em uma estrutura DEVMODE para evitar a perda de dados em alguns cenários. O tamanho exato disponível varia de acordo com o driver porque é determinado pelo tamanho da seção pública do DEVMODE mais a seção privada gerenciada pelo módulo de configuração.
O recipiente de propriedades DEVMODE usa um arquivo XML para especificar os membros do recipiente de propriedades e usa as APIs convertPrintTicketToDevMode e convertDevModeToPrintTicket para lidar com as conversões. O arquivo de mapeamento XML DEVMODE deve ser especificado no manifesto v4 usando a diretiva DevModeMap.
O snippet de código a seguir mostra um exemplo XML de mapeamento de recipiente de propriedades 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>
A captura de tela a seguir mostra o esquema XML de mapeamento de recipiente de propriedades DEVMODE e pode ser encontrada no seguinte caminho na pasta de instalação do WDK: \Include\um\printerdriverdevmodemap.xsd.pr
Os arquivos XML para o mapeamento do recipiente de propriedades DEVMODE são validados pela ferramenta INFGate.
Recipiente de propriedades da fila
O recipiente de propriedades da fila armazena definições de configuração por fila, incluindo mapeamentos de formulário para bandeja e a configuração de propriedades de impressora, como opções instaláveis. As propriedades definidas pelo driver e as propriedades da impressora são configuráveis no PowerShell, enquanto os mapeamentos de formulário para bandeja são configuráveis na interface do usuário das propriedades da impressora. As extensões de impressora não podem editar nenhum dos valores de propriedade.
O recipiente de propriedades da fila é criado automaticamente para muitos drivers de impressão v4, mas os drivers também podem fornecer propriedades adicionais para configurar usando um arquivo XML. Esse arquivo XML não deve ser compilado usando a ferramenta recipiente de propriedades do driver. Os recipientes de propriedades da fila estão disponíveis para impressoras compatíveis com drivers de impressão v4 que executam um dos seguintes procedimentos:
Especificar várias bandejas, OU
Especificar as opções instaláveis no arquivo GPD ou PPD, OU
Especificar um recipiente de propriedades de fila no manifesto do driver usando a diretiva QueueProperties.
Os administradores configuram recipientes de propriedades da fila usando o PowerShell. Os cmdlets (command-lets) a seguir são filhos de um objeto de impressora, que podem ser obtidos usando o cmdlet Get-Printer.
| Nome do cmdlet | Descrição |
|---|---|
| Get-PrinterProperty -printerName <printerName> -name <propertyName*> | Recupera uma ou mais propriedades (-name suporta globbing). |
| Set-PrinterProperty -inputObject <printerPropertyObject> | Altera uma propriedade da fila de impressão usando um printerPropertyObject persistente. |
| Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value> | Altera a propriedade especificada para o valor especificado. |
Opções instaláveis
Essas opções, por exemplo, o estado de um duplexador, serão expostas no recipiente de propriedades da fila como propriedades individuais. Cada propriedade será nomeada da seguinte maneira, em que o nome do recurso é baseado no nome do recurso do arquivo GPD ou PPD do driver:
Config:<feature name>
Por exemplo, Config:DuplexUnit
O valor da propriedade é o nome da palavra-chave para a opção que foi selecionada pelo administrador. Por exemplo, Instalado. As opções instaláveis são editáveis usando o mesmo cmdlet Set-PrinterProperty usado para propriedades de fila.
A partir do Windows 8.1, um usuário com direitos de administrador ou um usuário que criou uma fila de impressão pode alterar as opções instaláveis e as definições de configuração por fila para um recipiente de propriedades da fila de um aplicativo de dispositivo UWP.
Mapeamentos de formulário para bandeja
Para impressoras com um driver de impressão v4 e com mais de uma bandeja, os mapeamentos de "formulário para bandeja" são expostos por meio do recipiente de propriedades da fila na propriedade chamada "FormTrayTable".
Essa propriedade é formatada como uma cadeia de caracteres terminada em nulo contendo pares do formato <tray name>, <form name>, em que o nome do formulário é um dos seguintes:
Se o tamanho do papel for mapeado para o Esquema de Impressão no arquivo GPD ou PPD (usando palavras-chave padrão *PaperSize/*PageSize ou *(MS)PrintSchemaKeywordMap), o nome do formulário seguirá o seguinte formato:
PrintSchema:<Paper Size name>Por exemplo,
PrintSchema:NorthAmericaLetterSe o formulário for um formulário definido pelo usuário, conforme determinado pelo sinalizador FORM_USER, o nome do formulário será o seguinte. O índice de formulário é o mesmo valor usado no banco de dados de formulários do spooler. Isso é consistente com o índice usado quando o tamanho do papel é especificado no PrintTicket da seguinte maneira:
UserForm<form index>Por exemplo,
UserForm123Caso contrário, o nome do formulário seguirá o seguinte formato, em que o nome do formulário é o nome especificado no *PaperSize do GPD ou no *PageSize do PPD.
Config:<name>Por exemplo,
Config:_8_5x16
Uma cadeia de caracteres de exemplo completa seria lida da seguinte maneira:
Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0
Os filtros de renderização devem ler a configuração PageMediaSize do PrintTicket de entrada e pesquisar esse valor nos valores de nome do formulário do FormTrayTable.
Exemplo de XML do recipiente de propriedades da fila
O snippet de código a seguir mostra a sintaxe XML que pode ser usada para três propriedades, Name1, Name2, Name3 e seus elementos filho:
<?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>
Esquema XML do recipiente de propriedades da fila
A captura de tela a seguir mostra o esquema XML do recipiente de propriedades da fila e pode ser encontrado no seguinte caminho na pasta de instalação do WDK: \Include\um\printqueueproperties.xsd.
Tópicos relacionados
Recipiente de Propriedades de Pipeline do Filtro de Impressão