IP Phone Suite Provisioning API (Windows Embedded CE 6.0)

1/6/2010

The following provisioning APIs are exposed through the PhCommon component (phcommon.dll). OEMs can incorporate these APIs into custom provisioning applications.

PHProcessProvisionXML

Configures VoIP settings according to the specified XML data.

Syntax

            HRESULT PHProcessProvisionXML(
 const WCHAR*  pInputBuffer,
       WCHAR** ppOutputBuffer
     );

Parameters

• pInputBuffer
  The input XML buffer containing the provision data. It can also be used to specify a XML file name. See "Remarks" for more information.

• ppOutputBuffer
  (Optional) Pointer to the output XML buffer. The caller of this function is responsible for cleanup of the output buffer referenced by this parameter. Memory is allocated in the implementation by means of the new [] operator. Thus, the caller must use the delete [] <varname> statement to free the output buffer.

Return Value

Returns the standard HRESULT values. S_OK indicates success. The following table shows additional error codes that may be returned.

Value	Description
PROVISION_E_MULTIPLE_SETTINGS	There are multiple operations on the same setting(s) in the XML file
PROVISION_E_INVALID_SETTING	One of the settings is invalid

Remarks

The pInputBuffer parameter can contain explicit provisioning information (a string or pointer to a string containing the provisioning data), or it can contain the pathname of a provisioning XML file.

The ppOutputBuffer parameter is optional. Set this parameter to NULL when an output value is not required.

Examples:

1. String containing explicit provisioning information:

PHProcessProvisionXML("<voip-provision><set name='VoicemailNumber' value='5555551212' /></voip-provision>", NULL);

2. Pathname of provisioning XML file:

PHProcessProvisionXML("file:\\\Windows\provisioning.xml", NULL);

3. Input parameter contains a <query> operation. The result of the query is returned in the string pointed to by ppQueryResult:

PHProcessProvisionXML("<voip-provision><query name='VoicemailSettings'/></voip-provision>",ppQueryResult);

Requirements

Header	phoneapi.hpp
Library	PhCommon.dll
Windows Embedded CE	Windows Embedded CE 6.0

PHValidateProvisionXML

This function performs run time validation of the specified XML provisioning data.

Syntax

            HRESULT PHValidateProvisionXML(
  const WCHAR*   pInputBuffer
);

Parameters

• pInputBuffer
  The input XML buffer containing the provision data. It can also be used to specify a XML file name.

Return Value

Returns the standard HRESULT values. S_OK indicates success and valid input XML. The following table shows additional error codes that may be returned.

Value	Description
PROVISION_E_MULTIPLE_SETTINGS	There are multiple operations on the same setting(s) in the XML file
PROVISION_E_INVALID_SETTING	One of the settings is invalid

Remarks

The pInputBuffer parameter can contain explicit provisioning information (a string or pointer to a string containing the provisioning data), or it can contain the pathname of a provisioning XML file. For example:

Examples:

1. String containing explicit provisioning information.

PHValidateProvisionXML("<voip-provision><set name='VoicemailNumber' value='5555551212' /></voip-provision>");

2. Pathname of provisioning XML file.

PHValidateProvisionXML("file:\\\Windows\provisioning.xml");

Requirements

Header	phoneapi.hpp
Library	PhCommon.dll
Windows Embedded CE	Windows Embedded CE 6.0

See Also

Concepts

IP Phone Suite Provisioning
IP Phone Suite Provisioning Examples