Edit

Share via

WlanSetProfileList function (wlanapi.h)

  • Article

The WlanSetProfileList function sets the preference order of profiles for a given interface.

Syntax

DWORD WlanSetProfileList(
  [in] HANDLE     hClientHandle,
  [in] const GUID *pInterfaceGuid,
  [in] DWORD      dwItems,
  [in] LPCWSTR    *strProfileNames,
       PVOID      pReserved
);

Parameters

[in] hClientHandle

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

[in] pInterfaceGuid

The GUID of the interface.

[in] dwItems

The number of profiles in the strProfileNames parameter.

[in] strProfileNames

The names of the profiles in the desired order. Profile names are case-sensitive. This string must be NULL-terminated.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  The supplied names must match the profile names derived automatically from the SSID of the network. For infrastructure network profiles, the SSID must be supplied for the profile name. For ad hoc network profiles, the supplied name must be the SSID of the ad hoc network followed by -adhoc.

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.

Return code Description
ERROR_ACCESS_DENIED
 The caller does not have sufficient permissions to change the profile list.

Before WlanSetProfileList performs an operation that changes the relative order of all-user profiles in the profile list or moves an all-user profile to a lower position in the profile list, WlanSetProfileList retrieves the discretionary access control list (DACL) stored with the wlan_secure_all_user_profiles_order object. If the DACL does not contain an access control entry (ACE) that grants WLAN_WRITE_ACCESS permission to the access token of the calling thread, then WlanSetProfileList returns ERROR_ACCESS_DENIED.
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 invalid.
  • pInterfaceGuid is NULL.
  • dwItems is 0.
  • strProfileNames is NULL.
  • The same profile name appears more than once in strProfileNames.
  • pReserved is not NULL.
ERROR_NOT_FOUND
 strProfileNames contains the name of a profile that is not present in the profile store.
RPC_STATUS
 Various error codes.

Remarks

The WlanSetProfileList function sets the preference order of wireless LAN profiles for a given wireless interface.

The profiles in the list must be a one-to-one match with the current profiles returned by the WlanGetProfileList function. The position of group policy profiles cannot be changed.

All wireless LAN functions require an interface GUID for the wireless interface when performing profile operations. When a wireless interface is removed, its state is cleared from Wireless LAN Service (WLANSVC) and no profile operations are possible.

The WlanSetProfileList function can fail with ERROR_INVALID_PARAMETER if the wireless interface specified in the pInterfaceGuid parameter has been removed from the system (a USB wireless adapter that has been removed, for example).

Requirements

Requirement Value
Minimum supported client Windows Vista, Windows XP with SP3 [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header wlanapi.h (include Wlanapi.h)
Library Wlanapi.lib
DLL Wlanapi.dll
Redistributable Wireless LAN API for Windows XP with SP2

See also

WlanGetProfile

WlanGetProfileList

WlanSetProfile