Fonction WlanRegisterNotification (wlanapi.h)

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.

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.

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

Voir aussi

ONEX_NOTIFICATION_TYPE

WLAN_HOSTED_NETWORK_NOTIFICATION_CODE

WLAN_NOTIFICATION_ACM

WLAN_NOTIFICATION_CALLBACK

WLAN_NOTIFICATION_DATA

WLAN_NOTIFICATION_MSM

WlanCloseHandle

WlanRegisterVirtualStationNotification