Fonction WlanRegisterNotification (wlanapi.h)

Article
01/30/2024

Important

Certaines informations se rapportent à un produit de préversion qui peut être sensiblement modifié avant sa commercialisation. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

La fonction WlanRegisterNotification est utilisée pour inscrire et annuler l’inscription des notifications sur toutes les interfaces sans fil.

Syntaxe

DWORD WlanRegisterNotification(
  [in]            HANDLE                     hClientHandle,
  [in]            DWORD                      dwNotifSource,
  [in]            BOOL                       bIgnoreDuplicate,
  [in, optional]  WLAN_NOTIFICATION_CALLBACK funcCallback,
  [in, optional]  PVOID                      pCallbackContext,
  [in]            PVOID                      pReserved,
  [out, optional] PDWORD                     pdwPrevNotifSource
);

Paramètres

[in] hClientHandle

Le handle de session du client, obtenu par un appel précédent à la fonction WlanOpenHandle .

[in] dwNotifSource

Sources de notification à inscrire. Ces indicateurs peuvent être combinés. Lorsque ce paramètre est défini sur WLAN_NOTIFICATION_SOURCE_NONE, WlanRegisterNotification annule l’inscription des notifications sur toutes les interfaces sans fil.

Les valeurs possibles pour ce paramètre sont définies dans les fichiers d’en-tête Wlanapi.h et L2cmn.h .

La table suivante indique des valeurs possibles.

Valeur	Signification
WLAN_NOTIFICATION_SOURCE_NONE	Annule l’inscription des notifications.
WLAN_NOTIFICATION_SOURCE_ALL	S’inscrit pour toutes les notifications disponibles sur la version du système d’exploitation, y compris celles générées par le module 802.1X. Pour Windows XP avec SP3 et l’API LAN sans fil pour Windows XP avec SP2, définir dwNotifSourcesur WLAN_NOTIFICATION_SOURCE_ALL équivaut fonctionnellement à définir dwNotifSource sur WLAN_NOTIFICATION_SOURCE_ACM.
WLAN_NOTIFICATION_SOURCE_ACM	S’inscrit aux notifications générées par le module de configuration automatique. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Seules les notifications wlan_notification_acm_connection_complete et wlan_notification_acm_disconnected sont disponibles.
WLAN_NOTIFICATION_SOURCE_HNWK	S’inscrit aux notifications générées par le réseau hébergé sans fil. Cette source de notification est disponible sur Windows 7 et Windows Server 2008 R2 avec le service LAN sans fil installé.
WLAN_NOTIFICATION_SOURCE_ONEX	S’inscrit pour les notifications générées par 802.1X.
WLAN_NOTIFICATION_SOURCE_MSM	S’inscrit aux notifications générées par MSM. Si l’indicateur WLAN_NOTIFICATION_SOURCE_MSM est défini dans dwNotifSource, la fonctionnalité de l’appareil wiFiControl est requise (voir Déclarations de capacité d’application). Si cette fonctionnalité n’est pas accordée, la fonction retourne ERROR_ACCESS_DENIED. La demande de la fonctionnalité d’appareil wiFiControl nécessite le consentement de l’utilisateur concernant l’accès à l’emplacement. Pour plus d’informations, consultez Modifications du comportement de l’API pour Wi-Fi l’accès et l’emplacement. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Cette valeur n’est pas prise en charge.
WLAN_NOTIFICATION_SOURCE_SECURITY	S’inscrit aux notifications générées par le module de sécurité. Aucune notification n’est actuellement définie pour WLAN_NOTIFICATION_SOURCE_SECURITY. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Cette valeur n’est pas prise en charge.
WLAN_NOTIFICATION_SOURCE_IHV	S’inscrit aux notifications générées par les fournisseurs de matériel indépendants (IHV). Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Cette valeur n’est pas prise en charge.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	S’inscrit aux notifications générées par les services d’appareil.

Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Ce paramètre doit être défini sur WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL ou WLAN_NOTIFICATION_SOURCE_ACM.

[in] bIgnoreDuplicate

Spécifie si les notifications en double seront ignorées. Si la valeur est TRUE, aucune notification n’est envoyée au client si elle est identique à la précédente.

Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Ce paramètre est ignoré.

[in, optional] funcCallback

Type WLAN_NOTIFICATION_CALLBACK qui définit le type de fonction de rappel de notification.

Ce paramètre peut avoir la valeur NULL si le paramètre dwNotifSource est défini sur WLAN_NOTIFICATION_SOURCE_NONE pour annuler l’inscription des notifications sur toutes les interfaces sans fil,

[in, optional] pCallbackContext

Pointeur vers le contexte client qui sera passé à la fonction de rappel avec la notification.

[in] pReserved

Réservé pour un usage futur. Doit être défini sur NULL.

[out, optional] pdwPrevNotifSource

Pointeur vers les sources de notification précédemment inscrites.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour peut être l’un des codes de retour suivants.

Si l’indicateur WLAN_NOTIFICATION_SOURCE_MSM est défini dans dwNotifSource, la fonctionnalité de l’appareil wiFiControl est requise (voir Déclarations de capacité d’application). Si cette fonctionnalité n’est pas accordée, la fonction retourne ERROR_ACCESS_DENIED. La demande de la fonctionnalité d’appareil wiFiControl nécessite le consentement de l’utilisateur concernant l’accès à l’emplacement. Pour plus d’informations, consultez Modifications du comportement de l’API pour Wi-Fi l’accès et l’emplacement.

Code de retour	Description
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si hClientHandle a la valeur NULL ou n’est pas valide ou si pReserved n’a pas la valeur NULL.
ERROR_INVALID_HANDLE	Le handle hClientHandle est introuvable dans la table handle.
ERROR_NOT_ENOUGH_MEMORY	Échec de l’allocation de mémoire pour les résultats de la requête.
ERROR_ACCESS_DENIED	Si l’indicateur WLAN_NOTIFICATION_SOURCE_MSM est défini dans dwNotifSource, la fonctionnalité d’appareil wiFiControl est requise (voir Déclarations de capacité d’application. Si cette fonctionnalité n’est pas accordée, la fonction retourne ERROR_ACCESS_DENIED. La demande de la fonctionnalité d’appareil wiFiControl nécessite le consentement de l’utilisateur concernant l’accès à l’emplacement. Pour plus d’informations, consultez Modifications du comportement de l’API pour Wi-Fi l’accès et l’emplacement.
RPC_STATUS	Différents codes d’erreur.

Remarques

WlanRegisterNotification est utilisé par une application pour inscrire et annuler l’inscription des notifications sur toutes les interfaces sans fil. Lors de l’inscription aux notifications, une application doit fournir une fonction de rappel pointée vers le paramètre funcCallback . Le prototype de cette fonction de rappel est le WLAN_NOTIFICATION_CALLBACK. Cette fonction de rappel reçoit des notifications qui ont été inscrites pour dans le paramètre dwNotifSource passé à la fonction WlanRegisterNotification . La fonction de rappel est appelée avec un pointeur vers une structure WLAN_NOTIFICATION_DATA comme premier paramètre qui contient des informations détaillées sur la notification. La fonction de rappel reçoit également un deuxième paramètre qui contient un pointeur vers le contexte client passé dans le paramètre pCallbackContext à la fonction WlanRegisterNotification .

La fonction WlanRegisterNotification retourne une erreur si dwNotifSource est une valeur autre que WLAN_NOTIFICATION_SOURCE_NONE et si le client ne parvient pas à fournir une fonction de rappel.

Une fois inscrite, la fonction de rappel est appelée chaque fois qu’une notification est disponible jusqu’à ce que le client annule ou ferme le handle.

Toute inscription pour recevoir des notifications provoquées par cette fonction serait automatiquement annulée si l’application appelante ferme son handle d’appel (en appelant WlanCloseHandle avec le paramètre hClientHandle ) ou si le processus se termine.

N’appelez pas WlanRegisterNotification à partir d’une fonction de rappel. Si le client se trouve au milieu d’un rappel de notification lorsque WlanRegisterNotification est appelé avec dwNotifSource défini sur WLAN_NOTIFICATION_SOURCE_NONE (autrement dit, lorsque le client se désinscrit des notifications), WlanRegisterNotification attendra que le rappel se termine avant de renvoyer une valeur. L’appel de cette fonction à l’intérieur d’une fonction de rappel entraîne la fin de l’appel. Si la fonction de rappel et le thread qui désinscrit les notifications tentent d’acquérir le même verrou, un blocage peut se produire. En outre, n’appelez pas WlanRegisterNotification à partir de la fonction DllMain dans une DLL d’application. Cela peut également provoquer un blocage.

Une application peut expirer et interroger l’état actuel de l’interface au lieu d’attendre une notification.

Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Les notifications sont gérées par le service Netman. Si le service Netman est désactivé ou indisponible, les notifications ne sont pas reçues. Si aucune notification n’est reçue dans un délai raisonnable, une application doit expirer et interroger l’état actuel de l’interface.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista, Windows XP avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wlanapi.h (incluez Wlanapi.h)
Bibliothèque	Wlanapi.lib
DLL	Wlanapi.dll
Composant redistribuable	API LAN sans fil pour Windows XP avec SP2