TwclWiFiHostedNetwork.SetKey(Cardinal,Pointer,Boolean,Boolean) Method

The method configures the secondary security key that will be used by the wireless Hosted Network.

Namespace: wclWiFi
Delphi
public
 function SetKey(const KeyLength: Cardinal; const KeyData: Pointer;
 const IsPassPhrase: Boolean; const Persistent: Boolean): Integer;

Parameters

KeyLength
Type: Cardinal

The number of valid data bytes in the key data array pointed to by the KeyData parameter. This key length should include the terminating 0 if the key is a passphrase.

KeyData
Type: Pointer

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 KeyLength parameter.

IsPassPhrase
Type: Boolean

A Boolean value that indicates if the key data array pointed to by the KeyData 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.

Persistent
Type: Boolean

A Boolean value that indicates if the key data array pointed to by the KeyData 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).

Return Value

Type: Integer

 

A client application calls the SetKey method 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 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 KeyData 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 KeyLength parameter should include the terminating 0 in the passphrase. The value of the KeyLength parameter should be in the range of 9 to 64.
  • A binary key that consists of 32 bytes of binary key data. The KeyLength parameter should be 32 for binary key.

To configure a valid secondary security key, the KeyLength parameter should be in the correct range and the KeyData 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 SetKey method with zero in KeyLength parameter and nil in the KeyData parameter.

The SetKey method will return wclWiFiErrors.WCL_E_WIFI_INVALID_ARGUMENT if the KeyData parameter is nil, but the KeyLength parameter is not zero. The SetKey method will also return wclWiFiErrors.WCL_E_WIFI_INVALID_ARGUMENT if the KeyLength parameter is zero, but KeyData parameter is not nil.

The secondary security key can be specified as persistent if the Persistent parameter is set to True. When specified as persistent, the secondary security key would be used immediately 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, 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.