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 de evento	Definição
PRINTER_EVENT_ADD_CONNECTION	O spooler acabou de concluir o processamento de uma chamada para sua funçãoAddPrinterConnection, 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 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çãoDeletePrinterConnection, que permite que um usuário cliente remova uma conexão de impressora.
PRINTER_EVENT_DELETE	O spooler acabou de concluir o processamento de 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 acabou de adicionar a impressora GUID. O evento PRINTER_EVENT_INITIALIZE especifica um valor de parâmetro NULL lParam para chamadas DrvPrinterEvent no Windows Vista e versões anteriores. Para versões posteriores e windows 7, 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 definido, a função não deve 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 é usando a 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 nenhum novos drivers v3 ou v4 que você desenvolver. 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 esteja definido como PRINTER_EVENT_ATTRIBUTES_CHANGED. Nesse caso, lParam contém o endereço de uma estrutura de 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.

Valor de retorno

Se a operação for bem-sucedida, a função deverá retornar VERDADEIRO; caso contrário, ele deverá retornar FALSE . No momento, no entanto, 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 falhem.

Observações

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 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 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 DrvPrinterEvent código de evento da função é 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
da Plataforma de Destino	Área de trabalho
cabeçalho	winddiui.h (inclua Winddiui.h)