WlanSetPsdIEDataList (Compact 2013)

  • Article

3/26/2014

This function sets the proximity service discovery (PSD) information element (IE) data list.

Syntax

DWORD WINAPI WlanSetPsdIEDataList(
  __in        HANDLE hClientHandle,
  __in        LPCWSTR strFormat,
  __in        const PWLAN_RAW_DATA_LIST pPsdIEDataList,
  __reserved  PVOID pReserved
);

Parameters

  • hClientHandle
    The client's session handle, obtained by a previous call to the WlanOpenHandle function.
  • strFormat
    Describes the format of a PSD IE. This is a NULL-terminated URI string that specifies the namespace of the protocol that is used for discovery.
  • pPsdIEDataList
    Pointer to a WLAN_RAW_DATA_LIST structure that contains the data list to be set.
  • pReserved
    Reserved; set to NULL.

Return Values

Value

Description

ERROR_SUCCESS

The function succeeds

ERROR_INVALID_PARAMETER

hClientHandle is NULL or invalid or pReserved is not NULL

ERROR_INVALID_HANDLE

The handle hClientHandle was not found in the handle table

ERROR_NOT_SUPPORTED

This function was called from an unsupported platform

RPC_STATUS

Various error codes

Remarks

A PSD IE is used to transmit compressed information that is provided by higher-level discovery protocols, such as the WS-Discovery protocol, for passive discovery. Any protocol can be used for discovery. Each application that sends or receives beacons maintains its own PSD IE data list. The pPsdIEDataList is used to generate a list of PSD IEs. Each IE has the following format:

Field

Value

Element ID

221

Length

Length of payload bytes + 8

OUI

00:52:f2

OUI Type

6

Format

Bits 31-0 of the HMAC computed from strFormat

Payload

pDataBlob member of WLAN_RAW_DATA. Must not exceed 240 bytes

The Element ID, Length, OUI, and Type fields are controlled by the automatic configuration service. The application controls the remaining fields.

The Format field contains the first four octets of a hash-based message authentication code (HMAC). The HMAC is used to specify the format of the payload of an IE. The formula used to calculate the HMAC is described in RFC 2104. When calculating the HMAC:

  • use SHA-256 for the hash function
  • use no key
  • use the value of strFormat (including any spaces but excluding the NULL-termination character) as the input text

For example, if strFormat is http://schemas.xmlsoaps.org/ws/2004/10/discovery, the first 32 bits of the corresponding HMAC is 0x1535CBF8. If strFormat is https://schemas.microsoft.com/networking/discoveryformat/v2, the first 32 bits of the corresponding HMAC is 0x1764F1CF.

When sending the first 32 bits of an HMAC over the network, send the low-order bit first.

Collisions in the truncated HMACs might indicate that it is impossible to uniquely determine the discovery protocol that corresponds to the payload of an IE from the given bits of an HMAC. An application receiving an IE must take a best guess at the discovery protocol that is used from a given HMAC, and then rerun the higher-level discovery protocol after a connection has been established.

A maximum of five IEs can be passed in a list. The total length (in bytes) of the IE list can be restricted by hardware limitations on the length of a beacon.

An application can call WlanSetPsdIeDataList many times. When WlanSetPsdIEDataList is called two times 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 by using pPsdIEDataList set to NULL, the IE list associated with strFormat is cleared. When WlanSetPsdIeDataList is called by using pPsdIEDataList and strFormat set to null, all IE lists set by the application are cleared.

The wireless service processes PSD IE data lists that are set by varying applications, and generates raw IE data blobs. When a computer creates or joins an ad hoc network on any wireless adapter, it sends beacons that include an IE data blob associated with the network to other computers.

Stations can call WlanExtractPsdIEDataList to retrieve the PSD IE data list after they have received a beacon from a computer.

See Also

Reference

Native Wi-Fi Functions
WlanOpenHandle
WLAN_RAW_DATA_LIST
WlanSetPsdIEDataList
WlanExtractPsdIEDataList
Native Wi-Fi Reference