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