Função StartXpsPrintJob1 (xpsprint.h)

[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

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.

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.

Requisitos

Confira também

Documentos

IXpsOMPackageTarget

IXpsOMPackageWriter

Especificação de Papel XML