Export (0) Print
Expand All
Expand Minimize

WlanSetInterface function

The WlanSetInterface function sets user-configurable parameters for a specified interface.

Syntax


DWORD WINAPI WlanSetInterface(
  _In_        HANDLE hClientHandle,
  _In_        const GUID *pInterfaceGuid,
  _In_        WLAN_INTF_OPCODE OpCode,
  _In_        DWORD dwDataSize,
  _In_        const PVOID pData,
  _Reserved_  PVOID pReserved
);

Parameters

hClientHandle [in]

The client's session handle, obtained by a previous call to the WlanOpenHandle function.

pInterfaceGuid [in]

The GUID of the interface to be configured.

OpCode [in]

A WLAN_INTF_OPCODE value that specifies the parameter to be set. The following table lists the valid constants along with the data type of the parameter in pData.

WLAN_INTF_OPCODE valuepData data typeDescription

wlan_intf_opcode_autoconf_enabled

BOOL

Enables or disables auto config for the indicated interface.

wlan_intf_opcode_background_scan_enabled

BOOL

Enables or disables background scan for the indicated interface.

wlan_intf_opcode_radio_state

WLAN_PHY_RADIO_STATE

Sets the software radio state of a specific physical layer (PHY) for the interface.

wlan_intf_opcode_bss_type

DOT11_BSS_TYPE

Sets the BSS type.

wlan_intf_opcode_media_streaming_mode

BOOL

Sets media streaming mode for the driver.

wlan_intf_opcode_current_operation_mode

ULONG

Sets the current operation mode for the interface. For more information, see Remarks.

 

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  Only the wlan_intf_opcode_autoconf_enabled and wlan_intf_opcode_bss_type constants are valid.

dwDataSize [in]

The size of the pData parameter, in bytes. If dwDataSize is larger than the actual amount of memory allocated to pData, then an access violation will occur in the calling program.

pData [in]

The value to be set as specified by the OpCode parameter. The type of data pointed to by pData must be appropriate for the specified OpCode. Use the table above to determine the type of data to use.

Note  If OpCode is set to wlan_intf_opcode_autoconf_enabled, wlan_intf_opcode_background_scan_enabled, or wlan_intf_opcode_media_streaming_mode, then pData may point to an integer value. If pData points to 0, then the value is converted to FALSE. If pData points to a nonzero integer, then the value is converted to TRUE.

pReserved

Reserved for future use. Must be set to 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.

ERROR_ACCESS_DENIED

The caller does not have sufficient permissions to perform the requested operation.

Before WlanSetInterface performs an operation, it retrieves the discretionary access control list (DACL) stored with the securable object associated with the specified OpCode. If the DACL does not contain an access control entry (ACE) that grants WLAN_WRITE_ACCESS permission to the thread token of the calling thread, then WlanSetInterface returns ERROR_ACCESS_DENIED.

The following table shows the securable objects associated with each OpCode.

OpCodeSecurable object

wlan_intf_opcode_autoconf_enabled

wlan_secure_ac_enabled

wlan_intf_opcode_background_scan_enabled

wlan_secure_bc_scan_enabled

wlan_intf_opcode_bss_type

wlan_secure_bss_type

wlan_intf_opcode_current_operation_mode

wlan_secure_current_operation_mode

wlan_intf_opcode_media_streaming_mode

wlan_secure_media_streaming_mode_enabled

wlan_intf_opcode_radio_state

None, if running as console user; wlan_secure_interface_properties if not running as console user.

All other values

wlan_secure_interface_properties

 

By default, only a user who is logged on as a member of the Administrators group or the Network Configuration Operators group can set the operation mode of the interface. These default permissions can be changed by calling the WlanSetSecuritySettings function with SecurableObject set to wlan_secure_current_operation_mode.

ERROR_GEN_FAILURE

The parameter specified by OpCode is not supported by the driver or NIC.

ERROR_INVALID_HANDLE

The handle hClientHandle was not found in the handle table.

ERROR_INVALID_PARAMETER

One of the following conditions occurred.

  • hClientHandle is NULL or not valid
  • pInterfaceGuid is NULL.
  • pData is NULL.
  • pReserved is not NULL.
  • OpCode is set to wlan_intf_opcode_current_operation_mode and pData points to a value other than DOT11_OPERATION_MODE_EXTENSIBLE_STATION or DOT11_OPERATION_MODE_NETWORK_MONITOR.
RPC_STATUS

Various return codes to indicate errors occurred when connecting.

Remarks

When OpCode is set to wlan_intf_opcode_current_operation_mode, the WlanSetInterface function sets the current operation mode of the wireless interface. For more information about operation modes, see Native 802.11 Operation Modes. Two operation modes are supported: DOT11_OPERATION_MODE_EXTENSIBLE_STATION and DOT11_OPERATION_MODE_NETWORK_MONITOR. The operation mode constants are defined in the header file Windot11.h. If pData does not point to one of these values when OpCode is set to wlan_intf_opcode_current_operation_mode, the WlanSetInterface function will fail with an error.

To enable or disable the automatic configuration service at the command line, which is functionally equivalent to calling WlanSetInterface with OpCode set to wlan_intf_opcode_autoconf_enabled, use the netsh wlan setautoconfig command. For more information, see Netsh Commands for Wireless Local Area Network (wlan).

The software radio state can be changed by calling the WlanSetInterface function. The hardware radio state cannot be changed by calling the WlanSetInterface function. When the OpCode parameter is set to wlan_intf_opcode_radio_state, the WlanSetInterface function sets the software radio state of a specific PHY. The pData parameter must point to a WLAN_PHY_RADIO_STATE structure with the new radio state values to use. The dot11HardwareRadioState member of the WLAN_PHY_RADIO_STATE structure is ignored when the WlanSetInterface function is called with the OpCode parameter set to wlan_intf_opcode_radio_state and the pData parameter points to a WLAN_PHY_RADIO_STATE structure. The radio state of a PHY is off if either the software radio state (dot11SoftwareRadioState member of the WLAN_PHY_RADIO_STATE structure) or the hardware radio state (dot11HardwareRadioState member of the WLAN_PHY_RADIO_STATE structure) is off.

Changing the software radio state of a physical network interface could cause related changes in the state of the wireless Hosted Network or virtual wireless adapter radio states. The PHYs of every virtual wireless adapter are linked. For more information, see the About the Wireless Hosted Network.

Requirements

Minimum supported client

Windows Vista, Windows XP with SP3 [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Redistributable

Wireless LAN API for Windows XP with SP2

Header

Wlanapi.h (include Wlanapi.h)

Library

Wlanapi.lib

DLL

Wlanapi.dll

See also

About the Wireless Hosted Network
DOT11_BSS_TYPE
WLAN_INTF_OPCODE
WLAN_PHY_RADIO_STATE
WlanQueryInterface

 

 

Community Additions

ADD
Show:
© 2014 Microsoft