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 |
|
| Biblioteca |
|
| DLL |
|