Função SetPrinter
A função SetPrinter define os dados de uma impressora especificada ou define o estado da impressora especificada pausando a impressão, retomando a impressão ou limpando todos os trabalhos de impressão.
Sintaxe
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
Parâmetros
-
hPrinter [in]
-
Um identificador para a impressora. Use a função OpenPrinter, OpenPrinter2 ou AddPrinter para recuperar um identificador de impressora.
-
Nível [in]
-
O tipo de dados que a função armazena no buffer apontado pelo pPrinter. Se o parâmetro Command não for igual a zero, o parâmetro Level deverá ser zero.
Esse valor pode ser 0, 2, 3, 4, 5, 6, 7, 8 ou 9.
-
pPrinter [in]
-
Um ponteiro para um buffer que contém dados a serem definidos para a impressora ou que contém informações para o comando especificado pelo parâmetro Command . O tipo de dados no buffer é determinado pelo valor de Level.
Nível Estrutura - 0
Se o parâmetro Command for PRINTER_CONTROL_SET_STATUS, pPrinter deverá conter um valor DWORD que especifique a nova impressora status a ser definida. Para obter uma lista dos possíveis valores de status, consulte o membro Status da estrutura PRINTER_INFO_2. Observe que PRINTER_STATUS_PAUSED e PRINTER_STATUS_PENDING_DELETION não são valores de status válidos a serem definidos.
Se Level for 0, mas o parâmetro Command não for PRINTER_CONTROL_SET_STATUS, pPrinter deverá ser NULL.- 2
Uma estrutura PRINTER_INFO_2 que contém informações detalhadas sobre a impressora. - 3
Uma estrutura PRINTER_INFO_3 que contém as informações de segurança da impressora. - 4
Uma estrutura PRINTER_INFO_4 que contém informações mínimas da impressora, incluindo o nome da impressora, o nome do servidor e se a impressora é remota ou local. - 5
Uma estrutura PRINTER_INFO_5 que contém informações de impressora, como atributos de impressora e configurações de tempo limite. - 6
Uma estrutura PRINTER_INFO_6 especificando o valor status de uma impressora. - 7
Uma estrutura PRINTER_INFO_7 . O membro dwAction dessa estrutura indica se SetPrinter deve publicar, cancelar a publicação, publicar novamente ou atualizar os dados da impressora no serviço de diretório. - 8
Uma estrutura PRINTER_INFO_8 especificando as configurações de impressora padrão global. - 9
Uma estrutura PRINTER_INFO_9 especificando as configurações de impressora padrão por usuário. -
Comando [in]
-
a ação a ser executada.
Se o parâmetro Level for diferente de zero, defina o valor desse parâmetro como zero. Nesse caso, a impressora mantém seu estado atual e a função reconfigura os dados da impressora conforme especificado pelos parâmetros Level e pPrinter .
Se o parâmetro Level for zero, defina o valor desse parâmetro como um dos valores a seguir.
Valor Significado - PRINTER_CONTROL_PAUSE
Pause a impressora. - PRINTER_CONTROL_PURGE
Exclua todos os trabalhos de impressão na impressora. - PRINTER_CONTROL_RESUME
Retomar uma impressora pausada. - PRINTER_CONTROL_SET_STATUS
Defina o status da impressora.
Defina o parâmetro pPrinter como um ponteiro para um valor DWORD que especifica a nova impressora status.
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.
Se Level for 7 e a ação de publicação falhar, SetPrinter retornará ERROR_IO_PENDING e tentará concluir a ação em segundo plano. Se Level for 7 e a ação de atualização falhar, SetPrinter retornará ERROR_FILE_NOT_FOUND.
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.
Não é possível usar SetPrinter para alterar a impressora padrão.
Para modificar as configurações atuais da impressora, chame a função GetPrinter para recuperar as configurações atuais em uma estrutura PRINTER_INFO_2 , modifique os membros dessa estrutura conforme necessário e, em seguida, chame SetPrinter.
A função SetPrinter ignora os membros pServerName, AveragePPM, Status e cJobs de uma estrutura PRINTER_INFO_2 .
Pausar uma impressora suspende o agendamento de todos os trabalhos de impressão para essa impressora, exceto para o único trabalho de impressão que pode estar sendo impresso no momento. Os trabalhos de impressão podem ser enviados para uma impressora pausada, mas nenhum trabalho será agendado para impressão nessa impressora até que a impressão seja retomada. Se uma impressora estiver desmarcada, todos os trabalhos de impressão dessa impressora serão excluídos, exceto para o trabalho de impressão atual.
Se você usar SetPrinter para modificar a estrutura DEVMODE padrão de uma impressora (definindo globalmente os padrões da impressora), primeiro chame a função DocumentProperties para validar a estrutura DEVMODE .
Para as estruturas PRINTER_INFO_2 e PRINTER_INFO_3 que contêm um ponteiro para um descritor de segurança, a função pode definir apenas os componentes do descritor de segurança que o chamador tem permissão para modificar. Para definir componentes específicos do descritor de segurança, você deve especificar os direitos de acesso necessários ao chamar a função OpenPrinter ou OpenPrinter2 para recuperar um identificador para a impressora. A tabela a seguir mostra os direitos de acesso necessários para modificar os vários componentes do descritor de segurança.
| Permissão de acesso | Componente do descritor de segurança |
|---|---|
| WRITE_OWNER | Proprietário Grupo primário |
| WRITE_DAC | DACL (lista de controle de acesso discricionário) |
| ACCESS_SYSTEM_SECURITY | SACL (lista de controle de acesso do sistema) |
Se o descritor de segurança contiver um componente que o chamador não tem o direito de acesso de modificar, o SetPrinter falhará. Esses componentes de um descritor de segurança que você não deseja modificar devem ser NULL ou não estar presentes, conforme apropriado. Se você não quiser modificar o descritor de segurança e estiver chamando SetPrinter com uma estrutura PRINTER_INFO_2 , defina o membro pSecurityDescriptor dessa estrutura como NULL.
O ICF (Firewall de Conexão com a Internet) bloqueia as portas da impressora por padrão, mas uma exceção para o Compartilhamento de Arquivos e Impressão pode ser habilitada. Se SetPrinter for chamado por um administrador de computador, ele habilitará a exceção. Se ele for chamado por um não administrador e a exceção ainda não tiver sido habilitada, a chamada falhará.
Você pode usar o nível 7 com a estrutura PRINTER_INFO_7 para publicar, cancelar a publicação ou atualizar dados de serviço de diretório para a impressora. Os dados de serviço de diretório de uma impressora incluem todos os dados armazenados sob as chaves SPLDS_* por chamadas para a função SetPrinterDataEx para a impressora. Antes de chamar SetPrinter, defina o membro pszObjectGUID de PRINTER_INFO_7 como NULL e defina o membro dwAction como um dos valores a seguir.
| Valor | Descrição |
|---|---|
|
DSPRINT_PUBLISH |
Publica os dados do serviço de diretório. |
|
DSPRINT_REPUBLISH |
Os dados do serviço de diretório da impressora são não publicados e publicados novamente, atualizando todas as propriedades na impressora publicada. A nova publicação também altera o GUID da impressora publicada. Use esse valor se suspeitar que os dados publicados da impressora foram corrompidos. |
|
DSPRINT_UNPUBLISH |
Cancela a publicação dos dados do serviço de diretório. |
|
DSPRINT_UPDATE |
Atualizações os dados do serviço de diretório. Isso é o mesmo que DSPRINT_PUBLISH, exceto que SetPrinter falhará com ERROR_FILE_NOT_FOUND se a impressora ainda não estiver publicada. Use DSPRINT_UPDATE para atualizar as propriedades publicadas, mas não forçar a publicação. Os drivers de impressora sempre devem usar DSPRINT_UPDATE em vez de DSPRINT_PUBLISH. |
DSPRINT_PENDING não é um valor dwAction válido para SetPrinter.
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 |
|
| Biblioteca |
|
| DLL |
|
| Nomes Unicode e ANSI |
SetPrinterW (Unicode) e SetPrinterA (ANSI) |