Função StartXpsPrintJob (xpsprint.h)

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

Inicia a impressão de um fluxo de documentos XPS em uma impressora.

Sintaxe

HRESULT StartXpsPrintJob(
  [in]  LPCWSTR            printerName,
  [in]  LPCWSTR            jobName,
  [in]  LPCWSTR            outputFileName,
  [in]  HANDLE             progressEvent,
  [in]  HANDLE             completionEvent,
  [in]  UINT8              *printablePagesOn,
  [in]  UINT32             printablePagesOnCount,
  [out] IXpsPrintJob       **xpsPrintJob,
  [out] IXpsPrintJobStream **documentStream,
  [out] IXpsPrintJobStream **printTicketStream
);

Parâmetros

[in] printerName

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

[in] jobName

Um nome de trabalho especificado pelo usuário a ser associado a esse trabalho. Se o trabalho não exigir um nome separado especificado pelo usuário, esse parâmetro poderá ser definido como NULL.

[in] 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, esse parâmetro deve ser definido como NULL.

[in] progressEvent

Um identificador de evento que é sinalizado quando ocorrem as 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.

Se nenhuma notificação de progresso for necessária, esse parâmetro poderá ser definido como NULL.

[in] completionEvent

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

Se nenhuma notificação de conclusão for necessária, esse parâmetro poderá ser definido como NULL.

[in] printablePagesOn

O parâmetro faz referência a uma matriz UINT8 cujos elementos especificam um subconjunto das páginas de um documento a ser impresso. Conforme mostrado na tabela a seguir, o valor de cada elemento indica se a página deve ser impressa.

Os eventos de progresso serão sinalizados apenas para as páginas designadas para impressão.

Os elementos na matriz representam todas as páginas designadas para impressão em todos os documentos do pacote XPS. Por exemplo, se o pacote contiver dois documentos com três páginas cada, a matriz mostrada na tabela a seguir designará a impressão das páginas 0 e 2 do documento 1 e as páginas 0 e 2 do documento 2.

Se printablePagesOn for NULL, todas as páginas do pacote serão impressas.

Se printablePagesOn tiver mais elementos do que há páginas no pacote, os elementos supérfluos serão ignorados.

Se a matriz tiver menos elementos do que há páginas no documento, o valor do último elemento de matriz da matriz será aplicado às páginas restantes. Essa regra facilita a especificação de um intervalo aberto ou que obtém apenas algumas páginas de um documento grande impresso.

[in] printablePagesOnCount

O número de elementos na matriz referenciado por printablePagesOn. Se printablePagesOn for NULL, esse parâmetro será ignorado.

[out] xpsPrintJob

Um ponteiro para a interface IXpsPrintJob que representa o trabalho de impressão criado por StartXpsPrintJob. Para obter o status do trabalho de impressão ou cancelá-lo, use a interface IXpsPrintJob. Se um IXpsPrintJob não for necessário, esse parâmetro poderá ser definido como NULL.

[out] documentStream

Um ponteiro para a interface IXpsPrintJobStream na qual o chamador grava o documento XPS a ser impresso por esse trabalho de impressão.

[out] printTicketStream

Um ponteiro para a interface IXpsPrintJobStream usada pelo chamador para gravar o tíquete de impressão no nível do trabalho que será associado a esse trabalho. Se esse parâmetro for definido como NULL, os tíquetes de impressão (se houver) do documento XPS gravado no documentStream serão usados.

Retornar valor

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

Comentários

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

As interfaces retornadas em xpsPrintJob, documentStream e printTicketStream não devem ser usadas até que StartXpsPrintJob tenha retornado com êxito.

Depois que o chamador começar a enviar dados, ele deverá 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, seja com êxito ou não, o evento que é passado em completionEvent é sinalizado uma vez e apenas uma vez. Para evitar a perda de dados, o chamador deve monitorar esse evento e o thread ou o aplicativo do chamador não deve ser encerrado até que o evento tenha sido 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 StartXpsPrintJob falhar, o trabalho status será atualizado, os eventos de conclusão e progresso serão sinalizados e um código de erro será retornado. Para obter o status do trabalho de impressão com falha, chame IXpsPrintJob::GetJobStatus.

StartXpsPrintJob 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, é possível que o chamador feche esses identificadores a qualquer momento sem afetar a execução do trabalho. O procedimento recomendado, no entanto, é que o chamador feche esses identificadores somente após o evento completionEvent ter sido sinalizado e observado pelo chamador.

As interfaces IXpsPrintJobStream retornadas em documentStream e printTicketStream são fluxos somente gravação que não permitem a busca, mas que podem ser fechados. O chamador grava o documento XPS e imprime o conteúdo do tíquete nesses fluxos e chama Fechar depois que todos os dados forem gravados. As chamadas para o método Write dos fluxos são thread-safe; no entanto, se essas chamadas forem feitas de threads diferentes, elas não terão a garantia de serem confirmadas no fluxo na ordem esperada.

Requisitos

Confira também

Documentos

StartXpsPrintJob1

Especificação de Papel XML