Fonction WlanSetPsdIEDataList (wlanapi.h)
La fonction WlanSetPsdIeDataList définit la liste de données des éléments d’information de découverte de service de proximité (IE).
Syntaxe
DWORD WlanSetPsdIEDataList(
[in] HANDLE hClientHandle,
[in] LPCWSTR strFormat,
[in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
PVOID pReserved
);
Paramètres
[in] hClientHandle
Le handle de session du client, obtenu par un appel précédent à la fonction WlanOpenHandle .
[in] strFormat
Format d’un IE PSD dans la liste de données PSD IE transmise dans le paramètre pPsdIEDataList . Il s’agit d’une chaîne d’URI terminée par null qui spécifie l’espace de noms du protocole utilisé pour la découverte.
[in] pPsdIEDataList
Pointeur vers une structure de WLAN_RAW_DATA_LIST qui contient la liste de données PSD IE à définir.
pReserved
Réservé pour un usage futur. Doit être défini sur NULL.
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.
| Code de retour | Description |
|---|---|
|
Un paramètre est incorrect. Cette erreur est retournée si le hClientHandle a la valeur NULL ou n’est pas valide ou si pReserved n’est pas NULL. |
|
Le handle hClientHandle est introuvable dans la table handle. |
|
Cette fonction a été appelée à partir d’une plateforme non prise en charge. Cette valeur est retournée si la fonction a été appelée à partir d’un windows XP avec SP3 ou API LAN sans fil pour Windows XP avec client SP2. |
|
Différents codes d’erreur. |
Remarques
Le protocole de découverte du service de proximité est un protocole propriétaire Microsoft qui permet à un client de découvrir les services dans sa proximité physique, définie par la plage radio. L’objectif du protocole de découverte de service de proximité est de transmettre des informations de découverte de service, telles que des publicités de service, dans le cadre des trames Beacon. Les points d’accès (AP) et les stations (STA) qui fonctionnent en mode ad hoc diffusent régulièrement des images de balise. La trame de balise peut contenir un ou plusieurs éléments d’informations propriétaires qui contiennent des informations de découverte relatives aux services offerts par l’appareil.
Un IE PSD est utilisé pour transmettre des informations compressées fournies par des protocoles de découverte de niveau supérieur à des fins de découverte passive. Un protocole de niveau supérieur utilisé pour la découverte est le protocole WS-Discovery. N’importe quel protocole peut être utilisé pour la découverte.
Windows Vista et Windows Server 2008 avec le service LAN sans fil installé prennent en charge la découverte passive pour les clients ad hoc, les services ad hoc et les clients d’infrastructure. Cela signifie qu’un service ad hoc peut publier une ressource ou un service disponible en transmettant un IE PSD dans une ou plusieurs balises. Il n’est pas garanti que cette balise soit reçue par un client ad hoc ou d’infrastructure.
Windows 7 et Windows Server 2008 R2 avec le service LAN sans fil installé prend en charge la découverte passive pour les clients ad hoc, les services ad hoc et les clients d’infrastructure de la même manière que dans Windows Vista. En outre, LE DSP IE est également pris en charge pour le réseau hébergé sans fil, un point d’accès sans fil basé sur un logiciel. Les applications sur l’ordinateur local sur lequel le réseau hébergé sans fil doit être exécuté peuvent utiliser la fonction WlanSetPsdIeDataList pour définir l’IE PSD avant de démarrer le réseau hébergé sans fil. Une fois défini, l’IE PSD est inclus dans la réponse de balise et de sonde après le démarrage du réseau hébergé sans fil.
Chaque application qui envoie ou reçoit des balises conserve sa propre liste de données PSD IE. Le paramètre pPsdIEDataList pointe vers une liste d’EE PSD générées par l’application. Chaque IE PSD a le format suivant.
| Champ | Description et valeur |
|---|---|
| ID d’élément (1 octet) | 221 |
| Longueur (1 octet) | Longueur, en octets, du champ Données plus 8. |
| OUI (3 octets) | L’identificateur unique d’organisation (OUI) doit contenir une valeur de 00-50-F2. Ce OUI public est inscrit auprès de Microsoft. |
| Type OUI (1 octet) | Pour le protocole de découverte du service de proximité, le type OUI doit contenir la valeur 6. |
| Hachage de l’identificateur de format(4 octets) | Bits 31-0 du HMAC calculé à partir du paramètre strFormat . |
| Données (variable) | Contient des données définies par l’utilisateur pour la découverte. Ce champ ne doit pas dépasser 240 octets. |
Le champ De hachage de l’identificateur de format décrit le format des informations transmises dans l’IE PSD. Pour garantir l’unicité tout en contournant la nécessité d’une administration centrale des identificateurs de format, une chaîne sous la forme d’un URI (Uniform Resource Identifier), comme spécifié dans la RFC 3986, est utilisée pour distinguer le format. Toutefois, étant donné que la transmission doit être efficace et que l’espace dans l’élément d’information est limité, la chaîne n’est pas réellement transmise, mais, au lieu de cela, son hachage est transmis. Sur le client, qui est le côté récepteur de la balise, le hachage est mis en correspondance avec un ensemble connu d’identificateurs de format.
Le champ De hachage de l’identificateur de format est représenté par les bits 0... 31 d’un code d’authentification de message basé sur le hachage (HMAC) sur la chaîne d’identificateur de format spécifiée dans le paramètre strFormat . Le HMAC est utilisé pour spécifier le format du champ Données de l’IE PSD. La formule utilisée pour calculer le HMAC est décrite dans RFC 2104. L’exemple de code pour le calcul du HMAC est spécifié dans RFC 4634. Lorsque vous calculez le HMAC, utilisez SHA-256 pour la fonction de hachage. La clé utilisée est la clé « null » (pointeur NULL vers la clé d’authentification et clé d’authentification de longueur nulle selon le code source dans RFC 4634). Utilisez la valeur du paramètre strFormat (y compris tous les espaces, mais à l’exclusion du caractère de terminaison NULL) comme texte d’entrée encodé en Unicode UTF-16 au format little endian.
Par exemple, si le paramètre strFormat est http://schemas.xmlsoaps.org/ws/2004/10/discovery, les quatre premiers octets du HMAC correspondant sont 0xF8 0xCB 0x35 0x15.
Si le paramètre strFormat est http://schemas.microsoft.com/networking/discoveryformat/v2, les quatre octets du HMAC correspondant sont 0xCF 0xF1 0x64 0x17.
Lors de l’envoi des 4 premiers octets d’un HMAC sur le réseau, envoyez d’abord le premier octet (le plus à gauche).
Notez qu’il peut y avoir des collisions dans les HMAC tronqués, ce qui signifie qu’il peut être impossible de déterminer de manière unique le protocole de découverte correspondant à la charge utile d’un IE PSD à partir des bits donnés d’un HMAC. Une application recevant un IE PSD doit vérifier au mieux le protocole de découverte utilisé à partir d’un HMAC donné, puis réexécuter le protocole de découverte de niveau supérieur une fois qu’une connexion a été établie.
Au maximum, cinq EE PSD peuvent être passées dans une liste. En outre, la longueur totale, en octets, de la liste IE PSD peut être limitée par des limitations matérielles sur la longueur d’une balise.
Une application peut appeler WlanSetPsdIeDataList plusieurs fois. Lorsque WlanSetPsdIeDataList est appelé deux fois avec le même strFormat, le contenu du WLAN_RAW_DATA_LIST rempli par le premier appel de fonction est remplacé par la charge utile WLAN_RAW_DATA_LIST du deuxième appel. Lorsque WlanSetPsdIeDataList est appelé avec le paramètre pPsdIEDataList défini sur NULL, la liste IE PSD associée à strFormat est effacée. Lorsque WlanSetPsdIeDataList est appelé avec les paramètres pPsdIEDataList et strFormat définis sur NULL, toutes les listes PSD IE définies par l’application sont effacées.
Le service sans fil traite les listes de données IE PSD définies par différentes applications et génère des objets blob de données IE bruts. Lorsqu’une machine crée ou joint un réseau ad hoc sur une carte sans fil, elle envoie des balises qui incluent un objet blob de données IE PSD associé au réseau à d’autres machines.
Les stations peuvent appeler la fonction WlanExtractPsdIEDataList pour obtenir la liste de données PSD IE après avoir reçu une balise à partir d’une machine.
Spécifications
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | wlanapi.h (inclure Wlanapi.h) |
| Bibliothèque | Wlanapi.lib |
| DLL | Wlanapi.dll |