Função OpenPrinter
A função OpenPrinter recupera um identificador para a impressora ou servidor de impressão especificado ou outros tipos de identificadores no subsistema de impressão.
Sintaxe
BOOL OpenPrinter(
_In_ LPTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault
);
Parâmetros
-
pPrinterName [in]
-
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome da impressora ou servidor de impressão, o objeto da impressora, o XcvMonitor ou o XcvPort.
Para um objeto de impressora, use: PrinterName, Job xxxx. Para um XcvMonitor, use: ServerName, XcvMonitor MonitorName. Para um XcvPort, use: ServerName, XcvPort PortName.
Se FOR NULL, ele indicará o servidor de impressora local.
-
phPrinter [out]
-
Um ponteiro para uma variável que recebe um identificador (não thread-safe) para a impressora aberta ou o objeto do servidor de impressão.
O parâmetro phPrinter pode retornar um identificador Xcv para uso com a função XcvData. Para obter mais informações sobre XcvData, consulte o DDK.
-
pDefault [in]
-
Um ponteiro para uma estrutura PRINTER_DEFAULTS . Esse valor pode ser NULL.
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
Não chame esse método em DllMain.
Observação
Um identificador obtido para uma impressora remota por uma chamada para OpenPrinter para uma impressora remota acessa a impressora por meio de um cache local no serviço de spooler de impressão. Esse cache não é preciso em tempo real. Para obter dados precisos, substitua a chamada OpenPrinter por OpenPrinter2 por pOptions.dwFlags definido como PRINTER_OPTION_NO_CACHE. Observe que apenas OpenPrinter2W é funcional. A função retorna um identificador de impressora que usa outras chamadas à API de Impressão e ignora o cache local. Esse método é bloqueado enquanto aguarda a comunicação de rede com a impressora remota, portanto, ele 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 da interface do usuário pode fazer com que o aplicativo pareça não responder.
Observação
Um identificador obtido por uma chamada para OpenPrinter para uma impressora remota acessará a impressora por meio de um cache local no serviço de spooler de impressão. Esse cache não é, por design, preciso em tempo real. Se você precisar obter dados precisos, substitua a chamada OpenPrinter por OpenPrinter2 por pOptions.dwFlags definido comoPRINTER_OPTION_NO_CACHE. Observe que apenas OpenPrinter2W é funcional. Fazendo isso, a função retorna um identificador de impressora que faz outras chamadas à API de Impressão para ignorar o cache local. Observe que essa abordagem será bloqueada enquanto aguarda a comunicação de rede de ida e volta para a impressora remota, portanto, ela 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 implementação de driver de impressora – fatores difíceis de prever ao escrever um aplicativo. Portanto, 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 identificador apontado pelo phPrinter 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.
O parâmetro pDefault permite que você especifique os valores de tipo de dados e modo de dispositivo usados para imprimir documentos enviados pela função StartDocPrinter . No entanto, você pode substituir esses valores usando a função SetJob depois que um documento for iniciado.
As configurações DEVMODE definidas na estrutura PRINTER_DEFAULTS do parâmetro pDefault não são usadas quando o valor do membro pDatatype da estrutura DOC_INFO_1 que foi passada no parâmetro pDocInfo da chamada StartDocPrinter é "RAW". Quando um documento de alto nível (como um arquivo Adobe PDF ou Microsoft Word) ou outros dados de impressora (como PCL, PS ou HPGL) é enviado diretamente para uma impressora com pDatatype definido como "RAW", o documento deve descrever totalmente as configurações de trabalho de impressão no estilo DEVMODE no idioma compreendido pelo hardware.
Você pode chamar a função OpenPrinter para abrir um identificador para um servidor de impressão ou para determinar os direitos de acesso que um cliente tem a um servidor de impressão. Para fazer isso, especifique o nome do servidor de impressão no parâmetro pPrinterName , defina os membros pDatatype e pDevMode da estrutura PRINTER_DEFAULTS como NULL e defina o membro DesiredAccess para especificar um valor de máscara de acesso do servidor, como SERVER_ALL_ACCESS. Quando terminar com o identificador, passe-o para a função ClosePrinter para fechá-lo.
Use o membro DesiredAccess da estrutura PRINTER_DEFAULTS para especificar os direitos de acesso necessários para a impressora. Os direitos de acesso podem ser um dos seguintes. (Se pDefault for NULL, os direitos de acesso serão PRINTER_ACCESS_USE.)
| Valor de Acesso Desejado | Significado |
|---|---|
| PRINTER_ACCESS_ADMINISTER | Para executar tarefas administrativas, como as fornecidas pelo SetPrinter. |
| PRINTER_ACCESS_USE | Para executar operações básicas de impressão. |
| PRINTER_ALL_ACCESS | Para executar todas as tarefas administrativas e operações básicas de impressão, exceto SYNCHRONIZE (consulte Direitos de acesso padrão. |
| PRINTER_ACCESS_MANAGE_LIMITED | Para executar tarefas administrativas, como as fornecidas por SetPrinter e SetPrinterData. Esse valor está disponível a partir de Windows 8.1. |
| valores de segurança genéricos, como WRITE_DAC | Para permitir direitos de acesso de controle específicos. Confira Direitos de Acesso Padrão. |
Se um usuário não tiver permissão para abrir uma impressora ou servidor de impressão especificado com o acesso desejado, a chamada openprinter falhará com um valor retornado igual a zero e GetLastError retornará o valor ERROR_ACCESS_DENIED.
Exemplos
Para obter um programa de exemplo que usa essa função, consulte Como imprimir usando a API de impressão GDI.
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 |
OpenPrinterW (Unicode) e OpenPrinterA (ANSI) |