Compartilhar via


Função AddPrinter

A função AddPrinter adiciona uma impressora à lista de impressoras com suporte para um servidor especificado.

Sintaxe

HANDLE AddPrinter(
  _In_ LPTSTR *pName,
  _In_ DWORD  Level,
  _In_ LPBYTE pPrinter
);

Parâmetros

pName [in]

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do servidor no qual a impressora deve ser instalada. Se essa cadeia de caracteres for NULL, a impressora será instalada localmente.

Nível [in]

A versão da estrutura para a qual pPrinter aponta. Esse valor deve ser 2.

pPrinter [in]

Um ponteiro para uma estrutura PRINTER_INFO_2 que contém informações sobre a impressora. Você deve especificar valores não NULL para os membros pPrinterName, pPortName, pDriverName e pPrintProcessor dessa estrutura antes de chamar AddPrinter.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um identificador (não thread-safe) para um novo objeto de impressora. Quando terminar de usar o identificador, passe-o para a função ClosePrinter para fechá-lo.

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

Comentários

Não chame esse método em DllMain.

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.

O chamador deve ter o SeLoadDriverPrivilege.

O identificador retornado não é thread-safe. Se os chamadores precisarem usá-lo simultaneamente em vários threads, eles deverão fornecer acesso de sincronização personalizado ao identificador da impressora usando as Funções de Sincronização. Para evitar escrever código personalizado, o aplicativo pode abrir um identificador de impressora em cada thread, conforme necessário.

Veja a seguir os membros da estrutura PRINTER_INFO_2 que podem ser definidos antes que a função AddPrinter seja chamada:

  • Atributos
  • pPrintProcessor
  • DefaultPriority
  • Prioridade
  • pComment
  • pSecurityDescriptor
  • pDatatype
  • pSepFile
  • pDevMode
  • pShareName
  • pLocation
  • StartTime
  • pParameters
  • UntilTime

Os membros Status, cJobs e AveragePPM da estrutura PRINTER_INFO_2 são reservados para uso pela função GetPrinter . Eles não devem ser definidos antes de chamar AddPrinter.

Se pSecurityDescriptor for NULL, o sistema atribuirá um descritor de segurança padrão à impressora. O descritor de segurança padrão tem as permissões a seguir.

Valor Descrição
Administradores e Usuários Avançados Controle total na fila de impressão. Isso significa que os membros desses grupos podem imprimir, gerenciar a fila (podem excluir a fila, alterar qualquer configuração da fila, incluindo o descritor de segurança) e gerenciar os trabalhos de impressão de todos os usuários (excluir, pausar, retomar, reiniciar trabalhos). Observe que os Usuários do Power não existem antes do Windows XP Professional.
Criador/Proprietário Pode gerenciar trabalhos próprios. Isso significa que o usuário que envia trabalhos pode gerenciar (excluir, pausar, retomar, reiniciar) seus próprios trabalhos.
Todos Execute e controle de leitura padrão. Isso significa que os membros do grupo todos podem imprimir e ler propriedades da fila de impressão.

Depois que um aplicativo cria um objeto de impressora com a função AddPrinter , ele deve usar a função PrinterProperties para especificar as configurações corretas para o driver de impressora associado ao objeto de impressora.

A função AddPrinter retornará um erro se já existir um objeto de impressora com o mesmo nome, a menos que esse objeto esteja marcado como exclusão pendente. Nesse caso, a impressora existente não é excluída e os parâmetros de criação AddPrinter são usados para alterar as configurações de impressora existentes (como se o aplicativo tivesse usado a função SetPrinter ).

Use a função EnumPrintProcessors para enumerar o conjunto de processadores de impressão instalados em um servidor. Use a função EnumPrintProcessorDatatypes para enumerar o conjunto de tipos de dados aos quais um processador de impressão dá suporte. Use a função EnumPorts para enumerar o conjunto de portas disponíveis. Use a função EnumPrinterDrivers para enumerar os drivers de impressora instalados.

O chamador da função AddPrinter deve ter SERVER_ACCESS_ADMINISTER acesso ao servidor no qual a impressora deve ser criada. O identificador retornado pela função terá PRINTER_ALL_ACCESS permissão e poderá ser usado para executar operações administrativas na impressora.

Se a função DrvPrinterEvent for passada pelo sinalizador PRINTER_EVENT_FLAG_NO_UI, o driver não deverá usar uma chamada de interface do usuário durante DrvPrinterEvent. Para fazer trabalhos relacionados à interface do usuário, o instalador deve usar a entrada VendorSetup no arquivo .inf da impressora ou, para dispositivos Plug and Play, o instalador pode usar um co-instalador específico do dispositivo. Para obter mais informações sobre VendorSetup, consulte o DDK (Microsoft Windows Driver Development Kit).

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 é habilitada quando você executa o AddPrinter.

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
AddPrinterW (Unicode) e AddPrinterA (ANSI)

Confira também

Impressão

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

ClosePrinter

DeletePrinter

EnumPorts

EnumPrinterDrivers

EnumPrintProcessors

EnumPrintProcessorDatatypes

GetPrinter

PRINTER_INFO_2

PrinterProperties

SetPrinter