Função DrvPrinterEvent (winddiui.h)

A função DrvPrinterEvent de uma interface de impressora é chamada pelo spooler de impressão ao processar eventos específicos da impressora que podem exigir ação do driver da impressora.

Sintaxe

BOOL DrvPrinterEvent(
  [in] LPWSTR pPrinterName,
       int    DriverEvent,
       DWORD  Flags,
       LPARAM lParam
);

Parâmetros

[in] pPrinterName

Ponteiro fornecido pelo chamador para uma cadeia de caracteres de nome de impressora terminada em NULL. O formato de cadeia de caracteres pode ser \Machine\PrinterName para especificar uma impressora remota ou PrinterName para especificar uma impressora local.

DriverEvent

Código de evento fornecido pelo chamador que identifica o evento. Os seguintes códigos de evento são definidos:

Código do evento	Definição
PRINTER_EVENT_ADD_CONNECTION	O spooler acabou de processar uma chamada para sua função AddPrinterConnection , que permite que um usuário cliente se conecte a uma impressora remota criada anteriormente.
PRINTER_EVENT_ATTRIBUTES_CHANGED	Os bits de atributo de uma impressora foram alterados. Em resposta à chamada de um aplicativo para a função SetPrinter , o spooler chama a função DrvPrinterEvent do driver de impressora, passando o código do evento na chamada. Quando esse código de evento é usado, o parâmetro lParam aponta para uma estrutura PRINTER_EVENT_ATTRIBUTES_INFO que descreve os atributos antigos e os novos.
PRINTER_EVENT_CACHE_DELETE	O spooler está excluindo o cache de arquivos do cliente.
PRINTER_EVENT_CACHE_REFRESH	O spooler está atualizando os arquivos armazenados em cache do cliente.
PRINTER_EVENT_CONFIGURATION_CHANGE	Reservado.
PRINTER_EVENT_CONFIGURATION_UPDATE	A configuração da impressora foi alterada. Quando esse código de evento é usado, o parâmetro lParam aponta para uma cadeia de caracteres Unicode que contém uma notificação formatada de acordo com o Esquema de Notificação bidi.
PRINTER_EVENT_DELETE_CONNECTION	O spooler acabou de processar uma chamada para sua função DeletePrinterConnection , que permite que um usuário cliente remova uma conexão de impressora.
PRINTER_EVENT_DELETE	O spooler acabou de processar uma chamada para sua função DeletePrinter , que permite que um administrador exclua uma instância de impressora.
PRINTER_EVENT_INITIALIZE	O spooler acabou de processar uma chamada para sua função AddPrinter , que permite que um administrador disponibilize uma impressora em um servidor ou sua função SetPrinter , que permite que um administrador modifique o estado de uma impressora. Em uma conexão de renderização do lado do cliente, o computador cliente acaba de adicionar a impressora GUID. O evento PRINTER_EVENT_INITIALIZE especifica um valor de parâmetro lParam NULL para chamadas DrvPrinterEvent no Windows Vista e versões anteriores. Para o Windows 7 e versões posteriores, o parâmetro lParam é um identificador de token de usuário. Os drivers de impressão podem usar o identificador de token retornado para consultar dados do usuário ou representar o usuário.

Flags

Sinalizador de bit fornecido pelo chamador, definido da seguinte maneira:

Valor

Definição

PRINTER_EVENT_FLAG_NO_UI

Se definida, a função não deverá exibir uma interface do usuário. Durante a instalação de um processador de impressão, monitor de impressão ou driver de impressora, a única maneira pela qual uma interface do usuário é permitida é por meio do uso da diretiva VendorSetup . Consulte Entradas de arquivo INF da impressora e Operações personalizadas de instalação da impressora para obter mais informações.

Cuidado

A diretiva VendorSetup foi preterida e não deve ser usada por novos drivers v3 ou v4 que você desenvolve. Essas informações sobre VendorSetup são fornecidas apenas para referência ou para a manutenção de drivers v3 existentes que já usam essa diretiva INF.

lParam

Não usado, a menos que o parâmetro DriverEvent seja definido como PRINTER_EVENT_ATTRIBUTES_CHANGED. Nesse caso, lParam contém o endereço de uma estrutura PRINTER_EVENT_ATTRIBUTES_INFO. (Consulte a descrição anterior do parâmetro DriverEvent .) Para todos os outros valores do parâmetro DriverEvent , o parâmetro lParam é NULL.

Retornar valor

Se a operação for bem-sucedida, a função deverá retornar TRUE; caso contrário, ele deve retornar FALSE. No entanto, no momento, a única vez em que o valor retornado da função é verificado é quando o spooler chama DrvPrinterEvent durante o processamento da função AddPrinter , com DriverEvent definido como PRINTER_EVENT_INITIALIZE. Se DrvPrinterEvent retornar FALSE nesse caso, o spooler não criará a impressora e, em vez disso, fará com que AddPrinter falhe.

Comentários

Todas as DLLs da interface da impressora devem fornecer uma função DrvPrinterEvent e a função deve dar suporte ao código de evento PRINTER_EVENT_INITIALIZE. O suporte para todos os outros códigos de evento é opcional.

As configurações do Registro armazenadas ao manipular um evento de PRINTER_EVENT_INITIALIZE devem ser armazenadas na chave HKEY_LOCAL_MACHINE chamando SetPrinterData. Para os códigos de evento PRINTER_EVENT_INITIALIZE e PRINTER_EVENT_DELETE, o spooler verifica se o chamador tem privilégio administrativo e chama DrvPrinterEvent ao representar o chamador.

Por outro lado, se você precisar armazenar configurações no registro ao manipular um evento PRINTER_EVENT_ADD_CONNECTION, a DLL da interface da impressora deverá gravá-las na chave HKEY_CURRENT_USER para que elas sejam armazenadas por usuário. Em seguida, se um usuário com um perfil móvel fizer logon em outro sistema, a conexão seguirá o usuário. A função DrvPrinterEvent é chamada somente quando o usuário faz a conexão pela primeira vez, e não quando o usuário faz logon posteriormente em outros sistemas usando o perfil móvel.

Para os códigos de evento PRINTER_EVENT_ADD_CONNECTION e PRINTER_EVENT_DELETE_CONNECTION, o contexto de execução da função DrvPrinterEvent é o aplicativo de chamada (geralmente a Pasta de Impressão) e a função pode exibir uma interface do usuário. Para todos os outros códigos de evento, o contexto de execução é o spooler de impressão e uma interface do usuário não pode ser exibida.

Um exemplo de um driver que pode exibir uma interface do usuário quando uma conexão é feita é um driver de FAX, que pode solicitar ao usuário o nome e o número de telefone do usuário (remetente de FAX) e salvar as informações até que a conexão seja excluída.

Um exemplo do tipo de arquivo que pode ser armazenado em um cache de cliente é um arquivo grande de métricas de fonte que contém muitas informações a serem gravadas no registro. Quando o código de evento da função DrvPrinterEvent é PRINTER_EVENT_CACHE_REFRESH, a DLL da interface da impressora pode recarregar o arquivo do servidor para garantir que o cache esteja atualizado.

Requisitos

Requisito	Valor
Plataforma de Destino	Área de Trabalho
Cabeçalho	winddiui.h (inclua Winddiui.h)