WlanRegisterNotification-Funktion (wlanapi.h)
Wichtig
Einige Informationen beziehen sich auf ein Vorabrelease-Produkt, das vor der kommerziellen Freigabe wesentlich geändert werden kann. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.
Die WlanRegisterNotification-Funktion dient zum Registrieren und Aufheben der Registrierung von Benachrichtigungen auf allen drahtlosen Schnittstellen.
Syntax
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
);
Parameter
[in] hClientHandle
Das Sitzungshandle des Clients, das durch einen vorherigen Aufruf der WlanOpenHandle-Funktion abgerufen wurde.
[in] dwNotifSource
Die zu registrierenden Benachrichtigungsquellen. Diese Flags können kombiniert werden. Wenn dieser Parameter auf WLAN_NOTIFICATION_SOURCE_NONE festgelegt ist, hebt WlanRegisterNotification die Registrierung von Benachrichtigungen für alle drahtlosen Schnittstellen auf.
Die möglichen Werte für diesen Parameter werden in den Headerdateien "Wlanapi.h" und "L2cmn.h " definiert.
In der folgenden Tabelle sind die möglichen Werte aufgeführt.
Wert | Bedeutung |
---|---|
|
Hebt die Registrierung von Benachrichtigungen auf. |
|
Registriert alle Benachrichtigungen, die für die Version des Betriebssystems verfügbar sind, einschließlich der Benachrichtigungen, die vom Modul 802.1X generiert wurden.
Für Windows XP mit SP3 und die WLAN-API für Windows XP mit SP2 entspricht das Festlegen von dwNotifSource auf WLAN_NOTIFICATION_SOURCE_ALL funktional dem Festlegen von dwNotifSource auf WLAN_NOTIFICATION_SOURCE_ACM. |
|
Registriert für Benachrichtigungen, die vom Modul für die automatische Konfiguration generiert werden.
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Es sind nur die Benachrichtigungen wlan_notification_acm_connection_complete und wlan_notification_acm_disconnected verfügbar. |
|
Registriert sich für Benachrichtigungen, die vom drahtlosen gehosteten Netzwerk generiert werden. Diese Benachrichtigungsquelle ist unter Windows 7 und Windows Server 2008 R2 mit installiertem WLAN-Dienst verfügbar. |
|
Registriert für Benachrichtigungen, die von 802.1X generiert wurden. |
|
Registriert für Benachrichtigungen, die von MSM generiert werden.
Wenn das flag WLAN_NOTIFICATION_SOURCE_MSM in dwNotifSource festgelegt ist, ist die wiFiControl-Gerätefunktion erforderlich (siehe App-Funktionsdeklarationen). Wenn diese Funktion nicht gewährt wird, gibt die Funktion ERROR_ACCESS_DENIED zurück. Das Anfordern der wiFiControl-Gerätefunktion erfordert die Zustimmung des Benutzers in Bezug auf den Zugriff auf den Standort. Weitere Informationen finden Sie unter Änderungen am API-Verhalten für Wi-Fi Zugriff und Speicherort. Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Dieser Wert wird nicht unterstützt. |
|
Registriert für Benachrichtigungen, die vom Sicherheitsmodul generiert werden.
Für WLAN_NOTIFICATION_SOURCE_SECURITY sind derzeit keine Benachrichtigungen definiert. Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Dieser Wert wird nicht unterstützt. |
|
Registriert für Benachrichtigungen, die von unabhängigen Hardwareherstellern (IHV) generiert werden.
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Dieser Wert wird nicht unterstützt. |
|
Registriert für Benachrichtigungen, die von Gerätediensten generiert werden. |
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Dieser Parameter muss auf WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL oder WLAN_NOTIFICATION_SOURCE_ACM festgelegt werden.
[in] bIgnoreDuplicate
Gibt an, ob doppelte Benachrichtigungen ignoriert werden. Wenn true festgelegt ist, wird keine Benachrichtigung an den Client gesendet, wenn sie mit der vorherigen identisch ist.
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Dieser Parameter wird ignoriert.
[in, optional] funcCallback
Ein WLAN_NOTIFICATION_CALLBACK Typ, der den Typ der Benachrichtigungsrückruffunktion definiert.
Dieser Parameter kann NULL sein, wenn der dwNotifSource-Parameter auf WLAN_NOTIFICATION_SOURCE_NONE festgelegt ist, um die Registrierung von Benachrichtigungen auf allen Drahtlosschnittstellen aufzuheben.
[in, optional] pCallbackContext
Ein Zeiger auf den Clientkontext, der mit der Benachrichtigung an die Rückruffunktion übergeben wird.
[in] pReserved
Für die zukünftige Verwendung reserviert. Muss auf NULL festgelegt werden.
[out, optional] pdwPrevNotifSource
Ein Zeiger auf die zuvor registrierten Benachrichtigungsquellen.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Rückgabecodes sein.
Wenn das flag WLAN_NOTIFICATION_SOURCE_MSM in dwNotifSource festgelegt ist, ist die wiFiControl-Gerätefunktion erforderlich (siehe App-Funktionsdeklarationen). Wenn diese Funktion nicht gewährt wird, gibt die Funktion ERROR_ACCESS_DENIED zurück. Das Anfordern der wiFiControl-Gerätefunktion erfordert die Zustimmung des Benutzers in Bezug auf den Zugriff auf den Standort. Weitere Informationen finden Sie unter Änderungen am API-Verhalten für Wi-Fi Zugriff und Speicherort.
Rückgabecode | Beschreibung |
---|---|
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn hClientHandleNULL oder ungültig ist oder wenn pReserved nicht NULL ist. |
|
Das Handle hClientHandle wurde in der Handletabelle nicht gefunden. |
|
Fehler beim Zuweisen von Arbeitsspeicher für die Abfrageergebnisse. |
|
Wenn das WLAN_NOTIFICATION_SOURCE_MSM-Flag in dwNotifSource festgelegt ist, ist die wiFiControl-Gerätefunktion erforderlich (siehe App-Funktionsdeklarationen). Wenn diese Funktion nicht gewährt wird, gibt die Funktion ERROR_ACCESS_DENIED zurück. Das Anfordern der wiFiControl-Gerätefunktion erfordert die Zustimmung des Benutzers in Bezug auf den Zugriff auf den Standort. Weitere Informationen finden Sie unter Änderungen am API-Verhalten für Wi-Fi Zugriff und Speicherort. |
|
Verschiedene Fehlercodes. |
Hinweise
Die WlanRegisterNotification wird von einer Anwendung verwendet, um Benachrichtigungen auf allen drahtlosen Schnittstellen zu registrieren und aufzuheben. Bei der Registrierung für Benachrichtigungen muss eine Anwendung eine Rückruffunktion bereitstellen, auf die der funcCallback-Parameter verweist. Der Prototyp für diese Rückruffunktion ist die WLAN_NOTIFICATION_CALLBACK. Diese Rückruffunktion empfängt Benachrichtigungen, die im dwNotifSource-Parameter registriert wurden, der an die WlanRegisterNotification-Funktion übergeben wird. Die Rückruffunktion wird mit einem Zeiger auf eine WLAN_NOTIFICATION_DATA-Struktur als ersten Parameter aufgerufen, der detaillierte Informationen zur Benachrichtigung enthält. Die Rückruffunktion empfängt auch einen zweiten Parameter, der einen Zeiger auf den Clientkontext enthält, der im pCallbackContext-Parameter an die WlanRegisterNotification-Funktion übergeben wird.
Die WlanRegisterNotification-Funktion gibt einen Fehler zurück, wenn dwNotifSource ein anderer Wert als WLAN_NOTIFICATION_SOURCE_NONE ist und der Client keine Rückruffunktion bereitstellt.
Nach der Registrierung wird die Rückruffunktion immer dann aufgerufen, wenn eine Benachrichtigung verfügbar ist, bis der Client die Registrierung auf- oder schließt.
Alle Registrierungen zum Empfangen von Benachrichtigungen, die durch diese Funktion verursacht werden, werden automatisch rückgängig, wenn die aufrufende Anwendung ihr Aufrufende Handle schließt (durch Aufrufen von WlanCloseHandle mit dem hClientHandle-Parameter ) oder wenn der Prozess beendet wird.
Rufen Sie WlanRegisterNotification nicht über eine Rückruffunktion auf. Wenn sich der Client in der Mitte eines Benachrichtigungsrückrufs befindet, wenn WlanRegisterNotification aufgerufen wird und dwNotifSource auf WLAN_NOTIFICATION_SOURCE_NONE festgelegt ist (d. h. wenn der Client die Registrierung von Benachrichtigungen aufhebt), wartet WlanRegisterNotification auf den Abschluss des Rückrufs, bevor ein Wert zurückgegeben wird. Das Aufrufen dieser Funktion innerhalb einer Rückruffunktion führt dazu, dass der Aufruf nie abgeschlossen wird. Wenn sowohl die Rückruffunktion als auch der Thread, der die Registrierung von Benachrichtigungen auflöst, versuchen, dieselbe Sperre zu erhalten, kann ein Deadlock auftreten. Rufen Sie außerdem WlanRegisterNotification nicht über die DllMain-Funktion in einer Anwendungs-DLL auf. Dies kann auch zu einem Deadlock führen.
Eine Anwendung kann ein Timeout ausführen und den aktuellen Schnittstellenstatus abfragen, anstatt auf eine Benachrichtigung zu warten.
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Benachrichtigungen werden vom Netman-Dienst verarbeitet. Wenn der Netman-Dienst deaktiviert oder nicht verfügbar ist, werden keine Benachrichtigungen empfangen. Wenn eine Benachrichtigung nicht innerhalb eines angemessenen Zeitraums empfangen wird, sollte eine Anwendung ein Timeout ausführen und den aktuellen Schnittstellenstatus abfragen.
Anforderungen
Anforderung | Wert |
---|---|
Unterstützte Mindestversion (Client) | Windows Vista, Windows XP mit SP3 [nur Desktop-Apps] |
Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
Zielplattform | Windows |
Kopfzeile | wlanapi.h (einschließlich Wlanapi.h) |
Bibliothek | Wlanapi.lib |
DLL | Wlanapi.dll |
Verteilbare Komponente | Wlan-API für Windows XP mit SP2 |