Compartilhar via


Função SetJob

A função SetJob pausa, retoma, cancela ou reinicia um trabalho de impressão em uma impressora especificada. Você também pode usar a função SetJob para definir parâmetros de trabalho de impressão, como a prioridade do trabalho de impressão e o nome do documento.

Você pode usar a função SetJob para dar um comando a um trabalho de impressão ou para definir parâmetros de trabalho de impressão ou para fazer ambos na mesma chamada. O valor do parâmetro Command não afeta como a função usa os parâmetros Level e pJob . Além disso, você pode usar SetJob com JOB_INFO_3 para vincular um conjunto de trabalhos de impressão. Confira Comentários para obter mais informações.

Sintaxe

BOOL SetJob(
  _In_ HANDLE hPrinter,
  _In_ DWORD  JobId,
  _In_ DWORD  Level,
  _In_ LPBYTE pJob,
  _In_ DWORD  Command
);

Parâmetros

hPrinter [in]

Um identificador para o objeto de interesse da impressora. Use a função OpenPrinter, OpenPrinter2 ou AddPrinter para recuperar um identificador de impressora.

JobId [in]

Identificador que especifica o trabalho de impressão. Você obtém um identificador de trabalho de impressão chamando a função AddJob ou a função StartDoc .

Se o parâmetro Level estiver definido como 3, o parâmetro JobId deverá corresponder ao membro JobId da estrutura JOB_INFO_3 apontada por pJob

Nível [in]

O tipo de estrutura de informações de trabalho apontada pelo parâmetro pJob .

Todas as versões do Windows: você pode definir o parâmetro Level como 0, 1 ou 2. Quando você define Level como 0, pJob deve ser NULL. Use esses valores quando não estiver definindo nenhum parâmetro de trabalho de impressão.

Você também pode definir o parâmetro Level como 3.

A partir do Windows Vista: você também pode definir o parâmetro Level como 4.

pJob [in]

Um ponteiro para uma estrutura que define os parâmetros do trabalho de impressão.

Todas as versões do Windows: pJob pode apontar para uma estrutura JOB_INFO_1 ou JOB_INFO_2 .

PJob também pode apontar para uma estrutura JOB_INFO_3 . Você deve ter JOB_ACCESS_ADMINISTER permissão de acesso para os trabalhos especificados pelos membros JobId e NextJobId da estrutura JOB_INFO_3 .

Começando com o Windows Vista: o pJob também pode apontar para uma estrutura JOB_INFO_4 .

Se o parâmetro Level for 0, pJob deverá ser NULL.

Comando [in]

A operação de trabalho de impressão a ser executada. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
JOB_CONTROL_CANCEL
Não use. Para excluir um trabalho de impressão, use JOB_CONTROL_DELETE.
JOB_CONTROL_PAUSE
Pause o trabalho de impressão.
JOB_CONTROL_RESTART
Reinicie o trabalho de impressão. Um trabalho só poderá ser reiniciado se estiver imprimindo.
JOB_CONTROL_RESUME
Retomar um trabalho de impressão em pausa.
JOB_CONTROL_DELETE
Exclua o trabalho de impressão.
JOB_CONTROL_SENT_TO_PRINTER
Usado por monitores de porta para encerrar o trabalho de impressão.
JOB_CONTROL_LAST_PAGE_EJECTED
Usado por monitores de idioma para encerrar o trabalho de impressão.
JOB_CONTROL_RETAIN
Windows Vista e posterior: mantenha o trabalho na fila depois que ele for impresso.
JOB_CONTROL_RELEASE
Windows Vista e posterior: libere o trabalho de impressão.

Você pode usar a mesma chamada para a função SetJob para definir parâmetros de trabalho de impressão e dar um comando a um trabalho de impressão. Portanto, Command não precisará ser 0 se você estiver definindo parâmetros de trabalho de impressão, embora possa ser.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um valor diferente de zero.

Se a função falhar, o valor retornado será zero.

Comentários

Observação

Essa é uma função de bloqueio ou síncrona e pode não retornar imediatamente. A rapidez com que essa função retorna depende de fatores de tempo de execução, como status de rede, configuração do servidor de impressão e fatores de implementação de driver de impressora que são difíceis de prever ao escrever um aplicativo. Chamar essa função de um thread que gerencia a interação com a interface do usuário pode fazer com que o aplicativo pareça não responder.

Você pode usar a função SetJob para definir vários parâmetros de trabalho de impressão fornecendo um ponteiro para uma estrutura de JOB_INFO_1, JOB_INFO_2, JOB_INFO_3 ou JOB_INFO_4 que contém os dados necessários.

Para remover ou excluir todos os trabalhos de impressão de uma impressora específica, chame a função SetPrinter com seu parâmetro Command definido como PRINTER_CONTROL_PURGE.

Os seguintes membros de uma estrutura JOB_INFO_1, JOB_INFO_2 ou JOB_INFO_4 são ignorados em uma chamada para SetJob: JobId, pPrinterName, pMachineName, pUserName, pDrivername, Size, Submitted, Time e TotalPages.

Você deve ter PRINTER_ACCESS_ADMINISTER permissão de acesso para uma impressora para alterar a posição de um trabalho de impressão na fila de impressão.

Se você não quiser definir a posição de um trabalho de impressão na fila de impressão, defina o membro Position da estrutura JOB_INFO_1, JOB_INFO_2 ou JOB_INFO_4 para JOB_POSITION_UNSPECIFIED.

Use a função SetJob com a estrutura JOB_INFO_3 para vincular um conjunto de trabalhos de impressão (também conhecido como cadeia). Isso é útil em situações em que um único documento consiste em várias partes que você deseja renderizar separadamente. Para imprimir os trabalhos A, B, C e D em ordem, chame SetJob com JOB_INFO_4 para vincular A a B, B a C e C a D.

Se você vincular trabalhos de impressão, observe o seguinte:

  • Os trabalhos podem ser adicionados ao início ou ao fim de uma cadeia.

  • Todos os trabalhos na cadeia devem ter o mesmo tipo de dados.

  • A cadeia deve estar completamente vinculada antes do início do spooling, caso contrário, o spooler poderá imprimir e excluir trabalhos em spool antes de vinculá-los a todos. Há duas maneiras de impedir que a cadeia imprima prematuramente:

    • Pause o primeiro trabalho na cadeia até que a cadeia esteja completamente vinculada. O estado pausado do primeiro trabalho rege o estado de todos os trabalhos na cadeia.
    • Mantenha o primeiro trabalho incompleto, ou seja, não chame EndDoc ou ScheduleJob para o primeiro trabalho. No entanto, se 'print while spooling' estiver habilitado (o padrão), esse método bloqueará a porta enquanto a cadeia for criada, o que também impedirá a impressão de trabalhos não relacionados.
  • O aplicativo deve lidar com o caso em que o usuário exclui um trabalho na cadeia antes que a cadeia termine de imprimir. GetLastError retorna INVALID_PARAMETER quando um JobID não existe.

Requisitos

Requisito Valor
Cliente mínimo com suporte
Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte
Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho
WinSpool.h (inclua Windows.h)
Biblioteca
WinSpool.lib
DLL
WinSpool.drv
Nomes Unicode e ANSI
SetJobW (Unicode) e SetJobA (ANSI)

Confira também

Impressão

Funções da API do Spooler de impressão

Addjob

Getjob

OpenPrinter

SetPrinter

JOB_INFO_1

JOB_INFO_2

JOB_INFO_3

JOB_INFO_4