Restrições de JavaScript

O modelo de driver de impressora v4 dá suporte a um novo modelo para restrição estendida e tratamento de PrintTicket derivado da interface IPrintOemPrintTicketProvider v3.

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

As restrições JavaScript podem ser usadas para aumentar PrintCapabilities, validar PrintTickets e lidar com a conversão de PrintTicket em DEVMODE e vice-versa. No entanto, as restrições de JavaScript têm algumas limitações. Veja a seguir uma lista das principais limitações:

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

• Os recursos e opções adicionados usando CompletePrintCapabilities não são persistidos no DEVMODE público.

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

Dessa forma, recomendamos que as restrições JavaScript sejam usadas somente 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 Script baseado em 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 em Windows na lista. Se nenhum erro for lançado, 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 de JavaScript disponíveis publicamente também podem ser valiosas como auxiliares 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 de teste/depuração recomendada. 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 JavaScript usando estas APIs públicas: PTGetPrintCapabilities, PTConvertDevModeToPrintTicket, PTConvertPrintTicketToDevMode, e PTMergeAndValidatePrintTicket.

O aplicativo de teste sozinho é 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 Visual Studio Team Test

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

É importante observar que, se o arquivo de origem não for analisado, o depurador não será invocado e parecerá que o ambiente de depuração falhou. Se o arquivo de origem não for analisado, 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 no computador de teste

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

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

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

5. Neste momento, o "Depurador Just-In-Time do Visual Studio" aparecerá dizendo "Ocorreu uma exceção sem tratamento em <seu aplicativo>"

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

7. Escolha Depurar, então Anexar ao Processo.

8. Na caixa de diálogo Anexar ao Processo, certifique-se de que Anexar a: esteja 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 "Depurador Just-In-Time do Visual Studio" e clique em "Não"

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

APIs de restrição 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

• completePrintCapabilities

• convertDevModeToPrintTicket

• convertPrintTicketToDevMode

Função validatePrintTicket

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

sintaxe validatePrintTicket

function validatePrintTicket(printTicket, scriptContext)

Parâmetros validatePrintTicket

• printTicket

  [in][out] O objeto IPrintSchemaTicket a ser validado.

• scriptContext

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

valor de retorno validatePrintTicket

função completePrintCapabilities

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

sintaxe completePrintCapabilities

function completePrintCapabilities(printTicket, scriptContext, printCapabilities)

parâmetros completePrintCapabilities

• printTicket

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

• scriptContext

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

• printCapabilities

  [in][out] O objeto IPrintSchemaCapabilities que representa o objeto PrintCapabilities base que foi gerado pelo módulo de configuração.

valor retornado completePrintCapabilities

Nenhum.

função convertDevModeToPrintTicket

Essa API é chamada para converter valores do recipiente 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 convertDevModeToPrintTicket

• devModeProperties

[in] O objeto IPrinterScriptablePropertyBag que representa o Recipiente de Propriedades DEVMODE.

• scriptContext

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

• printTicket

  [in][out] O objeto IPrintSchemaTicket que representa o PrintTicket.

valor retornado convertDevModeToPrintTicket

Nenhum.

função convertPrintTicketToDevMode

Esta API é chamada para converter valores de um PrintTicket no conjunto de propriedades DEVMODE. Isto é análogo em função à API IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode, exceto que esta 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)

parâmetros convertPrintTicketToDevMode

• printTicket

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

• scriptContext

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

• devModeProperties

  [in][out] O objeto IPrinterScriptablePropertyBag que representa o Recipiente de Propriedades DEVMODE.

valor retornado convertPrintTicketToDevMode

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 dão suporte apenas a um subconjunto do namespace Palavras-chave do Esquema de Impressão. Como resultado, a Microsoft não recomenda o uso de restrições entre os recursos com suporte na caixa de diálogo de impressão do Windows 8 ou na interface do usuário de preferências de impressão e os recursos que não estão nessa interface do usuário, pois os usuários não terão oportunidade de resolver essas restrições.

Por exemplo, se a opção PageMediaType chamada Photo for restrita a funcionar apenas com um valor PageResolution de 1200 dpi, os usuários nunca poderão escolher o tipo de mídia Photo. Em casos como esse, é melhor corresponder à intenção do usuário (mídia de foto) 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 haverá nenhum requisito de que um arquivo seja fornecido. Se um driver utilizar restrições JavaScript para apenas um subconjunto dos pontos de entrada (por exemplo, validatePrintTicket), os outros pontos de entrada deverão ser totalmente omitidos do arquivo JavaScript.