WlanHostedNetworkInitSettings function (wlanapi.h)

The WlanHostedNetworkInitSettings function configures and persists to storage the network connection settings (SSID and maximum number of peers, for example) on the wireless Hosted Network if these settings are not already configured.

Syntax

DWORD WlanHostedNetworkInitSettings(
  [in]            HANDLE                      hClientHandle,
  [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.

[out, optional] pFailReason

An optional pointer to a value that receives the failure reason if the call to the WlanHostedNetworkInitSettings 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.

Remarks

The WlanHostedNetworkInitSettings 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 WlanHostedNetworkInitSettings function to configure and persist to storage the network connection settings (SSID and maximum number of peers, for example) on the wireless Hosted Network, if the connections settings are not already configured. If the network settings on the wireless Hosted Network settings are already configured (the WlanHostedNetworkQueryProperty function does not return ERROR_BAD_CONFIGURATION for the station profile or connection settings), then this function call returns ERROR_SUCCESS without changing the configuration of the network connection settings.

A client application should always call the WlanHostedNetworkInitSettings function before using other Hosted Network features on the local computer. This function initializes settings that are required when the wireless Hosted Network is used for the first time on a local computer. The WlanHostedNetworkInitSettings function does not change any configuration if the configuration has already been persisted. So it is safe to call the WlanHostedNetworkInitSettings function if the configuration has already been persisted. It is recommended that applications that use Hosted Network call the WlanHostedNetworkInitSettings function before using other Hosted Network functions.

The WlanHostedNetworkInitSettings function computes a random and readable SSID from the host name and computes a random primary key. This function also uses sets a value for the maximum number of peers allowed that defaults to 100. If an application wants to use a different SSID or a different maximum number of peers, then the application should call the WlanHostedNetworkSetProperty function to specifically set these properties used by the wireless Hosted Network.

Any Hosted Network state 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.

Any user can call the WlanHostedNetworkInitSettings function to configure and persist to storage network connection settings on the Hosted Network. If the wireless Hosted Network has already been configured, this function does nothing and returns ERROR_SUCCESS.

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

See also

About the Wireless Hosted Network

Using Wireless Hosted Network and Internet Connection Sharing

WLAN_HOSTED_NETWORK_REASON

WLAN_SECURABLE_OBJECT

WlanCloseHandle

WlanEnumInterfaces

WlanHostedNetworkQueryProperty

WlanHostedNetworkQuerySecondaryKey

WlanHostedNetworkQueryStatus

WlanHostedNetworkRefreshSecuritySettings

WlanHostedNetworkSetProperty

WlanHostedNetworkSetSecondaryKey

WlanOpenHandle