Sacos de propriedades do driver de impressora V4

Artigo
03/08/2023

Importante

Recomendamos que você use o driver de classe de caixa de entrada IPP da Microsoft, juntamente com o PSA (Aplicativos de Suporte para Impressão), para personalizar a experiência de impressão em Windows 10 e 11 para o desenvolvimento de dispositivos de impressora.

Para obter mais informações, consulte o Guia de design do aplicativo de suporte para impressão.

O modelo de driver de impressão v4 fornece uma série de 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 do JavaScript	Os recipientes de propriedades de fila e driver 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 DEVMODE <–> PrintTicket como o parâmetro devModeProperties (que é do tipo IPrinterScriptablePropertyBag). Não está disponível nos outros métodos.
USB Bidi JavaScript	Os recipientes de propriedades de fila e driver são passados para scripts JavaScript bidi USB 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 como os seguintes: 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 de 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 de 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 de 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 lançarão uma exceção se o recipiente de propriedades não for especificado ou não for encontrado. Além disso, a consulta de 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 propriedades do driver

O recipiente de propriedades do driver é um armazenamento de dados para drivers predefine 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 pode não ser modificado em runtime.

O Kit de Driver do Windows 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 do 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 de 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 pelos administradores e não é sincronizado entre o cliente e o servidor durante o compartilhamento da impressora. O recipiente de propriedades do usuário só é definido em runtime e só está disponível para extensões de impressora, aplicativos de dispositivo UWP e restrições javaScript.

Como as restrições javaScript também podem ser chamadas fora de um contexto de usuário, durante o despooling, 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 novamente no PrintTicket.

Esse recipiente de propriedades é limitado em tamanho a menos de 60 KB (a quantidade exata variará com base no tamanho das seções alocadas do DEVMODE), pois 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 manipular 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 de XML de mapeamento do 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 do recipiente de propriedades DEVMODE e pode ser encontrado no seguinte caminho na pasta de instalação do WDK: \Include\um\printerdriverdevmodemap.xsd.pr

esquema xml de mapeamento do recipiente de propriedades devmode.

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 o formulário para mapeamentos de bandeja e a configuração de propriedades da 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 forma 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 de 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 fazem um dos seguintes procedimentos:

Especificar várias bandejas, OR
Especificar opções instaláveis no arquivo GPD ou PPD, OR
Especifique um recipiente de propriedades de fila no manifesto do driver usando a diretiva QueueProperties.

Os administradores configuram os recipientes de propriedades da fila usando o PowerShell. Os cmdlets (command-lets) a seguir são filhos de um objeto de impressora, que pode ser obtido usando o cmdlet Get-Printer.

Nome do Cmdlet	Descrição
Get-PrinterProperty -printerName <printerName> -name <propertyName*>	Recupera uma ou mais propriedades (-name dá suporte a globbing).
Set-PrinterProperty -inputObject <printerPropertyObject>	Altera uma propriedade de 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 duplexer, 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.

Começando com 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 de 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 que contém 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:NorthAmericaLetter
Se 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ário do spooler. Isso é consistente com o índice usado quando o tamanho do papel é especificado no PrintTicket da seguinte maneira:

UserForm<form index>

Por exemplo, UserForm123
Caso contrário, o nome do formulário seguirá o formato a seguir, 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 da FormTrayTable.

Exemplo de XML do recipiente de propriedades queue

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 queue

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.

esquema xml do recipiente de propriedades da fila.