WlanSetPsdIEDataList function (wlanapi.h)
The WlanSetPsdIeDataList function sets the proximity service discovery (PSD) information element (IE) data list.
Syntax
DWORD WlanSetPsdIEDataList(
[in] HANDLE hClientHandle,
[in] LPCWSTR strFormat,
[in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
PVOID pReserved
);
Parameters
[in] hClientHandle
The client's session handle, obtained by a previous call to the WlanOpenHandle function.
[in] strFormat
The format of a PSD IE in the PSD IE data list passed in the pPsdIEDataList parameter. This is a NULL-terminated URI string that specifies the namespace of the protocol used for discovery.
[in] pPsdIEDataList
A pointer to a WLAN_RAW_DATA_LIST structure that contains the PSD IE data list to be set.
pReserved
Reserved for future use. Must be set to NULL.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value may be one of the following return codes.
| Return code | Description |
|---|---|
|
A parameter is incorrect. This error is returned if the hClientHandle is NULL or not valid or pReserved is not NULL. |
|
The handle hClientHandle was not found in the handle table. |
|
This function was called from an unsupported platform. This value is returned if the function was called from a Windows XP with SP3 or Wireless LAN API for Windows XP with SP2 client. |
|
Various error codes. |
Remarks
The Proximity Service Discovery Protocol is a Microsoft proprietary protocol that allows a client to discover services in its physical proximity, which is defined by the radio range. The purpose of the Proximity Service Discovery Protocol is to convey service discovery information, such as service advertisements, as part of Beacon frames. Access points (APs) and stations (STAs) that operate in ad hoc mode periodically broadcast beacon frames. The beacon frame can contain single or multiple proprietary information elements that carry discovery information pertaining to the services that the device offers.
A PSD IE is used to transmit compressed information provided by higher-level discovery protocols for the purpose of passive discovery. One such higher-level protocol used for discovery is the WS-Discovery protocol. Any protocol can be used for discovery.
Windows Vista and Windows Server 2008 with the Wireless LAN Service installed support passive discovery for ad hoc clients, ad hoc services, and infrastructure clients. This means an ad hoc service can advertise an available resource or service by transmitting a PSD IE in one or more beacons. There is no guarantee that this beacon is received by an ad hoc or infrastructure client.
Windows 7 and Windows Server 2008 R2 with the Wireless LAN Service installed support passive discovery for ad hoc clients, ad hoc services, and infrastructure clients in the same way as in Windows Vista. In addition, the PSD IE is also supported for the wireless Hosted Network, a software-based wireless access point (AP). Applications on the local computer where the wireless Hosted Network is to be run may use the WlanSetPsdIeDataList function to set the PSD IE before starting the wireless Hosted Network. Once set, the PSD IE will be included in the beacon and probe response after the wireless Hosted Network is started.
Each application sending or receiving beacons maintains its own PSD IE data list. The pPsdIEDataList parameter points to a list of PSD IEs generated by the application. Each PSD IE has the following format.
| Field | Description and Value |
|---|---|
| Element ID (1 byte) | 221 |
| Length (1 byte) | The length, in bytes, of Data field plus 8. |
| OUI (3 bytes) | The Organizational Unique Identifier (OUI) must contain a value of 00-50-F2. This public OUI is registered to Microsoft. |
| OUI Type (1 byte) | For the Proximity Service Discovery Protocol, the OUI Type must contain a value of 6. |
| Format identifier hash(4 bytes) | Bits 31-0 of the HMAC computed from the strFormat parameter. |
| Data (variable) | Contains user-defined data for discovery. This field must not exceed 240 bytes in length. |
The Format identifier hash field describes the format of the information carried in the PSD IE. To ensure uniqueness while circumventing the need for central administration of format identifiers, a string in the form of a Uniform Resource Identifier (URI), as specified in RFC 3986, is used to distinguish the format. However, because the transmission must be efficient and space in the information element is limited, the string is not actually transmitted, but, instead, its hash is transmitted. On the client, which is the receiving side of the beacon, the hash is matched against a known set of format identifiers.
The Format identifier hash field is represented by bits 0…31 of a hash-based message authentication code (HMAC) over the format identifier string specified in the strFormat parameter. The HMAC is used to specify the format of the Data field of the PSD IE. The formula used to calculate the HMAC is described in RFC 2104. Sample code for the calculation of the HMAC is as specified in RFC 4634. When calculating the HMAC, use SHA-256 for the hash function. The key used is the "null" key (NULL pointer to the authentication key, and zero length authentication key per the source code in RFC 4634). Use the value of strFormat parameter (including any spaces but excluding the NULL-termination character) as the input text encoded as Unicode UTF-16 in little-endian format.
For example, if the strFormat parameter is http://schemas.xmlsoaps.org/ws/2004/10/discovery, then the first four octets of the corresponding HMAC is 0xF8 0xCB 0x35 0x15.
If the strFormat parameter is http://schemas.microsoft.com/networking/discoveryformat/v2, then the four octets of the corresponding HMAC are 0xCF 0xF1 0x64 0x17.
When sending the first 4 octets of an HMAC over the network, send the first (left-most) octet first.
Note that there may be collisions in the truncated HMACs, which means that it may be impossible to uniquely determine the discovery protocol corresponding to the payload of a PSD IE from the given bits of an HMAC. An application receiving a PSD IE must take a best guess at the discovery protocol used from a given HMAC, then re-run the higher-level discovery protocol once a connection has been established.
At most, five PSD IEs can be passed in a list. Also, the total length, in bytes, of the PSD IE list may be restricted by hardware limitations on the length of a beacon.
An application can call WlanSetPsdIeDataList many times. When WlanSetPsdIeDataList is called twice with the same strFormat, the contents of the WLAN_RAW_DATA_LIST populated by the first function call are overwritten by the second call's WLAN_RAW_DATA_LIST payload. When WlanSetPsdIeDataList is called with the pPsdIEDataList parameter set to NULL, the PSD IE list associated with strFormat is cleared. When WlanSetPsdIeDataList is called with both the pPsdIEDataList and strFormat parameters set to NULL, all PSD IE lists set by the application are cleared.
The wireless service processes PSD IE data lists set by different applications and generates raw IE data blobs. When a machine creates or joins an ad-hoc network on any wireless adapter, it sends beacons that include a PSD IE data blob associated with the network to other machines.
Stations can call WlanExtractPsdIEDataList function to get the PSD IE data list after receiving a beacon from a machine.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | wlanapi.h (include Wlanapi.h) |
| Library | Wlanapi.lib |
| DLL | Wlanapi.dll |