Função OpenPrinter2
Recupera um identificador para a impressora, o servidor de impressão ou outros tipos de identificadores especificados no subsistema de impressão, ao mesmo tempo em que define algumas das opções da impressora.
Sintaxe
BOOL OpenPrinter2(
_In_ LPCTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault,
_In_ PPRINTER_OPTIONS pOptions
);
Parâmetros
-
pPrinterName [in]
-
Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o nome da impressora ou do 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.
Windows Vista: Se FOR NULL, ele indicará o servidor de impressão local.
-
phPrinter [out]
-
Um ponteiro para uma variável que recebe um identificador para a impressora aberta ou o objeto do servidor de impressão.
-
pDefault [in]
-
Um ponteiro para uma estrutura PRINTER_DEFAULTS . Esse valor pode ser NULL.
-
pOptions [in]
-
Um ponteiro para uma estrutura PRINTER_OPTIONS . 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. Para obter informações de erro estendidas, chame GetLastError.
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 do driver de impressora que são difíceis de prever ao gravar 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.
A versão ANSI dessa função não é implementada e retorna ERROR_NOT_SUPPORTED.
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.
Você pode chamar a função OpenPrinter2 para abrir um identificador para um servidor de impressão ou para determinar os direitos de acesso do cliente 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 de usar o identificador, passe-o para a função ClosePrinter para fechá-la.
Use o membro DesiredAccess da estrutura PRINTER_DEFAULTS para especificar os direitos de acesso necessários. Os direitos de acesso podem ser um dos seguintes.
| 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. Consulte Direitos de Acesso Padrão. |
Se um usuário não tiver permissão para abrir uma impressora especificada ou um servidor de impressão com o acesso desejado, a chamada OpenPrinter2 falhará e GetLastError retornará o valor ERROR_ACCESS_DENIED.
Quando pPrinterName é uma impressora local, o OpenPrinter2 ignora todos os valores dos dwFlags que a estrutura PRINTER_OPTIONS apontou para o uso de pOptions, exceto PRINTER_OPTION_CLIENT_CHANGE. Se o último for passado, o OpenPrinter2 retornará ERROR_ACCESS_DENIED. Assim, ao abrir uma impressora local, o OpenPrinter2 não oferece nenhuma vantagem sobre o OpenPrinter.
Windows Vista: Os dados da impressora retornados pelo OpenPrinter2 são recuperados de um cache local, a menos que o sinalizador PRINTER_OPTION_NO_CACHE seja definido no campo dwFlags da estrutura PRINTER_OPTIONS referenciada por pOptions.
Exemplos
Neste exemplo, o OpenPrinter2 falha quando PRINTER_ACCESS_MANAGE_LIMITED é passado para a estrutura PRINTER_DEFAULTS e o usuário não tem a permissão apropriada.
// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;
// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
&printer, // Printer handle
&defaults, // Printer defaults
nullptr)); // Printer options
assert(GetLastError() == ERROR_ACCESS_DENIED);
if (printer)
{
ClosePrinter(printer);
}
Para obter um programa de exemplo que mostra como usar essa função, consulte Como imprimir usando a API de impressão GDI.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte |
Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte |
Windows Server 2008 [somente aplicativos da área de trabalho] |
| Cabeçalho |
|
| Biblioteca |
|
| DLL |
|
| Nomes Unicode e ANSI |
OpenPrinter2W (Unicode) e OpenPrinter2A (ANSI) |