Fonction FindNextPrinterChangeNotification
La fonction FindNextPrinterChangeNotification récupère des informations sur la notification de modification la plus récente pour un objet de notification de modification associé à une imprimante ou à un serveur d’impression. Appelez cette fonction lorsqu’une opération d’attente sur l’objet de notification de modification est satisfaite.
La fonction réinitialise également l’objet de notification de modification à l’état non signalé. Vous pouvez ensuite utiliser l’objet dans une autre opération d’attente pour continuer à surveiller l’imprimante ou le serveur d’impression. Le système d’exploitation définit l’objet à l’état signalé la prochaine fois qu’une des modifications spécifiées se produira sur l’imprimante ou le serveur d’impression. La fonction FindFirstPrinterChangeNotification crée l’objet de notification de modification et spécifie l’ensemble des modifications à surveiller.
Syntaxe
BOOL FindNextPrinterChangeNotification(
_In_ HANDLE hChange,
_Out_opt_ PDWORD pdwChange,
_In_opt_ LPVOID pPrinterNotifyOptions,
_Out_opt_ LPVOID *ppPrinterNotifyInfo
);
Paramètres
-
hChange [in]
-
Handle d’un objet de notification de modification associé à une imprimante ou à un serveur d’impression. Vous obtenez un tel handle en appelant la fonction FindFirstPrinterChangeNotification . Le système d’exploitation définit cet objet de notification de modification à l’état signalé lorsqu’il détecte l’une des modifications spécifiées dans le filtre de notification de modification de l’objet.
-
pdwChange [out, facultatif]
-
Pointeur vers une variable dont les bits sont définis pour indiquer les modifications qui se sont produites pour provoquer la notification la plus récente. Les indicateurs de bits qui peuvent être définis correspondent à ceux spécifiés dans le paramètre fdwFilter de l’appel FindFirstPrinterChangeNotification . Le système définit un ou plusieurs des indicateurs de bits suivants.
Valeur Signification - PRINTER_CHANGE_ADD_FORM
Un formulaire a été ajouté au serveur. - PRINTER_CHANGE_ADD_JOB
Un travail d’impression a été envoyé à l’imprimante. - PRINTER_CHANGE_ADD_PORT
Un port ou un moniteur a été ajouté au serveur. - PRINTER_CHANGE_ADD_PRINT_PROCESSOR
Un processeur d’impression a été ajouté au serveur. - PRINTER_CHANGE_ADD_PRINTER
Une imprimante a été ajoutée au serveur. - PRINTER_CHANGE_ADD_PRINTER_DRIVER
Un pilote d’imprimante a été ajouté au serveur. - PRINTER_CHANGE_CONFIGURE_PORT
Un port a été configuré sur le serveur. - PRINTER_CHANGE_DELETE_FORM
Un formulaire a été supprimé du serveur. - PRINTER_CHANGE_DELETE_JOB
Un travail a été supprimé. - PRINTER_CHANGE_DELETE_PORT
Un port ou un moniteur a été supprimé du serveur. - PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
Un processeur d’impression a été supprimé du serveur. - PRINTER_CHANGE_DELETE_PRINTER
Une imprimante a été supprimée. - PRINTER_CHANGE_DELETE_PRINTER_DRIVER
Un pilote d’imprimante a été supprimé du serveur. - PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
Une connexion d’imprimante a échoué. - PRINTER_CHANGE_SET_FORM
Un formulaire a été défini sur le serveur. - PRINTER_CHANGE_SET_JOB
Un travail a été défini. - PRINTER_CHANGE_SET_PRINTER
Une imprimante a été définie. - PRINTER_CHANGE_SET_PRINTER_DRIVER
Un pilote d’imprimante a été défini. - PRINTER_CHANGE_WRITE_JOB
Les données de travail ont été écrites. - PRINTER_CHANGE_TIMEOUT
Le travail a expiré. - PRINTER_CHANGE_SERVER
Windows 7 : une modification s’est produite sur le serveur. -
pPrinterNotifyOptions [in, facultatif]
-
Pointeur vers une structure PRINTER_NOTIFY_OPTIONS . Définissez le membre Indicateurs de cette structure sur PRINTER_NOTIFY_OPTIONS_REFRESH, afin que la fonction retourne les données actuelles de tous les champs d’informations d’imprimante surveillés. La fonction ignore tous les autres membres de la structure. Ce paramètre peut être NULL.
-
ppPrinterNotifyInfo [out, facultatif]
-
Pointeur vers une variable de pointeur qui reçoit un pointeur vers une mémoire tampon en lecture seule allouée par le système. Appelez la fonction FreePrinterNotifyInfo pour libérer la mémoire tampon lorsque vous avez terminé. Ce paramètre peut avoir la valeur NULL si aucune information n’est requise.
La mémoire tampon contient une structure PRINTER_NOTIFY_INFO , qui contient un tableau de structures PRINTER_NOTIFY_INFO_DATA . Chaque élément du tableau contient des informations sur l’un des champs spécifiés dans le paramètre pPrinterNotifyOptions de l’appel FindFirstPrinterChangeNotification . En règle générale, la fonction fournit des données uniquement pour les champs qui ont changé pour provoquer la notification la plus récente. Toutefois, si la structure pointée vers par le paramètre pPrinterNotifyOptions spécifie PRINTER_NOTIFY_OPTIONS_REFRESH, la fonction fournit des données pour tous les champs surveillés.
Si le bit PRINTER_NOTIFY_INFO_DISCARDED est défini dans le membre Indicateurs de la structure PRINTER_NOTIFY_INFO , un dépassement de capacité ou une erreur s’est produit et des notifications peuvent avoir été perdues. Dans ce cas, aucune notification supplémentaire n’est envoyée tant que vous n’avez pas fait un deuxième appel FindNextPrinterChangeNotification qui spécifie PRINTER_NOTIFY_OPTIONS_REFRESH.
Valeur retournée
Si la fonction réussit, la valeur de retour est une valeur différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro.
Notes
Notes
Il s’agit d’une fonction bloquante ou synchrone qui peut ne pas être retournée immédiatement. La rapidité avec laquelle cette fonction retourne dépend de facteurs d’exécution tels que l’status réseau, la configuration du serveur d’impression et les facteurs d’implémentation du pilote d’imprimante qui sont difficiles à prédire lors de l’écriture d’une application. L’appel de cette fonction à partir d’un thread qui gère l’interaction avec l’interface utilisateur peut donner l’impression que l’application ne répond pas.
Appelez la fonction FindNextPrinterChangeNotification une fois qu’une opération d’attente sur un objet de notification créé par FindFirstPrinterChangeNotification a été satisfaite. L’appel de FindNextPrinterChangeNotification vous permet d’obtenir des informations sur la modification qui a satisfait l’opération d’attente et de réinitialiser l’objet de notification afin qu’il puisse être signalé lorsque la modification suivante se produit.
À une exception près, n’appelez pas la fonction FindNextPrinterChangeNotification si l’objet de notification de modification n’est pas à l’état signalé. Si une fonction d’attente retourne la valeur WAIT_TIMEOUT, l’objet de modification n’est pas à l’état signalé. Appelez la fonction FindNextPrinterChangeNotification uniquement si la fonction d’attente réussit sans délai d’attente. L’exception est lorsque FindNextPrinterChangeNotification est appelé avec le PRINTER_NOTIFY_OPTIONS_REFRESH bit défini dans le paramètre pPrinterNotifyOptions . Notez que même lorsque cet indicateur est défini, il est toujours possible que l’indicateur PRINTER_NOTIFY_INFO_DISCARDED soit défini dans le paramètre ppPrinterNotifyInfo .
Pour continuer à surveiller l’imprimante ou le serveur d’impression à la recherche de modifications, répétez le cycle d’appel de l’une des fonctions d’attente , puis appelez la fonction FindNextPrinterChangeNotification pour examiner la modification et réinitialiser l’objet de notification.
FindNextPrinterChangeNotification peut combiner plusieurs modifications apportées au même champ d’informations d’imprimante en une seule notification. Lorsque cela se produit, la fonction réduit généralement toutes les modifications du champ en une seule entrée dans le tableau de structures PRINTER_NOTIFY_INFO_DATA dans ppPrinterNotifyInfo ; l’entrée unique ne signale que les informations les plus actuelles. Toutefois, pour certains champs d’informations sur le travail et l’imprimante, la fonction peut retourner plusieurs entrées de tableau pour le même champ. Dans ce cas, la dernière entrée de tableau pour le champ indique les données actuelles, et les entrées antérieures contiennent les données pour les étapes intermédiaires.
Lorsque vous n’avez plus besoin de l’objet de notification de modification, fermez-le en appelant la fonction FindClosePrinterChangeNotification .
Notes
Dans Windows XP avec Service Pack 2 (SP2) et versions ultérieures, le pare-feu de connexion Internet (ICF) bloque les ports d’imprimante par défaut, mais une exception pour le partage de fichiers et d’impression peut être activée. Si un utilisateur établit une connexion d’imprimante à un autre ordinateur et que l’exception n’est pas activée, l’utilisateur ne reçoit pas de notifications de modification d’imprimante du serveur. Un administrateur de machine doit activer l’exception.
Exemples
L’exemple de code suivant illustre la façon dont vous pouvez surveiller les status d’imprimante à l’aide de ces fonctions.
// 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();
}
Spécifications
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge |
Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge |
Windows 2000 Server [applications de bureau uniquement] |
| En-tête |
|
| Bibliothèque |
|
| DLL |
|