Compartilhar via

Função StartXpsPrintJob1 (xpsprint.h)

  • Artigo

[StartXpsPrintJob1 não tem suporte e pode ser alterado ou indisponível no futuro. ]

Cria um trabalho de impressão para enviar conteúdo de documento XPS para uma impressora. Essa função cria um caminho de impressão mais eficiente do que StartXpsPrintJob.

Sintaxe

HRESULT StartXpsPrintJob1(
  [in]            LPCWSTR             printerName,
  [in, optional]  LPCWSTR             jobName,
  [in, optional]  LPCWSTR             outputFileName,
  [in, optional]  HANDLE              progressEvent,
  [in, optional]  HANDLE              completionEvent,
  [out, optional] IXpsPrintJob        **xpsPrintJob,
  [out]           IXpsOMPackageTarget **printContentReceiver
);

Parâmetros

[in] printerName

O nome da impressora à qual esse trabalho será associado.

[in, optional] jobName

Um nome de trabalho especificado pelo usuário a ser associado a esse trabalho. Você poderá definir esse parâmetro como NULL se o trabalho não exigir um nome separado especificado pelo usuário.

[in, optional] outputFileName

O nome do arquivo ou porta no qual a saída desse trabalho deve ser redirecionada. Definir esse valor fará com que a saída do trabalho de impressão seja direcionada para o arquivo ou porta especificado. Para enviar o trabalho de impressão para a impressora especificada por printerName, defina esse parâmetro como NULL.

[in, optional] progressEvent

Um identificador de evento que é sinalizado quando ocorre uma das seguintes alterações no trabalho de impressão:

  • Uma ID de trabalho é atribuída ao trabalho de impressão
  • A impressão de uma página foi concluída
  • A impressão de um documento foi concluída
  • O trabalho de impressão foi cancelado ou terminou devido a um erro
Nota Esse evento não será sinalizado até que o aplicativo inicie o envio de dados para o trabalho de impressão.
 

A API de Impressão XPS não redefine esse evento , que é responsabilidade do chamador.

Defina esse parâmetro como NULL se você não quiser ser notificado sobre o progresso.

[in, optional] completionEvent

Um identificador de evento que é sinalizado quando o trabalho de impressão é concluído. É garantido que esse evento seja sinalizado exatamente uma vez por chamada StartXpsPrintJob1 . A API de Impressão XPS não redefine esse evento , que é responsabilidade do chamador.

Defina esse parâmetro como NULL se não quiser ser notificado sobre a conclusão.

[out, optional] xpsPrintJob

Um ponteiro para a interface IXpsPrintJob que representa o trabalho de impressão que StartXpsPrintJob1 criou. Para obter o status do trabalho de impressão ou cancelá-lo, use a interface IXpsPrintJob. Defina esse parâmetro como NULL se você não precisar dele.

[out] printContentReceiver

Um ponteiro para a interface IXpsOMPackageTarget que essa função criou. Esse parâmetro é necessário e você não pode defini-lo como NULL.

Para enviar conteúdo do documento para o trabalho de impressão que essa função criou, use a interface IXpsOMPackageWriter que você cria chamando o método CreateXpsOMPackageWriter da interface IXpsOMPackageTarget retornada em xpsOMPackageTarget.

Retornar valor

O método retorna um HRESULT. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir.

Código de retorno Descrição
S_OK
 O método foi bem-sucedido.
E_POINTER
 printerName ou xpsOMPackageTarget é NULL.
E_OUTOFMEMORY
 Memória insuficiente para criar um novo objeto IXpsPrintJob .

Comentários

StartXpsPrintJob1 é uma função assíncrona e, portanto, pode retornar antes que o spooler de impressão crie ou inicie um trabalho de impressão.

Não use as interfaces retornadas em xpsPrintJob e xpsOMPackageTarget até que StartXpsPrintJob1 tenha retornado com êxito.

Depois que o chamador começa a enviar dados, é uma boa prática de programação monitorar os eventos de progresso que são sinalizados para o evento que é passado em andamentoEvent. Quando o evento é sinalizado, o chamador deve chamar IXpsPrintJob::GetJobStatus para obter o status atual do trabalho de impressão.

Quando o trabalho de impressão é concluído, com êxito ou não, o evento que é passado em completionEvent é sinalizado apenas uma vez. Para evitar a perda de dados, é uma boa prática de programação para o chamador monitorar o evento de conclusão e garantir que nem o thread nem o aplicativo que criou o trabalho de impressão sejam encerrados até que o evento de conclusão seja sinalizado.

Os estados de trabalho não são armazenados nem enfileirados pelo spooler de impressão. Como o processamento de trabalho não aguarda a leitura do status após a sinalização dos eventos, o chamador pode perder algumas alterações de estado, dependendo do atraso entre a hora em que o aplicativo recebeu a notificação de alteração e a hora em que chamou IXpsPrintJob::GetJobStatus. Para receber notificações subsequentes, o aplicativo deve redefinir o evento de progresso depois de receber a notificação.

Se uma chamada para StartXpsPrintJob1 falhar, o spooler de impressão atualizará o trabalho status, sinalizará os eventos de conclusão e progresso e retornará um código de erro. Para obter o status do trabalho de impressão com falha, chame IXpsPrintJob::GetJobStatus.

StartXpsPrintJob1 chama DuplicateHandle em completionEvent e progressEvent para garantir que eles permaneçam válidos durante o tempo de vida do trabalho. Como o spooler de impressão está usando um identificador duplicado para os eventos, o chamador pode fechar esses identificadores a qualquer momento sem afetar a execução do trabalho. No entanto, recomendamos que o chamador feche esses identificadores somente após o evento completionEvent ter sido sinalizado e o chamador o tenha observado.

Nota Quando o aplicativo é impresso em um arquivo, o aplicativo é responsável por fornecer o valor a ser passado no parâmetro outputFileName para operações de impressão em arquivo. Para imprimir em uma impressora que usa um driver que é gerado para a porta ARQUIVO: , o chamador deve recuperar o nome do arquivo do usuário exibindo a caixa de diálogo de arquivo comum.
 

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 7 com SP1, Windows Vista e Suplemento de Atualização de Plataforma para Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 R2 com SP1, Windows Server 2008 e Suplemento de Atualização de Plataforma para Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho xpsprint.h
Biblioteca XpsPrint.lib
DLL XpsPrint.dll

Confira também

Documentos

IXpsOMPackageTarget

IXpsOMPackageWriter

Especificação de Papel XML