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

Reads the secondary security key that is configured to be used by the wireless Hosted Network.

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

Parameters

KeyLength
Type: Cardinal

A value that specifies number of valid data bytes in the key data array pointed to by the KeyData parameter, if the call to the method succeeds.

This key length includes the terminating 0 if the key is a passphrase.

KeyData
Type: Pointer

A value that receives a pointer to the buffer returned with the secondary security key data, if the call to the method succeeds.

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 for one-time use only.

Return Value

Type: Integer

If the function succeeds, the return value is wclErrors.WCL_E_SUCCESS. If the function fails, the return value may be one of the WCL return codes.

A client application calls the GetKey method to query the secondary security key that will be used by the wireless Hosted Network. This function will return the key information including key data, key length, whether it is a passphrase, and whether it is persistent or for one-time use. This function does not change the state or properties of the wireless Hosted Network.

The secondary security key is a passphrase if the value of the IsPassPhrase parameter is True. The secondary security key is a binary key if the value of the "IsPassPhrase" parameter is False.

The secondary security key returned in the buffer pointed to authentication and is in one of the following formats:

  • A key passphrase that consists of an array of ASCII characters from 8 to 63 characters. The value of the KeyLength parameter includes 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 conists of 32 bytes of binary key data. The value of the KeyLength parameter should be 32 for binary key.

The secondary security key is persistent if the value of the Persistent parameter is True. When 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 the 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.

If there is no secondary security key currently configured, the returned value of the KeyLength parameter will be zero, and the value returned in the KeyData parameter will be nil. In such case, the value returned in the IsPassPhrase and Persistent parameters will be meaningless.

If the method succeeds, the memory used for the buffer in the KeyData parameter that is returned should be freed after use by calling the FreeMemory method.