Restrições de JavaScript

O modelo de driver de impressora v4 suporta um novo modelo para restrições avançadas e gestão de PrintTicket, que é originado da interface v3 IPrintOemPrintTicketProvider.

Em vez de usar um plug-in de configuração compilado, no entanto, os drivers de impressora v4 usam JavaScript para implementar APIs chamadas restrições de JavaScript, e o driver de impressora pode implementar um ou mais deles, conforme necessário. Para obter mais informações, consulte as funções na seção APIs de restrição de JavaScript no final deste tópico.

As restrições de JavaScript podem ser usadas para aumentar as capacidades de impressão, validar os bilhetes de impressão e lidar com a conversão de bilhetes de impressão para DEVMODE e vice-versa. No entanto, as restrições de JavaScript têm algumas limitações. Segue-se uma lista das principais limitações:

• Recursos e opções adicionados usando CompletePrintCapabilities, bem como restrições especificadas em validatePrintTicket não são mostrados na janela de preferências da impressora desktop.

• Recursos e opções adicionados no uso de CompletePrintCapabilities não são persistidos no DEVMODE público.

• As restrições de JavaScript não podem acessar recursos de idioma de dlls de recursos para localizar recursos e opções ou parâmetros adicionados.

Como tal, recomendamos que as restrições JavaScript sejam usadas apenas quando apropriado. Recursos e opções devem ser especificados nos arquivos GPD ou PPD sempre que possível, e apenas restrições complicadas devem ser representadas em JavaScript.

Depurando arquivos JavaScript

A validação sintática básica de arquivos JavaScript é suportada pela abertura do arquivo JavaScript no Host de Scripts baseado no Windows. Para fazer isso, clique com o botão direito do mouse no arquivo JavaScript e selecione Abrir com, e escolha a entrada Host de script baseado no Windows na lista. Se nenhum erro for gerado, o JavaScript será sintaticamente válido. Caso contrário, ele apontará o número da linha do problema, conforme mostrado na captura de tela a seguir.

As ferramentas de validação JavaScript disponíveis publicamente também podem ser valiosas como um auxiliar na avaliação do estilo dos arquivos JavaScript.

A depuração interativa pode ser habilitada criando a seguinte chave do Registro:

Nome da chave: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print

Nome do valor: EnableJavaScriptDebugging

Tipo: DWORD

Valor: 1

No entanto, como PrintConfig.dll é carregado e descarregado com frequência, depurar um aplicativo que imprime não é uma estratégia recomendada de teste/depuração. Em vez disso, a Microsoft recomenda que os fabricantes criem um aplicativo de teste que chame cada um dos pontos de entrada relevantes para restrições de JavaScript usando essas APIs públicas: PTGetPrintCapabilities, PTConvertDevModeToPrintTicket, PTConvertPrintTicketToDevMode e PTMergeAndValidatePrintTicket.

O aplicativo de teste por si só é suficiente para habilitar a depuração, mas também é benéfico adicionar testes de unidade para garantir que todo o driver esteja lidando com PrintTicket, PrintCapabilities e restrições conforme o esperado. Para obter mais informações sobre como criar testes de unidade no Visual Studio, consulte o seguinte tópico:

Um passo a passo de teste de unidade com o teste de equipe do Visual Studio

Depois que a chave do Registro mostrada no texto anterior for criada e o processo de hospedagem tiver sido reiniciado, você poderá depurar seu arquivo de origem JavaScript.

É importante notar que, se o arquivo de origem falhar ao analisar, o depurador não será invocado e parecerá que o ambiente de depuração falhou. Se o arquivo de origem falhar na análise, consulte Windows Script Host para obter mais informações sobre como proceder.

Se não houver erros e o arquivo de origem for analisado com êxito, depure o arquivo de origem da seguinte maneira:

1. Instalar o Microsoft Visual Studio 2012 ou posterior na máquina de teste

2. Criar uma fila de impressão usando o driver que tem o código de restrições JavaScript

3. Defina esta fila de impressão como padrão.

4. Inicie seu aplicativo de teste ou um aplicativo que imprima e inicie um cenário que fará com que restrições de JavaScript sejam invocadas. O aplicativo deve chamar as APIs PrintTicket/PrintCapabilities para quebrar as restrições de JavaScript; aplicativos mais antigos, como o Bloco de Notas, não chamam essas APIs, mas o aplicativo Visualizador XPS sim. A Microsoft recomenda o uso de um aplicativo de teste aqui, já que os cenários podem ser mais facilmente isolados e reproduzidos.

5. Neste momento, o "Visual Studio Just-In-Time Debugger" aparecerá dizendo "Ocorreu uma exceção não tratada em <seu aplicativo>"

6. Iniciar uma nova instância do Visual Studio 2012 ou posterior

7. Escolha Depurar e, em seguida, Anexar ao processo

8. Na caixa de diálogo Anexar ao processo, verifique se Anexar a: está definido como código de script

9. Agora escolha o aplicativo de teste ou a impressão do aplicativo e, finalmente, escolha Anexar

10. Clique em "Quebrar tudo"

11. Agora volte para a caixa de diálogo "Visual Studio Just-In-Time Debugger" e clique em "Não"

12. O Visual Studio invadirá o depurador no local chamado pelo teste atual. Agora você pode depurar o código normalmente.

APIs de restrição de JavaScript

Esta seção especifica as funções que servem como pontos de entrada da API para uso no arquivo de restrição JavaScript. Estas são as funções:

• validatePrintTicket

• capacidadesDeImpressãoCompletas

• convertDevModeToPrintTicket

• convertPrintTicketToDevMode

função validatePrintTicket

Essa API é chamada para validar que um objeto PrintTicket é válido para uma impressora específica. Isso é análogo em função ao IPrintOemPrintTicketProvider::ValidatePrintTicket API.

Sintaxe de validatePrintTicket

function validatePrintTicket(printTicket, scriptContext)

validatePrintTicket parâmetros

• imprimirBilhete

  [in][out] O objeto IPrintSchemaTicket para validação.

• scriptContext

  [em] O objeto IPrinterScriptContext que fornece acesso ao pacote de propriedades do driver, ao pacote de propriedades da fila e ao pacote de propriedades do usuário.

validatePrintTicket valor de retorno

função completePrintCapabilities

Essa API é chamada para permitir que o objeto PrintCapabilities seja modificado. Isso deve ser usado para recursos condicionais (por exemplo, sem margens é suportado apenas em papel fotográfico) ou para representar recursos que de outra forma não poderiam ser gerados por um arquivo GPD ou PPD (por exemplo, definições de recurso aninhadas). Isso é análogo em função à API IPrintOemPrintTicketProvider::CompletePrintCapabilities .

sintaxe de capacidades de impressão completas

function completePrintCapabilities(printTicket, scriptContext, printCapabilities)

parâmetros completePrintCapabilities

• imprimirBilhete

  [em] A entrada do objeto IPrintSchemaTicket para restringir o documento PrintCapabilities gerado.

• scriptContext

  [em] O objeto IPrinterScriptContext que fornece acesso ao pacote de propriedades do driver, ao pacote de propriedades da fila e ao pacote de propriedades do usuário.

• capacidades de impressão

  [em][saídas] O objeto IPrintSchemaCapabilities que representa o objeto PrintCapabilities base que foi gerado pelo módulo de configuração.

o valor de retorno de completePrintCapabilities

Nenhum.

Função convertDevModeToPrintTicket

Essa API é chamada para converter valores do pacote de propriedades DEVMODE em um PrintTicket. Isso é análogo em função à API IPrintOemPrintTicketProvider::ConvertDevModeToPrintTicket , exceto que essa implementação encapsula a seção privada do DEVMODE em um objeto IPrinterScriptablePropertyBag e não permite acesso à seção pública do DEVMODE.

Sintaxe convertDevModeToPrintTicket

function convertDevModeToPrintTicket(devModeProperties, scriptContext, printTicket)

Parâmetros do convertDevModeToPrintTicket

• devModeProperties

[em] O objeto IPrinterScriptablePropertyBag que representa o Conjunto de Propriedades DEVMODE.

• scriptContext

  [em] O objeto IPrinterScriptContext que fornece acesso ao pacote de propriedades do driver, ao pacote de propriedades da fila e ao pacote de propriedades do usuário.

• imprimirBilhete

  [em][saídas] O objeto IPrintSchemaTicket que representa o PrintTicket.

o valor de retorno de convertDevModeToPrintTicket

Nenhum.

Função convertPrintTicketToDevMode

Essa API é chamada para converter valores de um PrintTicket no pacote de propriedades DEVMODE. Isso é análogo em função à API IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode , exceto que essa implementação encapsula a seção privada do DEVMODE em um objeto IPrinterScriptablePropertyBag e não permite acesso à seção pública do DEVMODE.

sintaxe convertPrintTicketToDevMode

function convertPrintTicketToDevMode(printTicket, scriptContext, devModeProperties)

convertPrintTicketToDevMode parâmetros

• imprimirBilhete

  [em] O objeto IPrintSchemaTicket que representa o PrintTicket a ser convertido.

• scriptContext

  [em] O objeto IPrinterScriptContext que fornece acesso ao pacote de propriedades do driver, ao pacote de propriedades da fila e ao pacote de propriedades do usuário.

• devModeProperties

  [entrada][saída] O objeto IPrinterScriptablePropertyBag que representa o Conjunto de Propriedades DEVMODE.

convertPrintTicketToDevMode valor de retorno

Nenhum.

Práticas recomendadas de restrição

A caixa de diálogo de impressão do Windows 8 e a experiência de preferências de impressão suportam apenas um subconjunto do namespace Palavras-chave do esquema de impressão. Como resultado, a Microsoft não recomenda o uso de restrições entre recursos suportados na caixa de diálogo de impressão do Windows 8 ou na interface do usuário de preferências de impressão e recursos que não estão nessa interface do usuário, uma vez que os usuários não terão oportunidade de resolver essas restrições.

Por exemplo, se a opção PageMediaType chamada Photo estiver restrita a trabalhar apenas com um valor PageResolution de 1200dpi, os usuários nunca poderão escolher o tipo de mídia Photo. Em casos como este, é melhor corresponder à intenção do usuário (mídia de fotos) e ajustar as configurações necessárias para que isso ocorra. Esses ajustes podem ser feitos no código de restrição JavaScript.

Se um driver não utilizar restrições JavaScript, não há nenhum requisito de que um arquivo seja fornecido. Se um driver utiliza restrições JavaScript para apenas um subconjunto dos pontos de entrada (por exemplo, validatePrintTicket), os outros pontos de entrada devem ser totalmente omitidos do arquivo JavaScript.