Using the VAIL Database Store and Call Logging
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/27/2008
The VAIL Database Store uses the following interfaces for persistent database storage:
- IVoIPCallLogDB stores call log records. These records indicate the type, start time, end time, and duration of the call, and the name and URI of the other party.
- IVoIPCallerInfoDB stores caller-specific information, such as friendly name, speed dial index, specialized ring tone, blocked status, and forwarding URI.
These interfaces are pluggable and have implementations that can be replaced.
The supplied implementations use Windows Embedded CE databases and store information locally on the device. You can replace either database implementation by replacing the CLSID in the registry with the CLSID of your new implementation.
The VAIL Database Store uses CEDB
By default, the VAIL Database Store creates persistent databases using the Windows Embedded CE Database engine (CEDB). For more information about CEDB, please review the File Systems and Storage Management help section, especially, Databases, Object Store and the Database Reference.
The databases are created in the Object Store at the root of the store. The databases are persistent so that changes in the databases are saved across reboots. You can change the default location of the databases to wherever you wish, for example, a FLASH disk, rather than a hard disk.
The name of the database volume created by the VAIL Database Store is "VoIP DB Vol" but this is also changeable. This name is defined by the constant VOIP_DB_VOL_NAME which is located in the file db.h.
The Call Log and Caller Info databases
The call log and caller information databases created are instances of this database. Also, the names of these created databases can be altered. Currently, they take the root name, the "Database Name" registry value, from the registry, plus a prefix of one of the following: "In:", "Ot:", "Ms:" or "CI:" These names correspond to the Incoming Call database, Outgoing Call database, Missed Call database and Caller Info database. The database name from the registry would be the URI of the call. These names are assigned during the Init() methods of the Call Log and Caller Info database interfaces.
If the call to the registry fails, then the default database name, "VoIPDB" is used in its place--again with the prefixes already mentioned.
Please see the Init() methods for the IVoIPCallLogDB or IVoIPCallerInfoDB interfaces in the files, VoIPCallLogDB.cpp and VoIPCallerInfoDB.cpp, respectively.
These files, including db.h, can be found in the VAIL Database source code in %_WINCEROOT%\Public\VoIP\Oak\Phone\Database\Core.
To change the default name used if the registry retrieval fails, look at the constant, c_DefaultDatabaseName, in the file DatabaseAPI.cpp. That file is located in %_WINCEROOT%\Public\ VoIP\Oak\Phone\Common\DatabaseAPI.
To change "Database Name" registry value to something else, please look at the registry value constant SN_VOIP_DBNAME_VALUE in voipnotify.hpp. It can be found in the following directory, %_WINCEROOT%\Public\ VoIP\Oak\Phone\INC. For more information about VoIP Registry settings and values, please see IP Phone Suite Registry Settings .
While the size of the database is only limited by available memory, the implementation used by the VoIP Phone Suite limits the size of the Call Log database to 100 entries.
If more than this number are added, the oldest records are dropped first in order to make room for the new incoming records.
To change this value, see the c_CallLogDBCapacity in the file DatabaseAPI.cpp located in %_WINCEROOT%\Public\ VoIP\Oak\Phone\Common\DatabaseAPI.
This limitation does not apply to the Caller Info database.
Replacing the VAIL Database Store
To replace the database implementation entirely with another different implementation, change the CLSID used in the VoIP Phone Suite for the Call Log database or Caller Info database. You could replace any usage of the target CLSID directly in the code.
The VoIP Phone Suite uses wrapper functions found in databaseapi.cpp to initialize the VAIL Database Store. You could replace the CLSID's used there directly, for example, CLSID_VoIPCallerInfoDB or CLSID_VoIPCallLogDB.
You could also search for the CLSID's in the registry and change them directly in the registry.
Steps to Initialize and Use a Database
You initialize each database by performing the following steps:
- Call CoCreateInstance using the CLSID retrieved from the registry.
- Call IUnknown::QueryInterface for IID_IVoIPCallLogDB or IID_IVoIPCallerInfoDB.
- Call IVoIPCallLogDB::Init or IVoIPCallerInfoDB::Init with the URI of the phone used in provisioning.
- Create a new call record for the database using either IVoIPCallLogDB::CreateRecord or IVoIPCallerInfoDB::CreateRecord.
Modify the record as needed during or after the call and then commit it to the database when the call is finished or the caller information needs updating.
Your application is responsible for gathering the information needed for the record. Both the IP Dialer and the IP Contacts component applications of the VoIP Phone Suite use the VAIL Database Store. They can give you ideas on how to track, use and commit database records. In particular, look at VoIPCall_t::LogCallIfNecessary in the file, voipcall.cpp. This file is part of the IP Dialer application.
Likewise, the main function calls into the VAIL Database Store from IP Dialer can be found in database.cpp.
Both voipcall.cpp and database.cpp can be found in the following directory: %_WINCEROOT%\Public\VoIP\Oak\Phone\PhoneApp\PhoneCore.
Also, the wrapper functions used by the VoIP Phone Suite for the databases can be found in databaseapi.cpp in the following directory: %_WINCEROOT%\Public\VoIP\Oak\Phone\common\databaseapi.
If the initialization fails, the phone is still functional. However, calls are not logged until the initialization succeeds.
If an application attempts to access a database after initialization fails, the API returns the error VOIP_E_NODB.
Databases are Associated with Phone URI
The databases are associated with the phone URI. In the default implementation, if a phone is provisioned with one URI and reprovisioned with another URI, the database used changes. Therefore, if the user has a dataset stored in a database using one URI, and the URI changes, the data in the database appears to be missing.
Note
Important. The VoIP Phone Suite uses just one shared name rather than the phone URI. If the registry is pre-populated with the desired URI, the default name would be overwritten as explained earlier. You are therefore free to make use of this functionality, creating multiple databases per user, if you so choose. You will need to ensure that the registry values are being set ahead of time so that the right names are being used in database creation.
Saving the Log Information
After a call is terminated, you need to log the call to the appropriate database and commit the changes. See IVoIPCallRecord::Commit and IVoIPCallerInfoRecord::Commit. If this database does not exist, logging does not take place but the phone is still functional.
For detailed information on the VAIL Database Store, its database interfaces, their methods, enumerations, constants and possible return values, please see the VAIL Database Store Reference.