WlanSetProfile function (wlanapi.h)

The WlanSetProfile function sets the content of a specific profile.

Syntax

DWORD WlanSetProfile(
  [in]           HANDLE     hClientHandle,
  [in]           const GUID *pInterfaceGuid,
  [in]           DWORD      dwFlags,
  [in]           LPCWSTR    strProfileXml,
  [in, optional] LPCWSTR    strAllUserProfileSecurity,
  [in]           BOOL       bOverwrite,
  [in]           PVOID      pReserved,
  [out]          DWORD      *pdwReasonCode
);

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] dwFlags

The flags to set on the profile.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  dwFlags must be 0. Per-user profiles are not supported.

[in] strProfileXml

Contains the XML representation of the profile. The WLANProfile element is the root profile element. To view sample profiles, see Wireless Profile Samples. There is no predefined maximum string length.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  The supplied profile must meet the compatibility criteria described in Wireless Profile Compatibility.

[in, optional] strAllUserProfileSecurity

Sets the security descriptor string on the all-user profile. For more information about profile permissions, see the Remarks section.

If dwFlags is set to WLAN_PROFILE_USER, this parameter is ignored.

If this parameter is set to NULL for a new all-user profile, the security descriptor associated with the wlan_secure_add_new_all_user_profiles object is used. If the security descriptor has not been modified by a WlanSetSecuritySettings call, all users have default permissions on a new all-user profile. Call WlanGetSecuritySettings to get the default permissions associated with the wlan_secure_add_new_all_user_profiles object.

If this parameter is set to NULL for an existing all-user profile, the permissions of the profile are not changed.

If this parameter is not NULL for an all-user profile, the security descriptor string associated with the profile is created or modified after the security descriptor object is created and parsed as a string.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  This parameter must be NULL.

[in] bOverwrite

Specifies whether this profile is overwriting an existing profile. If this parameter is FALSE and the profile already exists, the existing profile will not be overwritten and an error will be returned.

[in] pReserved

Reserved for future use. Must be set to NULL.

[out] pdwReasonCode

A WLAN_REASON_CODE value that indicates why the profile is not valid.

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 WlanSetProfile function can be used to add a new wireless LAN profile or replace an existing wireless LAN profile.

A new profile is added at the top of the list after the group policy profiles. A profile's position in the list is not changed if an existing profile is overwritten.Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  

Ad hoc profiles appear after the infrastructure profiles in the profile list. If you create a new ad hoc profile, it is placed at the top of the ad hoc list, after the group policy and infrastructure profiles.

802.1X guest profiles, Wireless Provisioning Service (WPS) profiles, and profiles with Wi-Fi Protected Access-None (WPA-None) authentication are not supported. That means such a profile cannot be created, deleted, enumerated, or accessed using Native Wifi functions. Any such profile already in the preferred profile list will remain in the list, and its position in the list relative to other profiles is fixed unless the position of the other profiles change.

You can call WlanSetProfile on a profile that contains a plaintext key (that is, a profile with the protected element present and set to FALSE). Before the profile is saved in the profile store, the key material is automatically encrypted. When the profile is subsequently retrieved from the profile store by calling WlanGetProfile, the encrypted key material is returned.Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  The key material is never encrypted.

All-user profiles have three associated permissions: read, write, and execute. If a user has read access, the user can view profile permissions. If a user has execute access, the user has read access and the user can also connect to and disconnect from a network using the profile. If a user has write access, the user has execute access and the user can also modify and delete permissions associated with a profile.

The following describes the procedure for creating a security descriptor object and parsing it as a string.

1. Call InitializeSecurityDescriptor to create a security descriptor in memory.
2. Call SetSecurityDescriptorOwner.
3. Call InitializeAcl to create a discretionary access control list (DACL) in memory.
4. Call AddAccessAllowedAce or AddAccessDeniedAce to add access control entries (ACEs) to the DACL. Set the AccessMask parameter to one of the following as appropriate:
   • WLAN_READ_ACCESS
   • WLAN_EXECUTE_ACCESS
   • WLAN_WRITE_ACCESS
5. Call SetSecurityDescriptorDacl to add the DACL to the security descriptor.
6. Call ConvertSecurityDescriptorToStringSecurityDescriptor to convert the descriptor to string.

For every wireless LAN profile used by the Native Wifi AutoConfig service, Windows maintains the concept of custom user data. This custom user data is initially non-existent, but can be set by calling the WlanSetProfileCustomUserData function. The custom user data gets reset to empty any time the profile is modified by calling the WlanSetProfile function. Once custom user data has been set, this data can be accessed using the WlanGetProfileCustomUserData function.

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 WlanSetProfile 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).

The netsh wlan add profile command provides similar functionality at the command line. For more information, see Netsh Commands for Wireless Local Area Network (wlan).

Requirements

See also

ConvertSecurityDescriptorToStringSecurityDescriptor

InitializeAcl

InitializeSecurityDescriptor

Native Wifi API Permissions

SetSecurityDescriptorDacl

WlanGetProfile

WlanGetProfileCustomUserData

WlanGetProfileList

WlanQueryInterface

WlanSetProfileCustomUserData

WlanSetProfileEapUserData

WlanSetProfileEapXmlUserData