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	Winspool.h (inclua Windows.h)
Biblioteca	Winspool.lib
DLL	Winspool.drv
Nomes Unicode e ANSI	OpenPrinterW (Unicode) e OpenPrinterA (ANSI)

Confira também

Impressão

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

WritePrinter

ClosePrinter

PRINTER_DEFAULTS

SetJob

SetPrinter

StartDocPrinter