DOT11EXTIHV_PERFORM_PRE_ASSOCIATE callback function (wlanihv.h)

Article
10/21/2021

Important The Native 802.11 Wireless LAN interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see WLAN Universal Windows driver model.

The operating system calls the Dot11ExtIhvPerformPreAssociate function to request that the IHV Extensions DLL initiate a pre-association operation with the basic service set (BSS) network.

Syntax

DOT11EXTIHV_PERFORM_PRE_ASSOCIATE Dot11extihvPerformPreAssociate;

DWORD Dot11extihvPerformPreAssociate(
  [in, optional] HANDLE hIhvExtAdapter,
  [in, optional] HANDLE hConnectSession,
  [in, optional] PDOT11EXT_IHV_PROFILE_PARAMS pIhvProfileParams,
  [in]           PDOT11EXT_IHV_CONNECTIVITY_PROFILE pIhvConnProfile,
  [in]           PDOT11EXT_IHV_SECURITY_PROFILE pIhvSecProfile,
  [in]           PDOT11_BSS_LIST pConnectableBssid,
  [out]          PDWORD pdwReasonCode
)
{...}

Parameters

[in, optional] hIhvExtAdapter

The handle used by the IHV Extensions DLL to reference the wireless LAN (WLAN) adapter. This handle value was specified through a previous call to the Dot11ExtIhvInitAdapter IHV Handler function.

[in, optional] hConnectSession

The handle used by the operating system to reference the connection session with the basic service set (BSS) network.

[in, optional] pIhvProfileParams

A pointer to a DOT11EXT_IHV_PROFILE_PARAMS structure. This structure defines the attributes of the basic service set (BSS) network to which the profile extensions will be applied.

[in] pIhvConnProfile

A pointer to a DOT11EXT_IHV_CONNECTIVITY_PROFILE structure that contains connectivity settings for the IHV profile.

[in] pIhvSecProfile

A pointer to a DOT11EXT_IHV_SECURITY_PROFILE structure that specifies security settings for the IHV profile.

[in] pConnectableBssid

A pointer to a DOT11_BSS_LIST structure, which contains one or more 802.11 Beacon or Probe Response frames for the service set identifier (SSID) of the BSS network with which the DLL will perform the pre-association operation.

[out] pdwReasonCode

A pointer to a DWORD value, which provides additional information for the return value of the Dot11ExtIhvPerformPreAssociate function. The IHV Extensions DLL must set * pdwReasonCode to an L2_REASON_CODE_xxxx value, which are defined in L2cmn.h.

Return value

If the IHV Extension DLL can initiate the pre-association operation, it must complete the operation asynchronously. In this situation, the function returns ERROR_SUCCESS.

If the IHV Extensions DLL cannot initiate the pre-association operation, it returns an error code defined in Winerror.h.

Remarks

The operating system calls the Dot11ExtIhvPerformPreAssociate function to initiate a pre-association operation with the IHV Extensions DLL. The operating system initiates this operation before it initiates a connection operation with a basic service set (BSS) network through the WLAN adapter. For more information about the connection operation, see Connection Operations.

The pre-association operation must be completed asynchronously from the call to Dot11ExtIhvPerformPreAssociate. After the pre-association operation completes, the IHV Extensions DLL must call Dot11ExtPreAssociateCompletion.

When the Dot11ExtIhvPerformPreAssociate function is called, the IHV Extensions DLL must follow these guidelines.

If the IHV Extensions DLL can initiate the pre-association operation, the Dot11ExtIhvPerformPreAssociate function must return ERROR_SUCCESS and complete the operation asynchronously.
The IHV Extensions DLL provides more information regarding the initiation of the pre-association operation through the pdwReasonCode parameter. The DLL must set * pdwReasonCode to one of the following:
- L2_REASON_CODE_SUCCESS, if the pre-association operation can initiated successfully.
- An appropriate L2_REASON_CODE_xxxx error value, if the pre-association operation could not be initiated.
- An IHV-defined value in the range from L2_REASON_CODE_IHV_BASE to (L2_REASON_CODE_IHV_BASE+ L2_REASON_CODE_GROUP_SIZE-1), regardless of whether the pre-association operation could be initiated or not.

For more information about the pre-association operation, see Pre-Association Operation.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Desktop
Header	wlanihv.h (include Wlanihv.h, L2cmn.h)