Função FindNextPrinterChangeNotification

A função FindNextPrinterChangeNotification recupera informações sobre a notificação de alteração mais recente para um objeto de notificação de alteração associado a uma impressora ou servidor de impressão. Chame essa função quando uma operação de espera no objeto de notificação de alteração for atendida.

A função também redefine o objeto de notificação de alteração para o estado não sinalizado. Em seguida, você pode usar o objeto em outra operação de espera para continuar monitorando a impressora ou o servidor de impressão. O sistema operacional definirá o objeto como o estado sinalizado na próxima vez que ocorrer uma das alterações especificadas no servidor de impressão ou impressora. A função FindFirstPrinterChangeNotification cria o objeto de notificação de alteração e especifica o conjunto de alterações a serem monitoradas.

Sintaxe

BOOL FindNextPrinterChangeNotification(
  _In_      HANDLE hChange,
  _Out_opt_ PDWORD pdwChange,
  _In_opt_  LPVOID pPrinterNotifyOptions,
  _Out_opt_ LPVOID *ppPrinterNotifyInfo
);

Parâmetros

hChange [in]

Um identificador para um objeto de notificação de alteração associado a uma impressora ou servidor de impressão. Você obtém esse identificador chamando a função FindFirstPrinterChangeNotification . O sistema operacional define esse objeto de notificação de alteração para o estado sinalizado quando detecta uma das alterações especificadas no filtro de notificação de alteração do objeto.

pdwChange [out, opcional]

Um ponteiro para uma variável cujos bits estão definidos para indicar as alterações que ocorreram para causar a notificação mais recente. Os sinalizadores de bit que podem ser definidos correspondem aos especificados no parâmetro fdwFilter da chamada FindFirstPrinterChangeNotification . O sistema define um ou mais dos sinalizadores de bit a seguir.

Valor	Significado
PRINTER_CHANGE_ADD_FORM	Um formulário foi adicionado ao servidor.
PRINTER_CHANGE_ADD_JOB	Um trabalho de impressão foi enviado para a impressora.
PRINTER_CHANGE_ADD_PORT	Uma porta ou monitor foi adicionado ao servidor.
PRINTER_CHANGE_ADD_PRINT_PROCESSOR	Um processador de impressão foi adicionado ao servidor.
PRINTER_CHANGE_ADD_PRINTER	Uma impressora foi adicionada ao servidor.
PRINTER_CHANGE_ADD_PRINTER_DRIVER	Um driver de impressora foi adicionado ao servidor.
PRINTER_CHANGE_CONFIGURE_PORT	Uma porta foi configurada no servidor.
PRINTER_CHANGE_DELETE_FORM	Um formulário foi excluído do servidor.
PRINTER_CHANGE_DELETE_JOB	Um trabalho foi excluído.
PRINTER_CHANGE_DELETE_PORT	Uma porta ou monitor foi excluído do servidor.
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR	Um processador de impressão foi excluído do servidor.
PRINTER_CHANGE_DELETE_PRINTER	Uma impressora foi excluída.
PRINTER_CHANGE_DELETE_PRINTER_DRIVER	Um driver de impressora foi excluído do servidor.
PRINTER_CHANGE_FAILED_CONNECTION_PRINTER	Falha na conexão da impressora.
PRINTER_CHANGE_SET_FORM	Um formulário foi definido no servidor.
PRINTER_CHANGE_SET_JOB	Um trabalho foi definido.
PRINTER_CHANGE_SET_PRINTER	Uma impressora foi definida.
PRINTER_CHANGE_SET_PRINTER_DRIVER	Um driver de impressora foi definido.
PRINTER_CHANGE_WRITE_JOB	Os dados do trabalho foram gravados.
PRINTER_CHANGE_TIMEOUT	O trabalho atingiu o tempo limite.
PRINTER_CHANGE_SERVER	Windows 7: ocorreu uma alteração no servidor.

pPrinterNotifyOptions [in, opcional]

Um ponteiro para uma estrutura PRINTER_NOTIFY_OPTIONS . Defina o membro Flags dessa estrutura como PRINTER_NOTIFY_OPTIONS_REFRESH, para fazer com que a função retorne os dados atuais para todos os campos de informações da impressora monitorada. A função ignora todos os outros membros da estrutura. Este parâmetro pode ser NULL.

ppPrinterNotifyInfo [out, opcional]

Um ponteiro para uma variável de ponteiro que recebe um ponteiro para um buffer somente leitura alocado pelo sistema. Chame a função FreePrinterNotifyInfo para liberar o buffer quando terminar de fazer isso. Esse parâmetro poderá ser NULL se nenhuma informação for necessária.

O buffer contém uma estrutura PRINTER_NOTIFY_INFO , que contém uma matriz de estruturas de PRINTER_NOTIFY_INFO_DATA . Cada elemento da matriz contém informações sobre um dos campos especificados no parâmetro pPrinterNotifyOptions da chamada FindFirstPrinterChangeNotification . Normalmente, a função fornece dados apenas para os campos que foram alterados para causar a notificação mais recente. No entanto, se a estrutura apontada pelo parâmetro pPrinterNotifyOptionsespecificar PRINTER_NOTIFY_OPTIONS_REFRESH, a função fornecerá dados para todos os campos monitorados.

Se o bit PRINTER_NOTIFY_INFO_DISCARDED estiver definido no membro Flags da estrutura PRINTER_NOTIFY_INFO , ocorrerá um estouro ou erro e as notificações poderão ter sido perdidas. Nesse caso, nenhuma notificação adicional será enviada até que você faça uma segunda chamada FindNextPrinterChangeNotification que especifica PRINTER_NOTIFY_OPTIONS_REFRESH.

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

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.

Chame a função FindNextPrinterChangeNotification depois que uma operação de espera em um objeto de notificação criado por FindFirstPrinterChangeNotification for atendida. Chamar FindNextPrinterChangeNotification permite obter informações sobre a alteração que atendeu à operação de espera e redefine o objeto de notificação para que ele possa ser sinalizado quando a próxima alteração ocorrer.

Com uma exceção, não chame a função FindNextPrinterChangeNotification se o objeto de notificação de alteração não estiver no estado sinalizado. Se uma função de espera retornar o valor WAIT_TIMEOUT, o objeto de alteração não estará no estado sinalizado. Chame a função FindNextPrinterChangeNotification somente se a função de espera for bem-sucedida sem atingir o tempo limite. A exceção é quando FindNextPrinterChangeNotification é chamado com o PRINTER_NOTIFY_OPTIONS_REFRESH bit definido no parâmetro pPrinterNotifyOptions . Observe que, mesmo quando esse sinalizador é definido, ainda é possível que o sinalizador PRINTER_NOTIFY_INFO_DISCARDED seja definido no parâmetro ppPrinterNotifyInfo .

Para continuar monitorando a impressora ou o servidor de impressão para alterações, repita o ciclo de chamada de uma das funções de espera e, em seguida, chame a função FindNextPrinterChangeNotification para examinar a alteração e redefinir o objeto de notificação.

FindNextPrinterChangeNotification pode combinar várias alterações no mesmo campo de informações da impressora em uma única notificação. Quando isso ocorre, a função normalmente recolhe todas as alterações do campo em uma única entrada na matriz de estruturas de PRINTER_NOTIFY_INFO_DATA em ppPrinterNotifyInfo; a entrada única relata apenas as informações mais atuais. No entanto, para alguns campos de informações de trabalho e impressora, a função pode retornar várias entradas de matriz para o mesmo campo. Nesse caso, a última entrada de matriz do campo relata os dados atuais e as entradas anteriores contêm os dados para os estágios intermediários.

Quando você não precisar mais do objeto de notificação de alteração, feche-o chamando a função FindClosePrinterChangeNotification .

Observação

No Windows XP com Service Pack 2 (SP2) e posterior, o ICF (Firewall de Conexão com a Internet) bloqueia as portas da impressora por padrão, mas uma exceção para Compartilhamento de Arquivos e Impressão pode ser habilitada. Se um usuário fizer uma conexão de impressora com outro computador e a exceção não estiver habilitada, o usuário não receberá notificações de alteração de impressora do servidor. Um administrador de computador terá que habilitar a exceção.

Exemplos

O exemplo de código a seguir ilustra como você pode monitorar status de impressora usando essas funções.

// Get change notification handle for the printer   
chgObject = FindFirstPrinterChangeNotification( 
                hPrinter, 
                PRINTER_CHANGE_JOB, 
                0, 
                NULL); 

if (chgObject != INVALID_HANDLE_VALUE) {
    while (bKeepMonitoring) {
        // Wait for the change notification 
        WaitForSingleObject(chgObject, INFINITE);

        fcnreturn = FindNextPrinterChangeNotification(
                        chgObject, 
                        pdwChange, 
                        NULL, 
                        NULL);

        if (fcnreturn) {
            // Check value of *pdwChange and 
            //  deal with the indicated change 
        }
        // Insert some mechanism to stop monitoring
        //  such as: 
        //
        // if (something happens) {
        //     bKeepMonitoring = false; 
        // }
        //
    }
    // Close Printer Change Notification handle when finished. 
    FindClosePrinterChangeNotification(chgObject);
} else {
    // Unable to open printer change notification handle 
    dwStatus = GetLastError();
}

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	Spoolss.dll

Confira também

Impressão

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

FindClosePrinterChangeNotification

FindFirstPrinterChangeNotification

PRINTER_NOTIFY_INFO

PRINTER_NOTIFY_INFO_DATA

PRINTER_NOTIFY_OPTIONS