Requesting User Interaction

 

At any time after the call to Dot11ExtIhvInitAdapter, the IHV Extensions DLL can request interaction with the user by calling the Dot11ExtSendUIRequest function. The operating system forwards all user interaction requests to the IHV UI Extensions DLL, which will process the request and display the appropriate user interface (UI) pages to the user.

When the request has been completed, the operating system calls the Dot11ExtIhvProcessUIResponse function to forward the results from the IHV UI Extensions DLL for the user interaction. For more information about the IHV UI Extensions DLL, see Native 802.11 IHV UI Extensions DLL.

For example, the IHV Extensions DLL can request user interaction for any of the following.

• Notify the user regarding the stages of a pre or post-association operation.

• Prompt the user to enter his/her credentials for authentication during the post-association operation.

When it calls the Dot11ExtSendUIRequest function, the IHV Extensions DLL passes a pointer to a DOT11EXT_IHV_UI_REQUEST structure to the pIhvUIRequest parameter. The DOT11EXT_IHV_UI_REQUEST structure specifies the request, such as the globally unique ID (GUID), which identifies the UI request as well as the COM class ID (CLSID) of the target UI page that will handle this request.

When the IHV UI Extensions DLL has completed the user notification, the operating system calls the Dot11ExtIhvProcessUIResponse function. If the user had entered any data through the notification, the operating system passes a pointer to the buffer, which contains the data, to the pvResponseBuffer parameter.

The operating system might periodically query the status of pending notification requests. In this situation, the operating system calls the Dot11ExtIhvIsUIRequestPending and passes the GUID of the UI request to the guidUIRequest parameter.

When calling Dot11ExtSendUIRequest, the IHV Extensions DLL must follow these guidelines.

• The IHV Extensions DLL does not need to serialize the calls to Dot11ExtSendUIRequest. The DLL can have more than one pending UI request at any time.

• The UI request for a particular GUID is completed only when Dot11ExtIhvProcessUIResponse is called for that GUID. In this situation, the IHV Extensions DLL must not free any allocated resources for the UI request until Dot11ExtIhvProcessUIResponse is called.

• All pending UI requests are canceled whenever Dot11ExtIhvAdapterReset or Dot11ExtIhvDeinitAdapter is called. All pending UI requests are also canceled whenever Dot11ExtIhvProcessSessionChange is called with the uEventType parameter set to WTS_SESSION_LOGOFF.

  In these situations, the IHV Extensions DLL must free all allocated resources for each pending UI request.

The operating system can initiate user interaction itself whenever the connection state changes on the basic service set (BSS) network. In this situation, the operating system calls the Dot11ExtIhvQueryUIRequest function. The IHV Extensions DLL allocates a buffer and formats it as a DOT11EXT_IHV_UI_REQUEST structure. The DLL sets the members of the DOT11EXT_IHV_UI_REQUEST structure to reference a UI page that is appropriate for the change in connection status. The operating system is responsible for displaying the UI page.

Note  The IHV Extensions must allocate the buffer that contains the DOT11EXT_IHV_UI_REQUEST structure through Dot11ExtAllocateBuffer. The DLL must not free the buffer after returning from Dot11ExtIhvQueryUIRequest.