WlanHostedNetworkSetSecondaryKey function (wlanapi.h)
The WlanHostedNetworkSetSecondaryKey function configures the secondary security key that will be used by the wireless Hosted Network.
Syntax
DWORD WlanHostedNetworkSetSecondaryKey(
[in] HANDLE hClientHandle,
[in] DWORD dwKeyLength,
[in] PUCHAR pucKeyData,
[in] BOOL bIsPassPhrase,
[in] BOOL bPersistent,
[out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
PVOID pvReserved
);
Parameters
[in] hClientHandle
The client's session handle, returned by a previous call to the WlanOpenHandle function.
[in] dwKeyLength
The number of valid data bytes in the key data array pointed to by the pucKeyData parameter. This key length should include the terminating ‘\0’ if the key is a passphrase.
[in] pucKeyData
A pointer to a buffer that contains the key data. The number of valid data bytes in the buffer must be at least the value specified in dwKeyLength parameter.
[in] bIsPassPhrase
A Boolean value that indicates if the key data array pointed to by the pucKeyData parameter is in passphrase format.
If this parameter is TRUE, the key data array is in passphrase format. If this parameter is FALSE, the key data array is not in passphrase format.
[in] bPersistent
A Boolean value that indicates if the key data array pointed to by the pucKeyData parameter is to be stored and reused later or is for one-time use only.
If this parameter is TRUE, the key data array is to be stored and reused later. If this parameter is FALSE, the key data array is to be used for one session (either the current session or the next session if the Hosted Network is not started).
[out, optional] pFailReason
An optional pointer to a value that receives the failure reason, if the call to the WlanHostedNetworkSetSecondaryKey function fails. Possible values for the failure reason are from the WLAN_HOSTED_NETWORK_REASON enumeration type defined in the Wlanapi.h header file.
pvReserved
Reserved for future use. This parameter must be 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 handle is invalid. This error is returned if the handle specified in the hClientHandle parameter was not found in the handle table. |
|
A parameter is incorrect. This error is returned if any of the following conditions occur:
|
|
The resource is not in the correct state to perform the requested operation. This can occur if the wireless Hosted Network was in the process of shutting down. |
|
The service has not been started. This error is returned if the WLAN AutoConfig Service is not running. |
|
Various RPC and other error codes. Use FormatMessage to obtain the message string for the returned error. |
Remarks
The WlanHostedNetworkSetSecondaryKey function is an extension to native wireless APIs added to support the wireless Hosted Network on Windows 7 and on Windows Server 2008 R2 with the Wireless LAN Service installed.
A client application calls the WlanHostedNetworkSetSecondaryKey function to configure the secondary security key that will be used by the wireless Hosted Network. Any Hosted Network change caused by this function would not be automatically undone if the calling application closes its calling handle (by calling WlanCloseHandle with the hClientHandle parameter) or if the process ends.
Once started, the wireless Hosted Network will allow wireless peers to associate with this secondary security key in addition to the primary security key. The secondary security key is always specified by the user as needed, while the primary security key is generated by the operating system with greater security strength.
The secondary security key passed in the buffer pointed to by the pucKeyData parameter is used with WPA2-Personal authentication and should be in one of the following formats:
- A key passphrase that consists of an array of ASCII characters from 8 to 63 characters. The dwKeyLength parameter should include the terminating ‘\0’ in the passphrase. The value of the dwKeyLength parameter should be in the range of 9 to 64.
- A binary key that consists of 32 bytes of binary key data. The dwKeyLength parameter should be 32 for binary key.
To configure a valid secondary security key, the dwKeyLength parameter should be in the correct range and the pucKeyData parameter should point to a valid memory buffer containing the specified bytes of data. To remove the currently configured secondary security key from the system, the application should call the WlanHostedNetworkSetSecondaryKey function with zero in dwKeyLength parameter and NULL in the pucKeyData parameter.
The WlanHostedNetworkSetSecondaryKey function will return ERROR_INVALID_PARAMETER if the pucKeyData parameter is NULL, but the dwKeyLength parameter is not zero. The WlanHostedNetworkSetSecondaryKey function will also return ERROR_INVALID_PARAMETER if the dwKeyLength parameter is zero, but pucKeyData parameter is not NULL.
The secondary security key is usually set before the wireless Hosted Network is started. Then it will be used the next time when the Hosted Network is started.
A secondary security key can also be set after the Hosted Network has been started. In this case, the secondary security key will be used immediately. Any clients using the previous secondary security key will remain connected, but they will be unable to reconnect if they get disconnected for any reason or if the wireless Hosted Network is restarted.
The secondary security key can be specified as persistent if the bPersistent parameter is set to TRUE. When specified as persistent, the secondary security key would be used immediately if the Hosted Network is already started, and also reused whenever Hosted Network is started in the future.
If secondary security key is not specified as persistent, it will be used immediately if the Hosted Network is already started, or only for the next time when Hosted Network is started. After the Hosted Network is stopped, this secondary security key will never be used again and will be removed from the system.
Any user can call this function to configure the secondary security key to be used in the Hosted Network. However, the ability to enable the wireless Hosted Network may be restricted by group policy in a domain.
On Windows 7 and later, the operating system installs a virtual device if a Hosted Network capable wireless adapter is present on the machine. This virtual device normally shows up in the “Network Connections Folder” as ‘Wireless Network Connection 2’ with a Device Name of ‘Microsoft Virtual WiFi Miniport adapter’ if the computer has a single wireless network adapter. This virtual device is used exclusively for performing software access point (SoftAP) connections and is not present in the list returned by the WlanEnumInterfaces function. The lifetime of this virtual device is tied to the physical wireless adapter. If the physical wireless adapter is disabled, this virtual device will be removed as well. This feature is also available on Windows Server 2008 R2 with the Wireless LAN Service installed.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Target Platform | Windows |
| Header | wlanapi.h (include Wlanapi.h) |
| Library | Wlanapi.lib |
| DLL | Wlanapi.dll |
See also
About the Wireless Hosted Network
Using Wireless Hosted Network and Internet Connection Sharing
WlanHostedNetworkQueryProperty
WlanHostedNetworkQuerySecondaryKey