Compartir a través de

IProvisioningProfileWireless::CreateProfile method

  • Artículo

Note  Wireless Provisioning Services (WPS) is no longer available as of Windows Vista.

 

The CreateProfile method enables the dynamic configuration of a new profile in the preferred profile list using XML.

Syntax

HRESULT CreateProfile(
  [in]  BSTR  bstrXMLWirelessConfigProfile,
  [in]  BSTR  bstrXMLConnectionConfigProfile,
  [in]  GUID  *pAdapterInstanceGuid,
  [out] ULONG *pulStatus
);

Parameters

  • bstrXMLWirelessConfigProfile [in]
    String containing the XML data for the wireless profile. This XML data must be in the format defined for the WirelessProfile schema.

  • bstrXMLConnectionConfigProfile [in]
    String containing the XML data for the connection settings associated with the wireless profile.

    Note   This parameter is not supported on Windows XP with Service Pack 2 and must be set to NULL on this operating system.

     

  • pAdapterInstanceGuid [in]
    GUID identifying the device on which this profile is to be applied. The GUID value can be derived through the EnumComponents or FindComponent methods of the INetCfg interface.

  • pulStatus [out]
    A pointer to a status field used to return a service-specific failure code. These codes are associated with the return value to provide a more detailed reason for the failure.

Return value

If the method succeeds, the return value is S_OK; otherwise, returns one of the following codes:

Return code Description
ERROR_BAD_PROFILE

The method call has failed.
ERROR_BAD_CONFIGURATION

The method call has failed.
ERROR_CREATE_FAILED

The wireless profile was not created.
ERROR_CONNECTION_INVALID

The object has already been added to another collection.

 

Remarks

If the return value is non-zero, then the value of the pulStatus parameter can be used to provide more information about the failure:

  • If the value of the pulStatus parameter is WZC_PROFILE_SUCCESS (0), the error is related to system configuration or validation of the XML data.

  • If the value of the pulStatus parameter is non-zero, the error is related to a problem with the XML data specified by the bstrXMLWirelessConfigProfile parameter.

The following table defines the mapping between the return value and the value of the pulStatus parameter:

Return value pulStatus value

ERROR_BAD_PROFILE

WZC_PROFILE_XML_* error codes

ERROR_BAD_CONFIGURATION

WZC_PROFILE_CONFIG_* error codes

ERROR_CREATE_FAILED

WZC_PROFILE_SET_* and WZC_PROFILE_API_* error codes

 

The following are the error codes defined for the pulStatus parameter. Refer to the WirelessProfile schema and its validation rules for more information regarding the XML data elements.

  • WZC_PROFILE_XML_ERROR_NO_VERSION
    The Version element was not found in the XML data.

  • WZC_PROFILE_XML_ERROR_BAD_VERSION
    A failure occurred while reading the Version element from the XML data.

  • WZC_PROFILE_XML_ERROR_UNSUPPORTED_VERSION
    The Version element specified a value that is not supported.

    Note   For Windows XP with SP2 and Windows Server 2003 with SP1, the Version element must be set to 1.

     

  • WZC_PROFILE_XML_ERROR_SSID_NOT_FOUND
    The ssid element was not found in the XML data.

  • WZC_PROFILE_XML_ERROR_BAD_SSID
    The ssid element specified an invalid SSID string. This string must contain 1-32 characters.

  • WZC_PROFILE_XML_ERROR_CONNECTION_TYPE
    Either the connectionType element was not found in the XML data or the element specified an invalid connection method.

  • WZC_PROFILE_XML_ERROR_AUTHENTICATION
    Either the authentication element was not found in the XML data or the element specified an invalid authentication method.

  • WZC_PROFILE_XML_ERROR_ENCRYPTION
    Either the encryption element was not found in the XML data or the element specified an invalid encryption method.

  • WZC_PROFILE_XML_ERROR_KEY_PROVIDED_AUTOMATICALLY
    Either the keyProvidedAutomatically element was not found in the XML data or the element specified an invalid value.

  • WZC_PROFILE_XML_ERROR_1X_ENABLED
    Either the IEEE802.1XEnabled element was not found in the XML data or the element specified an invalid value.

  • WZC_PROFILE_XML_ERROR_EAP_METHOD
    The EAPMethod element was set to an invalid value.

  • WZC_PROFILE_XML_ERROR_BAD_KEY_INDEX
    The keyIndex element was set to a non-numeric value

  • WZC_PROFILE_XML_ERROR_KEY_INDEX_RANGE
    The keyIndex element was set to an invalid numeric value. This element must be set to a value in the range of 1-4.

  • WZC_PROFILE_XML_ERROR_BAD_NETWORK_KEY
    The networkKey element was set to a value that was invalid for the specified encryption method.

  • WZC_PROFILE_CONFIG_ERROR_INVALID_AUTH_FOR_CONNECTION_TYPE
    The authentication element was set to an authentication method not supported by the specified connection method. For example, this error will occur if the authentication element is set to WPA and the connection element is set to IBSS.

  • WZC_PROFILE_CONFIG_ERROR_INVALID_ENCRYPTION_FOR_AUTHMODE
    The encryption element was set to an encryption method not supported by the specified authentication method. For example, this error will occur if the encryption element is set to AES and the authentication element is set to Open.

  • WZC_PROFILE_CONFIG_ERROR_KEY_REQUIRED
    The networkKey element was not found in the XML data but the keyProvidedAutomatically element was set to 0.

    Note   This error is not applicable if the authentication element is set to Open and the encryption element is set to None.

     

  • WZC_PROFILE_CONFIG_ERROR_KEY_INDEX_REQUIRED
    The keyIndex element was not found in the XML data and the keyProvidedAutomatically element was set to 1.

    Note   This error is applicable if the authentication element is set to Open or Shared.

     

  • WZC_PROFILE_CONFIG_ERROR_KEY_INDEX_NOT_APPLICABLE
    The keyIndex element specified a valid index value but either the keyProvidedAutomatically element was set to 1 or the authentication element was set to WPAPSK, WPA2PSK, or WPA-None.

  • WZC_PROFILE_CONFIG_ERROR_1X_NOT_ALLOWED
    The IEEE802.1XEnabled element was set to 1 but either the connection element was set to IBSS or the encryption element was set to None.

  • WZC_PROFILE_CONFIG_ERROR_1X_NOT_ALLOWED_KEY_REQUIRED
    The IEEE802.1XEnabled element was set to 1 but the keyProvidedAutomatically element was set to 0 and the networkKey element was not found in the XML data.

  • WZC_PROFILE_CONFIG_ERROR_1X_NOT_ENABLED_KEY_PROVIDED
    The IEEE802.1XEnabled element was set to 0 but the keyProvidedAutomatically element was set to 1.

  • WZC_PROFILE_CONFIG_ERROR_EAP_METHOD_REQUIRED
    The EAPMethod element was not found in the XML data but the IEEE802.1XEnabled element was set to 1.

  • WZC_PROFILE_CONFIG_ERROR_EAP_METHOD_NOT_APPLICABLE
    The EAPMethod element was found in the XML data but the IEEE802.1XEnabled element was set to 1.

  • WZC_PROFILE_CONFIG_ERROR_WPA_NOT_SUPPORTED
    The wireless device (as specified by the pAdapterInstanceGuid parameter) does not support the authentication method specified by the authentication element.

  • WZC_PROFILE_CONFIG_ERROR_WPA_ENCRYPTION_NOT_SUPPORTED
    The wireless device (as specified by the pAdapterInstanceGuid parameter) does not support the encryption method specified by the encryption element.

  • WZC_PROFILE_SET_ERROR_DUPLICATE_NETWORK
    A wireless profile defined by the XML data cannot be created. Another profile for the same SSID and connection method currently exists on the client. The user must first manually remove the existing wireless profile before running the WISP application again.

  • WZC_PROFILE_SET_ERROR_MEMORY_ALLOCATION
    The CreateProfile call failed due to a lack of available memory.

  • WZC_PROFILE_SET_ERROR_READING_1X_CONFIG
    The interface to the Wireless Zero Configuration service failed when reading the 802.1X configuration for the wireless profile defined by the XML data.

  • WZC_PROFILE_SET_ERROR_WRITING_1X_CONFIG
    The interface to the Wireless Zero Configuration service failed when writing the 802.1X configuration for the wireless profile defined by the XML data.

  • WZC_PROFILE_SET_ERROR_WRITING_WZC_CFG
    The interface to the Wireless Zero Configuration service failed when creating the wireless profile defined by the XML data.

  • WZC_PROFILE_API_ERROR_NOT_SUPPORTED
    The bstrXMLConnectionConfigProfile parameter contained a non-NULL value, which is not supported by the operating system. On Windows XP with SP2, the bstrXMLConnectionConfigProfile parameter must be NULL.

  • WZC_PROFILE_API_ERROR_FAILED_TO_LOAD_XML
    The XML data could not be loaded for validation. This could occur if the XML data is not formatted correctly.

  • WZC_PROFILE_API_ERROR_FAILED_TO_LOAD_SCHEMA
    The WirelessProfile schema could not be loaded to validate the XML data.

  • WZC_PROFILE_API_ERROR_XML_VALIDATION_FAILED
    A failure occurred while validating the XML data against the WirelessProfile schema.

  • WZC_PROFILE_API_ERROR_INTERNAL
    An internal system error occurred while processing the XML data.

Requirements

Target platform

 Desktop

Version

Not available beginning with Windows Vista.

Header

 Netprov.h (include Netprov.h)

See also

WirelessProfile Schema

Validation Rules

Preferred Profile Provisioning

 

 

Send comments about this topic to Microsoft