Migrating to New Initialization and Provisioning APIs (Windows CE 5.0)
The way that VAIL handles initialization and provisioning in Windows CE 5.0 has changed significantly from how it was handled in Windows CE .NET 4.2.
In summary, Windows CE .NET 4.2 tied the retrieval and use of provisioning information together, while Windows CE 5.0 separates the management of the data from the use of the data.
In Windows CE .NET 4.2, the VAIL handled both retrieving and using provisioning information. To do this, it used directory client objects that retrieved provisioning information from an LDAP server, file, or string. These objects were accessible using the now unsupported IVoIPDirectoryClient interface.
In Windows CE 5.0, the VAIL provides a single configuration data store object that manages provisioning and other setting information. Applications — like the TUI — access this object through the IVoIPConfigurationDataStore interface.
The IVoIPConfigurationDataStore interface manages provisioning information, but doesn't handle provisioning itself. For this, application code — again, like code in the TUI — calls the IVoIPMgr2::RegisterWithSIPServer method and passes information it has retrieved using the data store.
This topic summarizes the changes but does not provide detailed information about provisioning. For this information about provisioning using the configuration data store, see IP Phone Provisioning.
SYSGEN Variable Changes
The following SYSGEN variables are no longer supported:
- SYSGEN_VOIPPHONE_FILEPROV
- SYSGEN_VOIPPHONE_LDAPPROV
- SYSGEN_VOIPPHONE_MANPROV
Instead, the IP phone design template uses this SYSGEN variable:
- SYSGEN_VOIPPHONE_CONFIGURATIONSTORE
SYSGEN_VOIPPHONE_CONFIGURATIONSTORE brings in support for provisioning from an XML file, from a string containing XML, and from an LDAP server.
API Changes
In Windows CE .NET 4.2, application code used the IVoIPMgr::Initialize and IVoIPMgr::Reregister methods, along with the IVoIPMgr::Parameters, VoIPMgrParameters, and DirectoryClientRegParams elements.
Windows CE 5.0 does not support these elements. Instead, application code, like code in the TUI, uses the configuration data store.
The data store is an object that provides settings. Behind the scenes, the object loads these settings from the registry, from an XML file or string containing XML, or from an LDAP server.
Instead of calling IVoIPMgr::Initialize, code now calls IVoIPMgr2::InitializeEx. InitializeEx takes only a reference to an IVoIPUI implementation, in contrast to Initialize, which also took an VoIPMgrParameters structure.
In Windows CE .NET 4.2, the Initialize implementation uses data in the VoIPMgrParameters structure to connect via a directory client object and ultimately retrieve provisioning information.
In Windows CE 5.0, application code uses the configuration data store directly to retrieve the provisioning information.
Similarly, instead of calling IVoIPMgr::Reregister, code now calls IVoIPMgr2::RegisterWithSIPServer. The contents of the SIPServerRegistrationParameters structure expected by RegisterWithSIPServer can be retrieved by application code using the data store.
For example code that calls InitializeEx, see the TUI CVoIPApp::InitializeVoIPMgr method in the VoIPApp.cpp file in %_WINCEROOT%\Public\VoIP\Oak\Phone\TUI\App.
To see how the TUI registers with the SIP server by first using the data store to retrieve provisioning information and then calling RegisterWithSIPServer, examine the CVoIPApp::ReprovisionVoIPMgr method, also in VoIPApp.cpp.
File Format Changes
Windows CE .NET 4.2 used a provisioning file that the file directory client understood.
The Windows CE 5.0 configuration data store uses an XML provisioning file with a different schema: the root element has the name VoIPConfiguration, and can contain any number of elements with names as specified in the CONFIG_DATA_ topic.
For example XML that follows this format, see Configuration Data Store Example XML.
See Also
VAIL Migration | Provisioning the TUI Application
Send Feedback on this topic to the authors