WlanRegisterNotification-Funktion (wlanapi.h)

Artikel
02/01/2024

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
WLAN_NOTIFICATION_SOURCE_NONE	Hebt die Registrierung von Benachrichtigungen auf.
WLAN_NOTIFICATION_SOURCE_ALL	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.
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.
WLAN_NOTIFICATION_SOURCE_HNWK	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.
WLAN_NOTIFICATION_SOURCE_ONEX	Registriert für Benachrichtigungen, die von 802.1X generiert wurden.
WLAN_NOTIFICATION_SOURCE_MSM	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.
WLAN_NOTIFICATION_SOURCE_SECURITY	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.
WLAN_NOTIFICATION_SOURCE_IHV	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.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	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
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn hClientHandleNULL oder ungültig ist oder wenn pReserved nicht NULL ist.
ERROR_INVALID_HANDLE	Das Handle hClientHandle wurde in der Handletabelle nicht gefunden.
ERROR_NOT_ENOUGH_MEMORY	Fehler beim Zuweisen von Arbeitsspeicher für die Abfrageergebnisse.
ERROR_ACCESS_DENIED	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.
RPC_STATUS	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