Funzione WlanSetPsdIEDataList (wlanapi.h)
La funzione WlanSetPsdIeDataList imposta l'elenco di dati di individuazione dei servizi di prossimità (PSD).
Sintassi
DWORD WlanSetPsdIEDataList(
[in] HANDLE hClientHandle,
[in] LPCWSTR strFormat,
[in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
PVOID pReserved
);
Parametri
[in] hClientHandle
Handle di sessione del client ottenuto da una chiamata precedente alla funzione WlanOpenHandle .
[in] strFormat
Formato di un IE PSD nell'elenco di dati PSD IE passato nel parametro pPsdIEDataList . Si tratta di una stringa URI con terminazione NULL che specifica lo spazio dei nomi del protocollo usato per l'individuazione.
[in] pPsdIEDataList
Puntatore a una struttura WLAN_RAW_DATA_LIST contenente l'elenco di dati PSD IE da impostare.
pReserved
Riservato per utilizzi futuri. Deve essere impostato su NULL.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito può essere uno dei codici restituiti seguenti.
| Codice restituito | Descrizione |
|---|---|
|
Un parametro non è corretto. Questo errore viene restituito se hClientHandle è NULL o non valido o pReserved non è NULL. |
|
L'handle hClientHandle non è stato trovato nella tabella handle. |
|
Questa funzione è stata chiamata da una piattaforma non supportata. Questo valore viene restituito se la funzione è stata chiamata da un'API Windows XP con SP3 o WIRELESS LAN per Windows XP con il client SP2. |
|
Vari codici di errore. |
Commenti
Il protocollo di individuazione dei servizi di prossimità è un protocollo proprietario Microsoft che consente a un client di individuare i servizi nella sua prossimità fisica, definita dall'intervallo di radio. Lo scopo del protocollo di individuazione dei servizi di prossimità consiste nel trasmettere informazioni di individuazione dei servizi, ad esempio annunci di servizio, come parte dei fotogrammi di Beacon. Punti di accesso (APS) e stazioni (STA) che operano in modalità ad hoc fotogrammi di beacon di trasmissione periodica. Il frame del beacon può contenere elementi informativi proprietari o singoli che contengono informazioni di individuazione relative ai servizi offerti dal dispositivo.
Un IE PSD viene usato per trasmettere informazioni compresse fornite da protocolli di individuazione di livello superiore per lo scopo dell'individuazione passiva. Un protocollo di questo livello superiore usato per l'individuazione è il protocollo di WS-Discovery. Qualsiasi protocollo può essere usato per l'individuazione.
Windows Vista e Windows Server 2008 con il servizio LAN wireless installato supportano l'individuazione passiva per client ad hoc, servizi ad hoc e client di infrastruttura. Ciò significa che un servizio ad hoc può annunciare una risorsa o un servizio disponibile trasmettendo un'IE PSD in uno o più beacon. Non vi è alcuna garanzia che questo beacon venga ricevuto da un client ad hoc o infrastruttura.
Windows 7 e Windows Server 2008 R2 con il servizio LAN wireless supportano l'individuazione passiva per client ad hoc, servizi ad hoc e client di infrastruttura nello stesso modo di Windows Vista. Inoltre, l'IE PSD è supportato anche per la rete ospitata wireless, un punto di accesso wireless basato su software (AP). Le applicazioni nel computer locale in cui deve essere eseguita la rete ospitata wireless possono usare la funzione WlanSetPsdIeDataList per impostare l'IE PSD prima di avviare la rete ospitata wireless. Dopo aver impostato, l'IE PSD verrà incluso nella risposta di beacon e probe dopo l'avvio della rete ospitata wireless.
Ogni applicazione che invia o riceve i beacon gestisce un proprio elenco di dati DI IE PSD. Il parametro pPsdIEDataList punta a un elenco di IES PSD generati dall'applicazione. Ogni IE PSD ha il formato seguente.
| Campo | Descrizione e valore |
|---|---|
| ID elemento (1 byte) | 221 |
| Lunghezza (1 byte) | Lunghezza, in byte, del campo Dati più 8. |
| OUI (3 byte) | L'identificatore univoco dell'organizzazione deve contenere un valore pari a 00-50-F2. Questa OUI pubblica è registrata in Microsoft. |
| Tipo OUI (1 byte) | Per il protocollo di individuazione dei servizi di prossimità, il tipo OUI deve contenere un valore pari a 6. |
| Hash dell'identificatore di formato(4 byte) | Bit 31-0 di HMAC calcolati dal parametro strFormat . |
| Dati (variabile) | Contiene dati definiti dall'utente per l'individuazione. Questo campo non deve superare i 240 byte di lunghezza. |
Il campo Hash identificatore formato descrive il formato delle informazioni trasportate nell'IE PSD. Per garantire l'univocità mentre si evita la necessità di amministrazione centrale degli identificatori di formato, viene usata una stringa sotto forma di URI (Uniform Resource Identifier), come specificato in RFC 3986, per distinguere il formato. Tuttavia, poiché la trasmissione deve essere efficiente e lo spazio nell'elemento informativo è limitato, la stringa non viene effettivamente trasmessa, ma, invece, il relativo hash viene trasmesso. Nel client, che rappresenta il lato ricevente del beacon, l'hash viene confrontato con un set noto di identificatori di formato.
Il campo Hash identificatore formato è rappresentato da bit 0... 31 di un codice di autenticazione del messaggio basato su hash (HMAC) sulla stringa di identificatore di formato specificata nel parametro strFormat . HMAC viene usato per specificare il formato del campo Dati dell'IE PSD. La formula usata per calcolare HMAC è descritta in RFC 2104. Il codice di esempio per il calcolo di HMAC è specificato in RFC 4634. Quando si calcola HMAC, usare SHA-256 per la funzione hash. La chiave usata è la chiave "Null" (puntatore NULL alla chiave di autenticazione e chiave di autenticazione zero per il codice sorgente in RFC 4634). Usare il valore del parametro strFormat (inclusi gli spazi, ma esclusi il carattere di terminazione NULL) come testo di input codificato come formato UTF-16 Unicode in formato little-endian.
Ad esempio, se il parametro strFormat è http://schemas.xmlsoaps.org/ws/2004/10/discovery, i primi quattro ottetti del corrispondente HMAC sono 0xF8 0xCB 0x35 0x15.
Se il parametro strFormat è http://schemas.microsoft.com/networking/discoveryformat/v2, i quattro ottetti del corrispondente HMAC sono 0xCF 0xF1 0x64 0x17.
Quando si inviano i primi 4 ottetti di un HMAC sulla rete, inviare prima il primo ottetto (a sinistra).
Si noti che potrebbero esserci collisioni nelle HMAC troncate, che significa che potrebbe essere impossibile determinare in modo univoco il protocollo di individuazione corrispondente al payload di un'IE PSD dai bit specificati di un HMAC. Un'applicazione che riceve un IE PSD deve accettare una migliore ipotesi nel protocollo di individuazione usato da un determinato HMAC, quindi eseguire nuovamente il protocollo di individuazione di livello superiore dopo aver stabilito una connessione.
Al massimo, cinque IES PSD possono essere passati in un elenco. Inoltre, la lunghezza totale, in byte, dell'elenco di IE PSD può essere limitata dalle limitazioni hardware sulla lunghezza di un beacon.
Un'applicazione può chiamare WlanSetPsdIeDataList molte volte. Quando WlanSetPsdIeDataList viene chiamato due volte con lo stesso strFormat, il contenuto del WLAN_RAW_DATA_LIST popolato dalla prima chiamata di funzione viene sovrascritto dal payload WLAN_RAW_DATA_LIST della seconda chiamata. Quando WlanSetPsdIeDataList viene chiamato con il parametro pPsdIEDataList impostato su NULL, l'elenco di IE PSD associato a strFormat viene cancellato. Quando WlanSetPsdIeDataList viene chiamato con entrambi i parametri pPsdIEDataList e strFormat impostati su NULL, tutti gli elenchi di IE PSD impostati dall'applicazione vengono cancellati.
Il servizio wireless elabora gli elenchi di dati PSD IE impostati da applicazioni diverse e genera BLOB di dati IE non elaborati. Quando un computer crea o aggiunge una rete ad hoc in qualsiasi scheda wireless, invia i beacon che includono un BLOB di dati PSD IE associato alla rete ad altri computer.
Le stazioni possono chiamare la funzione WlanExtractPsdIEDataList per ottenere l'elenco di dati PSD IE dopo aver ricevuto un beacon da un computer.
Requisiti
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | wlanapi.h (include Wlanapi.h) |
| Libreria | Wlanapi.lib |
| DLL | Wlanapi.dll |