WlanSetPsdIEDataList-Funktion (wlanapi.h)
Die WlanSetPsdIeDataList-Funktion legt die Datenliste der Näherungsdienstermittlung (PSD) (Information Element Information Element, IE) fest.
Syntax
DWORD WlanSetPsdIEDataList(
[in] HANDLE hClientHandle,
[in] LPCWSTR strFormat,
[in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
PVOID pReserved
);
Parameter
[in] hClientHandle
Das Sitzungshandle des Clients, das durch einen vorherigen Aufruf der WlanOpenHandle-Funktion abgerufen wurde.
[in] strFormat
Das Format eines PSD-IE in der PSD-IE-Datenliste, die im pPsdIEDataList-Parameter übergeben wird. Dies ist eine NULL-beendete URI-Zeichenfolge, die den Namespace des für die Ermittlung verwendeten Protokolls angibt.
[in] pPsdIEDataList
Ein Zeiger auf eine WLAN_RAW_DATA_LIST-Struktur , die die festzulegende PSD IE-Datenliste enthält.
pReserved
Für die zukünftige Verwendung reserviert. Muss auf NULL festgelegt werden.
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.
| Rückgabecode | Beschreibung |
|---|---|
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn hClientHandleNULL oder ungültig oder pReserved nicht NULL ist. |
|
Das Handle hClientHandle wurde in der Handle-Tabelle nicht gefunden. |
|
Diese Funktion wurde von einer nicht unterstützten Plattform aufgerufen. Dieser Wert wird zurückgegeben, wenn die Funktion von einem Windows XP-Client mit SP3 oder einer Wlan-LAN-API für Windows XP mit SP2-Client aufgerufen wurde. |
|
Verschiedene Fehlercodes. |
Hinweise
Das Näherungsdienstermittlungsprotokoll ist ein proprietäres Microsoft-Protokoll, mit dem ein Client Dienste in seiner physischen Nähe ermitteln kann, die durch den Funkbereich definiert wird. Der Zweck des Näherungsdienstermittlungsprotokolls besteht darin, Dienstermittlungsinformationen, z. B. Dienstanzeigen, als Teil von Beaconframes zu übermitteln. Zugriffspunkte (Access Points, APs) und Stationen (STAs), die im Ad-hoc-Modus arbeiten, senden regelmäßig Beaconframes. Der Beaconframe kann einzelne oder mehrere proprietäre Informationselemente enthalten, die Ermittlungsinformationen zu den Diensten enthalten, die das Gerät anbietet.
Ein PSD-IE wird verwendet, um komprimierte Informationen zu übertragen, die von übergeordneten Ermittlungsprotokollen für die passive Ermittlung bereitgestellt werden. Ein solches Protokoll auf höherer Ebene, das für die Ermittlung verwendet wird, ist das WS-Discovery-Protokoll. Für die Ermittlung kann jedes Protokoll verwendet werden.
Windows Vista und Windows Server 2008 mit installiertem WLAN-Dienst unterstützen die passive Ermittlung für Ad-hoc-Clients, Ad-hoc-Dienste und Infrastrukturclients. Dies bedeutet, dass ein Ad-hoc-Dienst eine verfügbare Ressource oder einen verfügbaren Dienst ankündigen kann, indem er einen PSD-IE in einem oder mehreren Beacons sendet. Es gibt keine Garantie dafür, dass dieses Beacon von einem Ad-hoc- oder Infrastrukturclient empfangen wird.
Windows 7 und Windows Server 2008 R2 mit installiertem WLAN-Dienst unterstützen die passive Ermittlung für Ad-hoc-Clients, Ad-hoc-Dienste und Infrastrukturclients auf die gleiche Weise wie in Windows Vista. Darüber hinaus wird der PSD IE auch für das drahtlose gehostete Netzwerk unterstützt, einen softwarebasierten Drahtlosen Zugriffspunkt (AP). Anwendungen auf dem lokalen Computer, auf dem das drahtlos gehostete Netzwerk ausgeführt werden soll, können die WlanSetPsdIeDataList-Funktion verwenden, um den PSD-IE festzulegen, bevor sie das drahtlose gehostete Netzwerk starten. Nach dem Festlegen wird der PSD-IE in die Beacon- und Testantwort einbezogen, nachdem das drahtlose gehostete Netzwerk gestartet wurde.
Jede Anwendung, die Beacons sendet oder empfängt, verfügt über eine eigene PSD IE-Datenliste. Der pPsdIEDataList-Parameter verweist auf eine Liste von PSD-IEs, die von der Anwendung generiert wurden. Jeder PSD-IE hat das folgende Format.
| Feld | Beschreibung und Wert |
|---|---|
| Element-ID (1 Byte) | 221 |
| Länge (1 Byte) | Die Länge des Datenfelds in Bytes plus 8. |
| OUI (3 Bytes) | Der organisationsspezifische eindeutige Bezeichner (Organizational Unique Identifier, OUI) muss den Wert 00-50-F2 enthalten. Diese öffentliche OUI ist bei Microsoft registriert. |
| OUI-Typ (1 Byte) | Für das Näherungsdienstermittlungsprotokoll muss der OUI-Typ den Wert 6 enthalten. |
| Formatbezeichnerhash(4 Bytes) | Bits 31-0 des HMAC, die aus dem strFormat-Parameter berechnet werden. |
| Daten (Variable) | Enthält benutzerdefinierte Daten für die Ermittlung. Dieses Feld darf nicht mehr als 240 Bytes lang sein. |
Das Hashfeld Formatbezeichner beschreibt das Format der Informationen, die im PSD IE übertragen werden. Um die Eindeutigkeit sicherzustellen und gleichzeitig die Notwendigkeit einer zentralen Verwaltung von Formatbezeichnern zu umgehen, wird eine Zeichenfolge in Form eines Uniform Resource Identifier (URI) verwendet, wie in RFC 3986 angegeben, um das Format zu unterscheiden. Da die Übertragung jedoch effizient sein muss und der Platz im Informationselement begrenzt ist, wird die Zeichenfolge nicht tatsächlich übertragen, sondern stattdessen ihr Hash übertragen. Auf dem Client, der die empfangende Seite des Beacons ist, wird der Hash mit einer bekannten Gruppe von Formatbezeichnern abgeglichen.
Das Formatbezeichnerhashfeld wird durch Bits 0... 31 eines hashbasierten Nachrichtenauthentifizierungscodes (HMAC) über der Formatbezeichnerzeichenfolge, die im strFormat-Parameter angegeben ist. Der HMAC wird verwendet, um das Format des Felds Daten des PSD IE anzugeben. Die Formel, die zum Berechnen des HMAC verwendet wird, wird in RFC 2104 beschrieben. Beispielcode für die Berechnung des HMAC ist wie in RFC 4634 angegeben. Verwenden Sie beim Berechnen des HMAC SHA-256 für die Hashfunktion. Der verwendete Schlüssel ist der "NULL"-Schlüssel (NULL-Zeiger auf den Authentifizierungsschlüssel und Authentifizierungsschlüssel der Länge null pro Quellcode in RFC 4634). Verwenden Sie den Wert des strFormat-Parameters (einschließlich aller Leerzeichen, aber ohne NULL-Terminierungszeichen) als Eingabetext, der als Unicode UTF-16 im Little-Endian-Format codiert ist.
Wenn der strFormat-Parameter beispielsweise lautet, sind http://schemas.xmlsoaps.org/ws/2004/10/discoverydie ersten vier Oktette des entsprechenden HMAC 0xF8 0xCB 0x35 0x15.
Wenn der strFormat-Parameter ist, sind http://schemas.microsoft.com/networking/discoveryformat/v20xCF 0xF1 0x64 0x17die vier Oktette des entsprechenden HMAC.
Wenn Sie die ersten vier Oktette eines HMAC über das Netzwerk senden, senden Sie zuerst das erste Oktett (links links).
Beachten Sie, dass es zu Kollisionen in den abgeschnittenen HMACs kommen kann, was bedeutet, dass es unmöglich ist, das Ermittlungsprotokoll eindeutig zu bestimmen, das der Nutzlast eines PSD-IE aus den angegebenen Bits eines HMAC entspricht. Eine Anwendung, die einen PSD-IE empfängt, muss das ermittlungsprotokoll, das von einem bestimmten HMAC verwendet wird, am besten erraten und das Ermittlungsprotokoll auf höherer Ebene erneut ausführen, sobald eine Verbindung hergestellt wurde.
Höchstens fünf PSD-IEs können in einer Liste übergeben werden. Außerdem kann die Gesamtlänge der PSD-IE-Liste in Bytes durch Hardwarebeschränkungen für die Länge eines Beacons eingeschränkt werden.
Eine Anwendung kann WlanSetPsdIeDataList mehrmals aufrufen. Wenn WlanSetPsdIeDataList zweimal mit demselben strFormat aufgerufen wird, wird der Inhalt der WLAN_RAW_DATA_LIST durch den ersten Funktionsaufruf aufgefüllt durch die WLAN_RAW_DATA_LIST Nutzlast des zweiten Aufrufs überschrieben. Wenn WlanSetPsdIeDataList aufgerufen wird und der pPsdIEDataList-Parameter auf NULL festgelegt ist, wird die mit strFormat verknüpfte PSD-IE-Liste gelöscht. Wenn WlanSetPsdIeDataList aufgerufen wird, wobei sowohl die Parameter pPsdIEDataList als auch strFormat auf NULL festgelegt sind, werden alle von der Anwendung festgelegten PSD-IE-Listen gelöscht.
Der Drahtlose Dienst verarbeitet PSD-IE-Datenlisten, die von verschiedenen Anwendungen festgelegt wurden, und generiert unformatierte IE-Datenblobs. Wenn ein Computer ein Ad-hoc-Netzwerk auf einem beliebigen Drahtlosadapter erstellt oder verknüpft, sendet er Beacons, die ein dem Netzwerk zugeordnetes PSD IE-Datenblob enthalten, an andere Computer.
Stationen können die WlanExtractPsdIEDataList-Funktion aufrufen, um die PSD IE-Datenliste abzurufen, nachdem sie ein Beacon von einem Computer empfangen haben.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista [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 |