IP Phone Suite Provisioning API
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
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