WlanSetProfile (Compact 2013)

3/26/2014

This function sets the content of a profile.

Syntax

DWORD WINAPI WlanSetProfile(
  __in        HANDLE hClientHandle,
  __in        const GUID* pInterfaceGuid,
  __reserved  DWORD dwReserved,
  __in        LPCWSTR strProfileXml,
  __reserved  PVOID pReserved1,
  __in        BOOL bOverwrite,
  __reserved  PVOID pReserved2,
  __out       DWORD* pdwReasonCode
);

Parameters

Term	Definition
hClientHandle	[in] Handle to the session on the client. To obtain a handle, call WlanOpenHandle.
pInterfaceGuid	[in] GUID of the interface.
dwReserved	Reserved; Must be 0 (zero).
strProfileXml	[in] The XML representation of the profile. There is no predefined maximum string length. The WLANProfile Element is the root profile element. For information about sample profiles, see Wi-Fi Profile Samples.
pReserved1	Reserved; Must be NULL.
bOverwrite	[in] Determines whether to overwrite an existing profile. For a profile that already exists, set this parameter to FALSE to protect the existing profile and return an error.
pReserved2	Reserved; Must be NULL.
pdwReasonCode	[out] A WLAN_REASON_CODE value that indicates why the profile is not valid.

Return Values

The following table shows the possible return values.

Value	Description
ERROR_SUCCESS	The function succeeds.
ERROR_ACCESS_DENIED	You included Connection Manager in your OS.
ERROR_ALREADY_EXISTS	bOverwrite is FALSE and strProfileXml specifies a network that already exists, or bOverwrite is TRUE and dwFlags specifies a different profile type than the one used by the existing profile.
ERROR_BAD_PROFILE	The profile specified by strProfileXml is not valid. If the function returns this value, pdwReasonCode specifies the reason the profile is invalid.
ERROR_INVALID_PARAMETER	One of the following conditions occurred: hClientHandle is NULL or invalid pInterfaceGuid is NULL dwReserved is not 0 pReserved1 is not NULL pReserved2 is not NULL strProfileXml is NULL strProfileXml contains a zero-length ConfigBlob If the profile must have an empty ConfigBlob, use <ConfigBlob>00</ConfigBlob> in the profile. pdwReasonCode is NULL bOverwrite is set to FALSE
ERROR_INVALID_HANDLE	The handle hClientHandle was not found in the handle table.
ERROR_NO_MATCH	The interface does not support one or more of the capabilities specified in the profile, for example, if the profile specifies the use of WPA2 when the network adapter only supports WPA.
RPC_STATUS	Can be any Remote Procedure Call (RPC) error code. The RPC call may be unsuccessful due to Wlan RPC server issues, such as when the RPC server is not started. Refer to RPC for more information.

Remarks

If you include Connection Manager in your OS design:

• You must handle Wi-Fi connection operations using Connection Manager APIs such as CmAcquireConnection, CmAddConnectionConfig, or CmReleaseConnection.
• Otherwise, if you use this API, it returns ERROR_ACCESS_DENIED.

If the function overwrites an existing profile, the position of the profile in the list does not change.

You can call this function on a profile that contains a plaintext key, a profile with the protected element set to FALSE. Before the function saves the profile in the profile store, it automatically encrypts the key material. When you later retrieve the profile from the profile store by calling WlanGetProfile, you get the encrypted key material.

See Also

Reference

Native Wi-Fi Functions
WlanOpenHandle
WLANProfile Element
WLAN_REASON_CODE
WlanGetProfile
WlanQueryInterface
Native Wi-Fi Reference