Share via

WlanSetProfile (Compact 7)

  • Article

3/12/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:

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