WlanHostedNetworkForceStart function (wlanapi.h)

The WlanHostedNetworkForceStart function transitions the wireless Hosted Network to the wlan_hosted_network_active state without associating the request with the application's calling handle.

Syntax

DWORD WlanHostedNetworkForceStart(
  [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 WlanHostedNetworkForceStart 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 WlanHostedNetworkForceStart 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 WlanHostedNetworkForceStart function to force the start of the wireless Hosted Network by transitioning the wireless Hosted Network to the wlan_hosted_network_active state without associating the request with the application's calling handle. A successful call to the WlanHostedNetworkForceStart function should eventually be matched by a call to WlanHostedNetworkForceStop function. 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.

The cost of calling the WlanHostedNetworkForceStart function over calling WlanHostedNetworkStartUsing is the associated privilege required. An application might call the WlanHostedNetworkForceStart function after ensuring that an elevated system user accepts the increased power requirements involved in running the wireless Hosted Network for extended durations.

The WlanHostedNetworkForceStart function could fail if Hosted Network state is wlan_hosted_network_unavailable or the caller does not have sufficient privileges.

This function to force the start of the Hosted Network can only be called if the user has the appropriate associated privilege. Permissions are stored in a discretionary access control list (DACL) associated with a WLAN_SECURABLE_OBJECT. To call the WlanHostedNetworkForceStart, the client access token of the caller must have elevated privileges exposed by the following enumeration in WLAN_SECURABLE_OBJECT:

• wlan_secure_hosted_network_elevated_access

The ability to enable the wireless Hosted Network may also 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

See also

About the Wireless Hosted Network

Using Wireless Hosted Network and Internet Connection Sharing

WLAN_HOSTED_NETWORK_REASON

WLAN_SECURABLE_OBJECT

WlanCloseHandle

WlanEnumInterfaces

WlanHostedNetworkForceStop

WlanHostedNetworkQueryStatus

WlanHostedNetworkStartUsing

WlanHostedNetworkStopUsing

WlanOpenHandle