on this topic to the authors
Technical Articles
by Intrinsyc Europe Limited
Updated July 2004
Applies to:
Windows Mobile Version 5.0
This paper presents a comprehensive review of the Windows Mobile Radio Interface Layer, RIL, including the following topics
Overview of a RIL development project
Best practices during development and testing
Typical platform implementation modifications
New features included in Windows Mobile 5.0
Throughout the paper emphasis is placed on providing examples of typical changes required when you port a sample RIL to a new platform.
This paper is aimed at project managers responsible for RIL projects and engineers responsible for porting a RIL to a new system. The information presented is based on experiences gained by porting the RIL to a variety of platforms and modems.
This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.
IntroductionRIL OverviewRIL Modem InterfaceDevelopment EnvironmentPlatform ImplementationTestingNew Features in Windows Mobile 5.0SummaryFor More Information
Introduction
The Radio Interface Layer (RIL) provides a key component of the underlying technology that is critical for enabling wireless voice or data applications that use Windows Mobile software to communicate seamlessly with a GSM/GPRS or CDMA2000 1X modem.
The RIL interfaces between the CellCore layer in Windows Mobile and the radio protocol stack within the wireless baseband system, or modem. The RIL abstracts the details of the hardware dependent components of a Windows Mobile-based device. This allows OEMs to integrate a variety of modems into their equipment, and thereby offer an opportunity for product differentiation.
The Windows Mobile 5.0 Adaptation Kit supplied to OEMs contains a sample RIL device driver developed for specific devices from Siemens, TI, and TTPCOM. However, there are a variety of modems available to the designer with new devices coming to market almost continuously. All modems generally conform to internationally recognized standards with regard to items like feature set and interface. Therefore, it is possible to include a generic sample RIL driver that can be used as the starting point for a RIL porting project.
The RIL, regardless of modem specific implementation details, must also conform to the interfaces provided and supported by the upper layers, for example: TAPI, SIM API, Short Message Service (SMS) API. Conformance to the general CellCore environment allows the sample RIL to include the required architecture. For example, the sample RIL can include command queue buffering, call back mechanisms, URC notifications, as well as other required architecture features to reduce the complexity of the project.
The sample RIL also includes code to support all the telephony features supported by Windows Mobile. These include: voice calls, data connections (circuit switched, CSD, and packet switched, for example, GPRS), SMS messages, network features (call forwarding, call barring, voice mail), SIM ToolKit, and more. These features are supported in a variety of upper layer user interfaces, for example in the Dialer, SMS Manager, as well as others.
A RIL porting project is concerned not with the general implementation of these many features, but with the specific differences between the hardware implementation on the target platform and the reference platform for which the sample Windows Mobile RIL was originally developed.
The following table shows the phases into which a RIL porting project is usually divided with associated estimated timescales.
PhaseTime in weeks
Modem specific changes
2 – 6 man weeks
Platform specific changes
2 – 8 man weeks
Test and debug
4 – 6 man weeks
Operator approvals
4 – 8 weeks elapsed time
LTK submission
4 weeks elapsed time
The extent of the modem-specific changes is dependent upon the differences between the selected modem and the reference modem supported by the sample RIL. This can vary considerably with a corresponding impact on timescales. Examples are provided in the Platform Implementation section of this document.
Platform support -- implementation details and testing, debugging, integration on the platform -- often presents the most challenging aspect of the project, especially if the platform is still under development during RIL integration.
Generally, a RIL port requires one engineer for development with a second engineer to test and assist with debugging and LTK submission. For radio modems, the basic AT command set has evolved and expanded over many years to support new network features that were not originally available. These result in a complex, feature-rich recipe from which the RIL developer selects the most applicable ingredients. It is advisable for the RIL development engineer to have access to a technical contact at the modem vendor throughout the course of the project as the development process can be somewhat iterative in nature.
A Windows Mobile-based device is required to pass the Logo Test Kit (LTK) program before the product can be shipped. The LTK subjects the device to a range of telephony tests that cover all telephony features expected to be supported by the device. It is unusual to pass 100% of the tests without some modification to the RIL, and in some cases the modem feature set may not support all test cases. This leads to the granting of a waiver for the product. The LTK requires resources to be available to perform the tests prior to submission, RIL modifications, and liaising with both Microsoft and the NSTL Lab conducting the approval process. The LTK process is covered in more detail later in this paper.
Operator approvals are usually required to be undertaken by the OEM. The timescales for operator approvals can differ considerably and depend on whether the end product is a handset (many months) or a vertical market device, for example a rugged PDA-like device with an embedded modem. It is common for vertical market devices to be approved on 2 or 3 networks that will be used by the OEMs initial customers. Whereas handsets need to be approved on a variety of networks.
RIL Overview
The RIL provides the interface between the system software and the radio stack that reside within the modem. The system software includes all elements of the Operating System, Windows Mobile. These elements include but are not limited to: TAPI or ExTAPI, SIM Manager, SMS Manager, Dialler, and customer or 3rd party applications.
The RIL services system requests radio functions, including voice, data, and SMS, and provides asynchronous notifications of changes to the system, including signal strength, coverage, incoming voice calls, and incoming SMS messages.
Telephony services within Windows Mobile are defined by the Operating System, each function or service is ideally independent of both the modem and the modem and applications processor interface.
The RIL is designed and built so that Windows Mobile provides a standard interface, API set, and set of call back mechanisms that can be used across different platforms, with the specific details hidden from the remainder of the system.
The overall architecture is presented in Figure 1, Telephony Architecture.
As this diagram shows. all of the interaction between Windows Mobile and the radio stack is through the RIL with the exception of a Point-to-Point Protocol (PPP) connection, that initially uses the RIL to set up the connection and then bypasses the RIL path to allow direct connection to the virtual serial port that is connected to the modem.
The RIL is split into two separate components, a RIL driver that processes AT commands and events, and a RIL proxy that performs arbitration between the multiple clients for access to the single RIL driver. This is shown in Figure 2, RIL Proxy Interface.A separate instance of the RIL proxy is loaded by each RIL client and provides a unique handle to each client. The handle is used to ensure that the RIL invokes the appropriate clients call back mechanism. The RIL proxy does not need modification by the OEM and therefore will not be discussed further in this document.
RIL Modem Interface
The RIL allows hardware abstraction by accepting service requests from the upper layers, mainly from TAPI and ExTAPI, and converts those requests into commands that are supported by the modem, and commands that exchange information over a modem and host processor interface.
The original modem system design dates back over 3 decades and provided a single communications channel over which both AT commands and data were routed. This requires a time consuming switching mechanism between command mode and data mode, and essentially allows only single processes to be active at any time. Advances in networks,for example 2.5G and 3G, now provide multiple simultaneous services, for example data connection to browse the Web, send and receive email, send and receive SMS messages, originate and answer voice calls, poll signal strength, and more. Network advances have outstripped modem interface advances to such a degree that it is necessary to expend effort to maximize throughput by providing support for a multiplexer device driver and multiplexer support in the RIL itself.
Network advances have necessitated modem architecture evolution so that it is usually necessary to expend effort on the modem interface
Some modems provide other interfaces, for example high speed UARTs, USB, and shared memory. The same principles apply to high speed UARTs and USB ports. Access to the modem is still through a standard device driver, serial or USB, with no specific RIL or MUX related functions. A shared memory implementation requires considerable changes to the RIL and is outside the scope of this document.
The simplest interface methods are those that employ a UART or UARTs as depicted in Figure 3, Virtual Serial Port Configurations.
One UART, One COM
This configuration is the simplest configuration that utilizes a single UART, and results in lowest cost and smallest real estate, and is connected to a single UART in the modem. This configuration is no longer supported as it imposes throughput constraints on 2.5G and 3G systems because the modem must be periodically switched between data and command mode.
One UART, Two COM
This configuration utilizes a single UART addressable through two logical and virtual serial ports. This requires support for a multiplexer in both the host system and in the modem itself. The GSM standards define a multiplexer specification that, if adhered to by modem vendors, results in a portable multiplexer device driver. However, this is not always the case and it may be necessary to match the multiplexer capabilities and operation with those supported by the selected modem. Some modems comply fully with the GSM standard, some implement a subset of the GSM standard and some implement proprietary solutions. The effort required to provide a fully functional system with acceptable performance and feature set increases as the modem implementation departs further from the full GSM specification. The development time for MUX support should not be underestimated.
Two UART, Two COM
This configuration provides maximum performance because the potential bottleneck presented by the multiplexer is minimized. In practice, the multiplexer bottleneck is not an issue when this configuration is used on GPRS networks where the maximum throughput rarely exceeds 50 kbps. However, higher speed networks like CDMA, EDGE, and W-CDMA are performance-limited by the multiplexer and care must be taken to ensure that the product performance targets can be achieved by the selected implementation.
Figure 4, RIL and Modem Interface shows the lowest level details of how the RIL communicates with the modem.
This diagram shows that the RIL does not communicate directly with the modem. The final link to the modem is usually the standard serial driver provided by the OEMs platform. The key to flexibility and the reduction of the complexity within the RIL is to migrate the port handling to the MUX driver. This approach is appropriate for both single and dual UART implementations. The RIL should acquire the virtual COM port assignments (VCP) from a registry entry that allows portability between platforms. A link between the RIL and the MUX, for example, a set of IOCTLs, should be implemented to allow the RIL to signal port switching. This approach allows the RIL to continue to use the same VCPs when it sends and receives data independent of the physical ports used on the modem for AT commands or data. Port switching is still required although it appears that RIL and PPP use a constant VCP. This is due to the following architectural issues with the modem.
For example, the modem can be configured for data on port 1, and AT commands on port 2. Once a modem port has been configured for data it may not be used for commands. However, for a data connection to be established on a modem port, that port must be configured by using AT commands, therefore, the original AT command port is no longer available for commands that require the use of a second port for commands. This situation arises regardless of which port is initially configured for AT commands.
A more subtle issue can arise with the Unsolicited Response Codes (URCs ) associated with incoming SMS messages. Some modems insist on associating a single port for both SMS configuration, +CSMS used to select phase 2 or phase 2+ SMS support, and SMS URCs. This is not an issue until port switching described earlier is invoked to set up a data call. At this time, the AT command port, also used for URCs, has changed. However this is a different port than the one used to set up SMSs. This leads to a port mismatch that results in loss of incoming SMS notifications. The solution to this is to reaffirm the SMS configuration on the newly assigned AT command port. This modification must be applied to the RIL to ensure that the SIM card does not fill up with unread SMS messages. It is only the SMS notification that is an issue, not the ability of the modem to receive SMS messages.
The preceding issues are dependant on the specific implementation details of each modem. Care must be taken to architect the system and the port usage for the particular modem selected.
In summary, the implementations described here require suitable support in the RIL to match the modem interface details, the modem port and function assignment, and the multiplexer that must be considered as part of the RIL integration project with its associated time and effort implications.
Development Environment
The development environment is key to ensuring a timely delivery of a quality product, this is particularly important for radio and RIL projects. Typically, the platform is not yet designed and debugged when software resources are available to develop the RIL. Since this leads to a serial development program the project timescale is extended, increasing time to market that imposes a limiting factor on the success of the product. Fortunately this situation can be avoided.
The Windows Mobile development environment includes an emulator that allows a Windows Mobile-based image to be built for execution on a standard PC. Developers can include their own drivers and modules into the system image and run under emulation on the PC. The emulator allows access to the standard interfaces supported by the PC, for example keyboard, serial ports, and more. Most modem vendors provide a modem development board which consists of a modem, SIM card interface (GSM), antenna and serial port(s). Connecting the modem development board to the PC emulator by using a standard serial interface presents the developer with a working system in the absence of the target platform, and this allows the majority of RIL development to be undertaken early in the product development project. Indeed, this is the method used by modem vendors who wish to develop a generic RIL for their particular modem and have a competitive advantage in that their customers are provided with a working base platform.
This approach allows the developer to create and debug a RIL that supports the standard features required by Windows Mobile-based devices, for example voice calls, SMS (GSM), data connections, and more. The emulator environment can also be used for testing and even running the LTK tests. See the Testing section for further details. This environment should be used as the standard development environment, however, it cannot support platform specific features nor can it highlight issues with the platform design, this can only be undertaken when the target platform is available. However, the advantages of adopting this approach are not to be underestimated.
When porting the RIL from the emulator environment to the target platform it is good practice to use build directives within the source code for platform specific features. This has two advantages, firstly, it is a simple build process to revert to the emulator version to verify if faults uncovered are due to the platform implementation or are a problem with the generic implementation, and secondly, a common code base can be used to support different product family variations, greatly reducing multi-product development timescales.
Build Environment
When developing the RIL driver it is useful to setup the build environment to build the RIL separately to the main platform build, this considerably improves the speed of development, because the developer only needs to build a single driver. This also eliminates the need to have the real platform source code available as the RIL can be built under the emulator or Hornet reference platforms.
The first step in creating this build environment is to create a desktop shortcut that uses the bldplat batch file to create a build command prompt window, for example, D:/Pak/PGrine/bldplat.bat -w -cpu ARMV4 -p HORNET -sku GSM -retail.
A retail build window can be used as the RIL debug output is actually controlled by the registry and the WINCESHIP build flag.
The shortcut can then be run to open up the build window with all the relevant platform settings.
Assuming that the full platform image has previously been built the developer can then simply set the current directory to the RIL driver source code directory and type Build –cf to build the RIL driver.
The driver DLL produced can then be copied from the release directory to either a device or into the release directory of the main platform build for inclusion into the OS image.
Usually the build environment is set up with the WINCESHIP environment variable set that limits the RIL debug output to include only the AT commands and responses. When debugging, the developer can clear this flag and set the required debug output level in the target registry.
The following example debug trace shows the lowest level of debug output selected when WINCESHIP is set.
RilDrv: Sending cmd: ATE0V0&cr&
RilDrv: Accumulated response: 0&cr&
RilDrv: Sending cmd: ATE0V0Q0X4&C1&W&cr&
RilDrv: Accumulated response: 0&cr&
RilDrv: Sending cmd: AT+CFUN=1;+CMEE=1;+CRC=1;+CREG=1;+CGREG=1;+FCLASS=0;+CLIP=1;+CSCS="GSM"&cr&
RilDrv: Accumulated response: 0&cr&
RilDrv: Sending cmd: AT+CMGF=0&cr&
RilDrv: Accumulated response: 0&cr&
RilDrv: Sending cmd: AT+CPIN?&cr&
RilDrv: Accumulated response: +CPIN: READY&cr&&lf&
RilDrv: Accumulated response: +CPIN: READY&cr&&lf&0&cr&
RilDrv: Sending cmd: AT+COPS=0&cr&
RilDrv: Accumulated response: 0&cr&
Clearing WINCESHIP selects a higher debug output level that shows the API calls and internal RIL operation.
Debug Environment
There are usually several stages of debugging when developing a RIL driver dependent upon the stage of the product, namely:
Emulator or reference platform
Prototype device
Production device
Approvals/Logo testing
As the product matures debugging can become a problem because the production device may not have the components required to easily facilitate debugging. Therefore, as with most other software development, the majority of debugging needs to be undertaken on reference or prototype devices.
Emulator or Reference Platform
Before target hardware becomes available it is useful to use the Microsoft emulator and/or a reference platform together with the relevant modem to start development of the RIL driver.
The reference platform will usually have an Ethernet debug connection and possibly hardware debug tools. These will allow easy download and single stepping of code on the target device.
The emulator provides the simplest debug mechanism because both the platform code and target device exist on the developers machine and allow drivers and applications to be quickly updated and debugged.
At this stage in development it is usual to debug the AT command strings and their responses.
Prototype Device
The prototype device will be similar to a reference platform in that it should provide an Ethernet debug interface, or one similar, to facilitate debugging of the platform software.
This type of device will allow the developer to work on the hardware and platform specific features, for example modem power control, modem interfacing, and more.
Production Device
The production device is the final stage in the development process and is unlikely to contain the same debugging facilities as the prototype device.
Therefore it is sometimes useful to redirect the RIL debug output to a file on either the device itself or on the developers PC via ActiveSync if no other form of debug connection is available.
The debug statements in the RIL source code are macros, hence it is simple to redirect the output strings to a file instead of the normal output routines.
Approvals and Logo Testing
Approvals and/or Logo testing usually occur after the main development process is completed and is performed on a full production device. Although a full debug interface may not be required at this stage some form of error reporting is usually required, hence, redirecting the RIL output to a file over an ActiveSync connection can be useful.
Enabling some form of debug output on a device can have effects on performance which in turn can affect the overall performance of the device during testing, therefore if debug output is required it is usually best to have a fast debug connection utilizing Ethernet or USB.
The ActiveSync connection can be a good way of sending debug information to the host PC without including an additional hardware interface specifically for debug output.
Platform Implementation
The RIL source code is usually based on the sample RIL provided by Microsoft in the adaptation kit under &platform root folder&/public/cellcore/ril/driver, which provides all the mechanisms required to support a standard AT command based modem. For a non-AT command based modem it may be more efficient to redesign the RIL.
The sample RIL provides support for Siemens, TI, and TTPCom based modems, hence modifications will be required to adapt the RIL to the selected modem if not based on one of the above.
Although most modems conform to the GSM or CDMA specifications most manufacturers implement these specifications in similar but not identical ways, hence, although the AT commands may be the same, the actual behavior of the commands may differ. For example AT+COPS=0 on some modems block until the modem has registered (or failed to register) on the network, whereas other modems respond immediately and register in the background.
The Logo Test Kit assumes a particular modem behavior, hence, some modems will require RIL modifications to match the expected behavior.
The most common areas that require modification for each modem and/or platform are:
Power Management
Audio Management
SMS handling
SIM toolkit
Own number
Power Management
The power management of the radio is a combination of modem specific and platform specific methods, for example the modem may support power saving modes by using AT commands and/or the platform may provide hardware power control to the modem. These two methods each have their own issues that need to be addressed in the RIL driver.
The AT command options associated with power management are already handled by the sample RIL to some extent in the SetEquipmentState RIL API functions, usually by using the AT+CFUN command. Any proprietary AT commands, or extensions, can also be handled within these functions to provide low power operation.
If any of the low power AT commands stop the AT command parser in the modem, then a mechanism for reawakening the modem will need to be implemented and the RIL may also need to be reinitialized if any of the modem settings are lost.
The hardware power control is a little more complicated as both the RIL and radio will need to be reinitialized when the power to the radio is cycled.
It is necessary to ensure that the OS does not attempt to access the modem while it is powered off and also forces CellCore components, for example SIM manager, to reinitialize when power is reapplied to the modem. When power is required to be physically removed from the modem, on calling SetEquipmentState with the RIL_EQSTATE_MINIMUM power state set, the following sample code needs to be executed after the modem has been powered down.
res.dwReadyState = 0;
g_dwGPRSRegStatus = RIL_REGSTAT_UNREGISTERED;
g_dwRegStatus = RIL_REGSTAT_UNREGISTERED;
pnd = new CNotificationD
if (!pnd-&InitFromRealBlob(RIL_NOTIFY_REGSTATUSCHANGED, &g_dwRegStatus, sizeof(DWORD)))
pnd = NULL;
pHandle-&GetDevice()-&BroadcastNotification(pnd);
// Notify the OS of the change in radio power state.
pHandle-&GetDevice()-&BroadcastRealBlobNotification(RIL_NOTIFY_RADIOEQUIPMENTSTATECHANGED, (void*)&res, res.cbSize);
Sleep(200);
// Signal that RIL is no longer ready.
pHandle-&GetDevice()-&StopReadyStateQuery();
pHandle-&GetDevice()-&SendReadyStateNotification(RIL_READYSTATE_NONE, TRUE);
UpdateSIMState(RIL_E_RADIOOFF);
When reapplying power to the modem by requesting the RIL_EQSTATE_FULL state the first AT command sent to the modem should have the CMDOPT_REINIT flag set to force the RIL to reinitialize both the modem and itself.
The RIL driver could also be made to be a power managed driver by adding the .NET power management IOCTLs as would be done for a standard stream device driver. This will allow the radio to be easily powered off and on (or put into a low power mode) during suspend and resume respectively, as well as integrating with the standard power management support in the OS. The power management IOCTLs could either put the modem into a low power mode using AT commands or switch off the power to the modem as described above.
The following sample code shows the power management IOCTLs that need to be added to the RIL driver to make it a power managed device:
BOOL RIL_IOControl(DWORD dwOpenData, DWORD dwCode, PBYTE pBufIn, DWORD dwLenIn, PBYTE pBufOut, DWORD dwLenOut, PDWORD pdwActualOut)
// Handle the power management IOCTLs.
case IOCTL_POWER_CAPABILITIES:
TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_CAPABILITIES"));
// Copy the supported power modes to the output buffer.
memcpy(pBufOut,
pHandle-&GetDevice()-&GetPwrCapabilies(), sizeof(POWER_CAPABILITIES) );
dwOutUsed = sizeof(POWER_CAPABILITIES);
fRet = TRUE;
case IOCTL_POWER_SET:
DWORD dwPwrS
dwPwrState = *(DWORD *)pBufIn;
TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_SET (0x%X)"), dwPwrState);
// Set the requested power mode.
pHandle-&GetDevice()-&SetCurrentPwrState(dwPwrState);
fRet = TRUE;
case IOCTL_POWER_QUERY:
TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_QUERY"));
fRet = TRUE;
case IOCTL_POWER_GET:
TBD_OUTPUT(TBDCT_INFO, TBDOL_INFORMATION, TEXT("RIL_IoControl: IOCTL_POWER_GET"));
// Get the current power mode.
*(DWORD *)pBufIn = pHandle-&GetDevice()-&GetCurrentPwrState();
dwOutUsed = sizeof(DWORD);
fRet = TRUE;
The actions performed by these power management functions are implementation specific and would either send a power saving AT command or switch the power to the modem on or off depending on the power mode requested.
Audio Management
The RIL is responsible for adjusting the volume of the voice signals from the modem and selecting which audio device is currently in use. This is normally undertaken using AT commands to adjust the modem settings, however, some platforms may have external audio hardware to make these changes and in these cases the RIL will need to either access the hardware directly or, preferably, to access another device driver.
The following APIs show the audio support functions within the RIL.
FunctionDescription
HRESULT RILDrv_GetAudioGain(DWORD dwParam)
Retrieves the current incoming and outgoing voice level settings.
HRESULT RILDrv_SetAudioGain(DWORD dwParam, const RILGAININFO* lpGainInfo);
Sets the volume of both the incoming and outgoing voice levels.
HRESULT RILDrv_SetAudioDevices(DWORD dwParam, const RILAUDIODEVICEINFO* lpAudioDeviceInfo);
Selects the type of audio device currently in use (either. Handset, Headset, Speakerphone, or Carkit)
HRESULT RILDrv_GetAudioMuting(DWORD dwParam);
Retrieves the current muting settings.
HRESULT RILDrv_SetAudioMuting(DWORD dwParam, BOOL fEnable);
Enables or disables the muting of the outgoing voice signal.
The OS will normally call the gain setting functions when the user adjusts the volume slider during a voice call, but they will also be called when the current audio device is changed as each device requires a different relative volume.
The audio device is normally selected via the profiles subsystem as there is a different profile for each audio device and a particular profile is selected when its device is either inserted or selected.
The profiles subsystem is included by default in the Windows Mobile-based Smartphone version of the OS, however, when developing for Windows Mobile-based Pocket PC the OEM either has to implement the audio profiles or an alternative method can be devised.
One way of implementing this is to create an audio device manager that monitors the state of each audio device and calls the RIL to change settings when either the device is inserted or the user selects a different audio device via a control panel.
SMS handling
The sample RIL supports GSM SMS phase 2 mode 2, however, if this is not supported by the modem then the handling of SMS messages requires modification. For example, to support SMS phase 2+ additional code with the RIL is required to send the SMS acknowledge AT command (+CNMA) after each incoming SMS notification.
SIM toolkit
The SIM toolkit support in the sample RIL is designed around the Condat and TTPCom AT command set. Many modem manufacturers implement their own proprietary AT command extensions for SIM toolkit commands, hence, some work may be required to convert the radio command to what the OS is expecting. This can be quite complex if the modem implements vastly different SIM toolkit functionality as considerable changes to the parsing of the commands will need to be added within the RIL.
The standard SIM toolkit functions implemented in the RIL are:
HRESULT RILDrv_GetSimToolkitProfile(DWORD dwParam);
HRESULT RILDrv_SetSimToolkitProfile(DWORD dwParam, const BYTE* lpbProfile, DWORD dwSize);
HRESULT RILDrv_SendSimToolkitCmdResponse(DWORD dwParam, const RILSIMTOOLKITRSP* pRsp, LPBYTE pDetails, const DWORD dwDetailSize);
HRESULT RILDrv_TerminateSimToolkitSession(DWORD dwParam, DWORD dwCause);
HRESULT RILDrv_SendSimToolkitEventDownload(DWORD dwParam, const DWORD dwEvent, LPBYTE pData, const DWORD dwDataSize);
The RIL is required to pass the following notifications to the OS to inform it of various events, the OS will then call the preceding APIs to perform the required actions:
NotificationDescription
RIL_NOTIFY_SIMTOOLKITCMD
Indicates that a SAT command is waiting to be executed.
RIL_NOTIFY_SIMTOOLKITSESSIONEND
Indicates that the current SAT session has been terminated.
RIL_NOTIFY_SIMTOOLKITCALLSETUP
Indicates that the SIM application wants to make a call.
If the SIMUI component detects any user interaction with the user interface, for example select a menu option, this is transmitted to the SIM application by means of the RILDrv_SendSimToolkitCmdResponse API.
The SIMUI can also terminate the current SAT session by calling the RILDrv_TerminateSimToolkitSession API.
The SIMUI will also transmit Event Download events by calling the RILDrv_SendSimToolkitEventDownload API.
Usually the modem uses an unsolicited notification of some form to indicate to the RIL that a SAT command is waiting. If this is not the case then the OS can be configured to poll for SAT commands by setting the appropriate option in the RIL_CAPSTYPE_SIMTOOLKITNOTIFICATIONS of the RILDrv_GetDevCaps API. If polling for SAT commands is needed, support for the RIL_FetchSimToolkitCmd API will also need to be implemented within the RIL. The RILDrv_GetDevCaps. The RILDrv_GetDevCaps structure is also used to determine which SAT commands are to be executed by the OS and which will be executed by the radio.
Own Number
Many modems do not implement the +CNUM AT command. When the +CNUM AT command is not implemented, it can cause problems when the OS attempts to fetch the modems own phone number. This is because the phone application in Control Panel will display unavailable. To avoid this, the RIL can be modified to obtain the own number from the SIM phonebook by selecting the own number phonebook, however, this is SIM/Network operator dependent, hence, some SIM cards may not include any entries in this phonebook.
The following simple example shows how to fetch the own number without using +CNUM:
DWORD CRilHandle::FetchOwnNumber()
APIINFO apiiI
CCommand* pC
char szCmd[MAX_PATH];
// Clear the global list of subscriber numbers
memset((void*)&g_rsi[0], 0x00, sizeof(RILSUBSCRIBERINFO));
// Get the information about this API.
apiid = APIID_OWNNUMBER;
memset(&apiiInfo,0,sizeof(apiiInfo));
GetAPIInfo(apiid, apiiInfo);
// Select the own number phonebook.
pCmd = new CC
if (!pCmd || !pCmd-&Init(NULL, "AT+CPBS=/"ON/"/r", NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, NULL, 0, 0, 0, apiid))
TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
g_pCmdQ-&Put(pCmd, INFINITE);
// Check if there are any phonebook entries.
pCmd = new CC
if (!pCmd || !pCmd-&Init(NULL, "AT+CPBR=?/r", NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, ParseGetNumPBEntries, 0, 0, 0, apiid))
TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
g_pCmdQ-&Put(pCmd, INFINITE);
// Wait for command to complete.
if(WAIT_OBJECT_0==WaitForSingleObject(g_hCPBREvent, 2000))
// Read the list of numbers.
(void)_snprintfz(szCmd, MAX_PATH, "AT+CPBR=1,%d/r", g_iNumPBEntries);
pCmd = new CC
if (!pCmd || !pCmd-&Init(NULL, szCmd, NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, ParseGetOwnPBEntries, 0, 0, 0, apiid))
TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
g_pCmdQ-&Put(pCmd, INFINITE);
pCmd = new CC
// Reset to using normal SIM phonebook.
if (!pCmd || !pCmd-&Init(NULL, "AT+CPBS=/"SM/"/r", NULL, CMDOPT_NONE, apiiInfo.dwExecTime, apiiInfo.dwTimeout, NULL, NULL, 0, 0, 0, apiid))
TBD_OUTPUT(TBDCT_INFO, TBDOL_ERROR, (TEXT("FetchOwnNumber : Unable to construct or Init CCommand")));
g_pCmdQ-&Put(pCmd, INFINITE);
Additional modifications
In addition to adapting the RIL driver to the modem, the following additional modifications can be made to enhance the platform or radio functionality.
Hardware abstraction layer
One useful change to the RIL is to add another software layer below the RIL to handle all hardware specific functionality, this can be important where the source code to the RIL cannot be shipped but the customer requires some level of platform dependent modification.
This extra layer would be in the form of a standard DLL which the RIL can load using LoadLibrary and would provide an API for accessing the radio hardware.
The main functionality included in this layer would be
Radio power control
Audio routing
Audio codec control
A simple example API could look something like this
BOOL HAL_SwitchRadioPower(BOOL fRadioPower);
BOOL HAL_IsRadioPowerOn(void);
BOOL HAL_SetAudioPath(DWORD dwTxAudioMode, DWORD dwRxAudioMode);
BOOL HAL_SetTxAudioVolume(DWORD dwAudioMode, DWORD dwVolume);
BOOL HAL_SetRxAudioVolume(DWORD dwAudioMode, DWORD dwVolume);
The RIL would call these APIs at the appropriate point within the standard RIL APIs.
GSM 27.10 Multiplexer
The GSM 27.10 multiplexer is a useful extension to the standard modem interface as it can provide multiple concurrent channels to the modem allowing the RIL to perform several functions simultaneously.
The main advantage of the multiplexer is that it allows AT commands to be sent to the modem without interrupting the data stream during an active data connection. This simplifies the handling of voice calls and SMS during a data connection.
The multiplexer essentially emulates a dual serial port modem as it provides several virtual modem/COM port interfaces to the upper layers whilst using a single physical serial interface.
The multiplexer is usually implemented as standard stream device driver and is similar to a serial driver and the RIL and TCP/IP stack each open their own instance of the virtual COM port interface.
Additional interfaces can be opened for specific purposes, for example, unsolicited notifications.
As the multiplexer presents a standard COM port interface there is little additional modification required to the RIL to support the multiplexer.
If any additional functionality is required from the multiplexer then the standard IOCTL interface can be used to perform the required operation.
For example, the following IOCTLs would normally be implemented to control the multiplexer.
IOCTL_MUX_ENABLE - Enable the multiplexer in the modem and establish the channels
IOCTL_MUX_DISABLE - Free the channels and disable the multiplexer in the modem
The individual channels would normally be configured when opening the associated virtual COM port with one DLCI being allocated to each port. These channels would then be established by the enable IOCTL described above which, in turn, would be called by the RIL after initialization.
Additional IOCTLs could be added to dynamically establish additional data link connection identifiers (DLCIs) if required.
RIL Extensions
The standard RIL API can be extended using the RIL_DevSpecific API.
A pointer to a parameter block is passed to this function. The first DWORD in this block is used as a function ID to call a specific function. The remainder of the parameter block is passed to that function as its parameters.
An example parameter block could look something like this:
typedef struct tagRILDevSpecificParams {
DWORD dwFunctionID;
BYTE *lpInputP
BYTE *lpOutputP
} RIL_DEVSPECIFIC_PARAMS;
The two-byte pointers would point to a buffer of parameters to be passed to the given function in a similar way to the standard IOCTL interface.
These additional RIL functions can implement proprietary AT commands for specific OEM radio applications.
A wrapper DLL can also be created to present a simpler API to the application layer, this DLL would contain all the RIL calls required to access the RIL APIs thus removing this burden from applications and also hiding the RIL API from the upper layers.
The wrapper DLL could provide a TAPI like API in the form of lineXXXXXXX style functions.
A popular RIL extension for many modem manufacturers is to provide a generic AT command function that allows any AT command to be sent from an application directly to the modem. This type of extension is normally only used for GSM approvals and modem testing and would not normally be allowed in normal operation as this type of function could adversely affect the CellCore stack.
Version control
Another useful addition to the RIL is to add a version resource to the build, this allows the version number to be easily viewed from Windows Explorer and can be accessed by other applications. This resource can also be linked to the standard RIL version IOCTL to maintain compatibility with the existing version control. The version number can then be read and displayed by a Control Panel Applet (CPL).
This technique can also be applied to all the other DLLs associated with the RIL, the RIL will then be able to check the version numbers of the extension DLLs to ensure the correct version is installed.
RIL testing is split into the following main sections
Standard development testing
Operator testing
Logo Test Kit (LTK) testing
Radio quality metric testing
Standard development testing
This requires test procedures and test suites to be developed in the same way as any development project with the tests and test environments being designed to match the specific project. RIL projects generally require the following test environments to be applied as early as possible during the development process.
Test Procedures
Although Microsoft provides a test environment it is good practice to create a project specific test procedure. Experience has shown that creating an extensive test procedure results in a smoother passage through LTK testing in that all basic issues and most combinatorial test issues have already been resolved prior to running the LTK.
It is imperative that a comprehensive test procedure be created to ensure that all boundary conditions and combinatorial conditions are correctly handled. The asynchronous nature of wireless networks requires consideration to be given to unpredictable events or sequences of events. Such examples include:
Incoming voice call,SMS, and voice mail notifications during other activities, for example, actively downloading data during a GPRS connection.
Out of coverage during a data call.
No SIM card present.
Unit power down during voice or data calls.
The general robustness of the system needs to be qualified with repeated tests. It is necessary to perform repeated tests to ensure good testing practices are adhered to, however, wireless networks are not static and not totally predicable, some failures to connect, dropped calls, etc. are to be expected. Although these issues should be minimal, it should be realized they do exist and care should be taken when interpreting the results to ensure network issues are not mistaken for platform implementation problems.
Examples of repetitive tests include:
Originate 50 voice calls in succession.
Send 50 SMS / MMS (where MMS is supported) messages in succession and check all 50 have been received at the target number.
Receive 50 SMS / MMS messages ensuring all are received correctly and SIM card overflow does not occur.
Web page browsing with automatic refresh enabled and active for 10 hours.
Receive 50 SMS / MMS messages during an active data connection.
The emulator coupled to a modem development station provides an ideal initial test environment ahead of the platform itself being available. The emulator can be used for most testing aspects, for example, voice, data, SMS, live networks, test networks, and LTK. The availability of this test environment should be maximized during the development phase.
Modem vendors usually use the emulator as their test environment when subjecting the device to the LTK radio tests. However, OEMs with specific platforms into which the modem is embedded must fully test on the platform both during in-house proving and formal LTK submission. See sub-topic, "Platform Specific".
Platform Specific
It is unlikely that some platform-specific features can be tested on the emulator, for example audio profiling external to the modem, audio path routing, power management, and others.
It is imperative to test on the target platform as soon as possible to ensure not only that platform-specific features are working correctly but also to ensure the overall system performance is acceptable.
The system performance aspects include:
RF Performance
RF performance is key to any wireless product. A poorly designed RF implementation can result in degraded system performance with loss of service under low signal strength conditions. The emulator system usually has a modem development station in its own enclosure and use of an external antenna that masks RF issues. The emulator provides a useful reference system against which the target platform can be measured to help identify if the problem lies with the platform or the generic RIL implementation.
The emulator environment is mains-powered, which masks any potential issues associated with supply voltage, power supply noise, and voltage reservoir effects. It is necessary to test the target platform on battery power and wall charger and external supply.
Operator Testing
Although internationally agreed specifications exist for both GSM / GPRS and CDMA networks many development and deployment issues are associated with differences between networks. It is not uncommon to find that some of the supplementary features are supported differently across a range of networks, for example, call forwarding, call baring, conference calling, SMS delivery notifications, etc., and in exceptional circumstances GPRS connection methods can differ, for example, a small number of servers attempt to authenticate the user at the time the AT+CGACT command is sent rather than authenticating at the time of connection.
Testing should be conducted on the network(s) known to be used when the product is deployed. However, it is good practice to repeat the tests on as wide a range of networks as possible depending on network availability. It is common practice to purchase a number of SIM cards for a variety of networks (GSM) or have subscriptions to a number of CDMA carriers to be used exclusively for RIL testing. It is also advisable to use both contract and pre-pay SIM cards. The cost of the live network testing should not be underestimated, it is likely that hundreds of voice calls, data connections and SMS messages will be undertaken over the project lifecycle.
Live network testing is the most representative test environment, however, it is also advisable to make use of test stations during the development. This is mandatory if the modem is not yet certified, although this is rarely the case. The test station should also be used to ensure compliance with Emergency Number support, emergency agencies are not impressed with false calls, and in some countries it is a criminal offence to place a false emergency call. The test station can be used to exercise the system under extreme conditions, for example, receive 1,000 SMS messages, receive 100s of voice calls, receive SMS messages during GPRS connections, and so on. Combining a test station with automated test software on the target platform provides a powerful test environment not achievable on live networks. Test stations are expensive ($10,000s) however, they do represent an invaluable test capability and should be used where possible.
Logo Test Kit (LTK) testing
LTK testing is a key part of the Windows Mobile test environment. A product must be subjected to and pass the LTK before the product can be shipped. Although the LTK is not designed to be a replacement for in-house test procedures it provides an out of the box test suite that can be used to test the RIL immediately.
The LTK for Windows Mobile-based devices includes the Microsoft radio test suite which uses a single test program, Radiotest.exe, and an associated test condition file Radiotest.ini.
The Microsoft radio test suite is intended as a simple mechanism to test basic wireless scenarios, for example:
Packet data throughput and stability
Incoming / outgoing voice call reliability
Supplementary services
SIM management
The radio test suite is fully configurable and permits either a broad coverage test to be run or specific scenarios. The ability to run tests randomly is also included, this is particularly useful for identifying combinatorial issues.
The tests included in Radiotest.exe and a sample test run output are shown in figures 7 and 8. The TARGET value represents the percentage pass rate required to pass a specific test. Networks can cause errors and failures that should not be confused with failures of the equipment under test, hence, the Radiotest.exe accounts for this by allowing typically 5% - 10% failure rates on most tests.
The LTK process includes the following:
In-house execution
The LTK is a useful test tool during development to be used when appropriate. However, the tests must be formally executed and recorded prior to formal NSTL submission, and the appropriate resources and time need to be allocated for this task. Any issues arising should be discussed with Microsoft and need to be either resolved or handled with waivers.
Ideally all devices and systems should pass the full compliment of LTK tests. However, this is not always possible. If a non-compliance occurs, it is necessary to discuss the issue with Microsoft and reach agreement. It is possible that a waiver will be granted for a specific test issue, for example, the modem only supports SMS Phase II+, whereas the LTK specifically tests for SMS Phase II.
Formal Submission
The Microsoft radio test suite is an OEM verify test case whereby each OEM runs the test cases, saves the log, and submits that log to NSTL for final approval. To remain independent and impartial, the NSTL team will not issue accreditation unless all tests are passed or Microsoft has issued waivers for agreed, specific non-compliances.
Details of the NSTL submission requirements and conditions can be found at .
Radio Quality Metric Testing
Microsoft provides another test executable, Radiometrics.exe, that is similar to Radiotest.exe. The Radiometrics.exe test provides additional functionality to derive quality metrics, for example, the missed call rate. Different INI files are used to derive different metrics.
INI FileTest Functionality
call_hold_conf_metric.ini
25 conference calls, 25 calls to a busy number, 25 dial and hang-up and 25 incoming calls.
general_func_metric.ini
One call to each CellCore API, similar to LTK test.
general_stress_metric.ini
24-hour test consisting of random API calls.
gprs_perf_metric.ini
20MB transfer with connect/disconnect every 1MB.
gprs_stability_metric.ini
~=13MB transfer in small blocks with intermittent sleeps, voice calls and connect/disconnect.
Send and receive 100 multipart messages.
supp_service_metric.ini
25 calls to each SS API.
voice_call_metric.ini
1000 outgoing/incoming phone calls.
Microsoft uses the Radiometrics.exe as a mechanism to determine relative quality of specific radio modules and firmware. Upon receipt of a module or build the entire suite detailed above will be run using the network available in Redmond and bugs discovered logged with the vendor.
New Features in Windows Mobile 5.0
The mobile device market is rapidly evolving worldwide with the deployment of new network technologies, new operator services, and new applications. To keep pace with these market forces, Windows Mobile software must adapt and innovate. Windows Mobile 5.0 includes substantial new features some of which directly impact CellCore and RIL drivers.
WWAN NDIS Packet Data Interface
Microsoft Smartphone 2002 products create GPRS and 1x data connections on demand. The connections provide modest data throughput, are required infrequently, and are discarded when idle or when a voice call is active. The dial-up modem model traditionally used with CDMA and GSM radio modules is adequate to support this level of data connectivity.
In Windows Mobile 2003-based Smartphone Microsoft improved the behavior so that GPRS and 1x data calls would not be discarded when the device is idle or during a voice call. This reduced the number of times the user or an application would have to wait for a data connection to be dialed before transferring packets. The dial-up modem model is still used in this release.
Going forward, Windows Mobile software is moving to an always-connected model for GPRS and 1x data connections. The system software will maintain, within certain parameters, that these data connections are constantly connected and available for use by applications. This is closer to the model of a traditional Ethernet or WiFi interface. Additionally, as packet data rates increase, the overhead associated with PPP becomes a factor.
For these reasons Microsoft is adding support for wireless packet data connections to transition to the Network Driver Interface Specification (NDIS).
Microsoft will provide a Wireless Wide Area Network (WWAN) miniport driver implementation suitable for use with cellular radio packet interfaces. The source code will be provided for this component as part of the Adaptation Kit, and it will be modifiable by Adaptation Kit licensees. Modification will not be typically required because all radio specific details of the implementation will be encapsulated in the RIL driver.
One instance of the WWAN miniport driver will be bound to NDISUIO for the purposes of configuration and control of WWAN connections. Other instances of the WWAN miniport will be created for each of the various packet connections exposed by the cellular radio. This will allow the RIL driver to expose multiple IP interfaces simultaneously. Documentation of NDISUIO is readily available in MSDN.
The RIL driver will typically need a new channel to communicate packets to the cellular radio. This channel can take the form of a shared memory buffer, MUX packet channel, or other packet transport means. AT commands are not suitable for the transfer of packets.
WWAN NDIS Buffer Management
In order to ensure high packet throughput, it is important to minimize the number of buffer copies, allocations, and deletes. For this reason Microsoft has carefully designed the interface between the WWAN miniport driver and the RIL driver to allow for buffer reuse, and to eliminate the need to copy packet buffers in memory. RIL drivers should be implemented with the same goal in mind.
When an IP packet is sent from the WWAN miniport driver to the RIL driver, it is passed in to RIL_NDIS_SendPacket as a list of pointers to buffers. The asynchronous completion of this function indicates to the WWAN miniport that the buffers are no longer required, and may be reused or destroyed.
When an IP packet is received from the RIL driver, it is passed up with a RIL_NOTIFY_NDIS_PACKETRECEIVED notification and a corresponding list of pointers to buffers. These buffers must not be modified or destroyed by the RIL driver until the WWAN miniport has indicated that the buffers are no longer needed. This is indicated by using RIL_NDIS_ReceivePacketDone.
WWAN NDIS Flow Control
Flow control will be used to prevent the WWAN miniport from flooding the RIL driver with outbound packets. When the RIL driver hits a high water mark it can prevent further packets from being transmitted via RIL_NOTIFY_NDIS_XFERSTATUSCHANGED RIL_NDIS_XOFF. When some packets have been sent and a low water mark is reached then the RIL driver can request more packets by using RIL_NOTIFY_NDIS_XFERSTATUSCHANGED RIL_NDIS_XON. The high and low water marks will vary for each RIL implementation, and should be tuned to the characteristics of the packet radio network.
WWAN NDIS Multiple APN Support
Microsoft is adding support to Windows Mobile software for multiple data connection scenarios. This will include support for more than one concurrent active GPRS context via the WWAN NDIS packet interface. RIL drivers will report the maximum number of simultaneous active contexts via a capability.
Always On Connection Support
Connection Manager is the component responsible for determining when data connections should be established and torn down. In was originally designed to bring up data connections upon request from an application, and to terminate the connection when the application had completed its transaction.
With operator and end user requirements evolving and the continuing trend to more affordable data plans, it makes sense to move to an always-connected data model. Microsoft is altering Connection Manager to align with this model.
Always On Configuration
Connections are provisioned using XML. To allow configuration of Always On connections, a new parameter is supported for the following connection types:
NDIS based GPRS
PPP based GPRS
PPP based CDMA 1x
Ethernet adapters
WiFi adapters
Desktop pass-through (DTPT)
By default the Windows Mobile connection control panel will configure one Internet GPRS or 1x call as always on, and all Ethernet, WiFi, and DTPT connections as always on.
The following sample XML shows how to configure an Internet GPRS entry as always on using WAP provisioning.
&wap-provisioningdoc&
&characteristic type="CM_GPRSEntries"&
&characteristic type="My Internet GPRS"&
&parm name="DestId" value="{436EF144-B4FB-F905A62C572}" /&
&parm name="AlwaysOn" value=1" /&
&characteristic type="DevSpecificCellular"&
&parm name="BearerInfoValid" value="1" /&
&parm name="GPRSInfoValid" value="1" /&
&parm name="GPRSInfoProtocolType" value="2" /&
&parm name="GPRSInfoL2ProtocolType" value="2" /&
&parm name="GPRSInfoAccessPointName" value="internet.operetor.com" /&
&parm name="GPRSInfoAddress" value="" /&
&parm name="GPRSInfoDataCompression" value="1" /&
&parm name="GPRSInfoHeaderCompression" value="1" /&
&/characteristic&
&/characteristic&
&/characteristic&
&/wap-provisioningdoc&
Always On connection availability
There are circumstances when always on connections will not be available because of the lack of some required resource, or because Connection Manager has determined that it is appropriate to bring the connection down. Some of these circumstances are summarized in the following list:
When the connection requires network coverage and that coverage is lost. For example, when the user turns off the radio by enabling Airplane Mode.
When Connection Manager determines that the always on connection must be brought down to free up the cellular radio for use by another higher priority connection request. For example, an always on GPRS call to the internet may be brought down to allow a circuit-switched RAS call to the work network.
When Connection Manager determines that the always on connection must be brought down for security reasons.
When a remote disconnect occurs due to network error or remote timeout
When a connect attempt fails.
Connection manager will attempt to establish any disconnected always on connections based on events occurring in the system such as the following:
The device boots up.
A network card gets an IP address.
The device registers on a network.
GPRS attaches.
The device is cradled.
Connection configuration for an always-on connection changes.
After a failed connection attempt a timer interval expires causing a retry.
When a connection that was using the cellular radio is disconnected.
Piggyback Connections
Connection manager allows for applications to request to be informed whenever a connection is available. These connections requests are referred to as piggyback connection requests because they cannot cause a connection to be established on their own, instead they must depend on another application to dial the data connection.
The always on feature changes for Connection Manager allow these piggyback requests to be connected whenever an always on connection is available even if no other application is using that connection. This means whenever a network card is available or an always on GPRS connection is established, piggyback requests will be connected.
Multiple Connection Support
Historically Connection Manager has tried to avoid multiple IP interfaces being available at the same time. This was done for security reasons and also to ensure that there is no ambiguity in how packets should be routed.
Connection Manager is being redesigned to support multiple simultaneous data connections. This will allow for multiple APN GPRS support, and for scenarios such as concurrent GPRS and WiFi connections.
To make this work, Microsoft has created a new module AutoBind_LSP.dll.
AutoBind LSP
The AutoBind LSP is a WinSock Layered Service Provider (LSP). When an application makes a Connection Manager connection request, Connection Manager determines which IP interface the application should use to reach the destination network requested. Connection manager passes this information along with the process ID to the AutoBind LSP.
If the application does not explicitly bind its sockets to an interface, then the AutoBind LSP will implicitly bind the sockets to the interface specified by Connection Manager, ensuring that the packets sent over the socket will take the correct route to reach the intended destination.
It is still possible for applications to override this behavior by explicitly binding sockets to the desired interface before connecting. In this way it is possible for a single application to have open sockets on multiple IP interfaces.
Secure Connections
In an environment where there are multiple IP interfaces available simultaneously, there is a possibility that applications or the operating system may route packets between interfaces. If one of the interfaces is behind a firewall or disconnected entirely from the public Internet, bridging packets may introduce a security threat.
In order to mitigate this threat, Connection Manager is adding the concept of secure connections. When Connection Manager needs to connect a secure connection, it first disconnects all other IP interfaces. If other IP interfaces appear during a secure call, then Connection Manager disconnects the new IP interface. If Connection Manager is unable to disconnect an IP interface before or during a secure call, then Connection manager will fail the disconnect and fail the secure call.
The method of disconnection varies by connection type, but includes hanging up RAS calls, deactivating GPRS contexts, and unbinding network interfaces.
Connections can be provisioned through XML to be secure, as shown in the following sample WAP provisioning XML for a VPN connection to work.
&wap-provisioningdoc&
&characteristic type="CM_VPNEntries"&
&characteristic type="VPN to Work"&
&parm name="DestId" value="{18AD9FBD-F716-ACB6-FD8A-}" /&
&parm name="Phone" value="11.22.33.44" /&
&parm name="UserName" value="user" /&
&parm name="Password" value="pass" /&
&parm name="Domain" value="domain" /&
&parm name="DeviceType" value="vpn" /&
&parm name="Type" value="0" /&
&parm name="Secure" value="1" /&
&/characteristic&
&/characteristic&
&/wap-provisioningdoc&
Call Progress Notifications
The ability to notify the upper layer software of changes in call state has been added to Windows Mobile 5.0 through a notification mechanism.
When call progress notifications are available, the CellCore TAPI Service Provider will greatly reduce the amount of polling it does of the RIL driver for call status. The frequency of CLCC and CPAS enquiries is greatly reduced which results in enhanced overall reliability and system performance.
The capability of the RIL to support call progress notifications is tested by the upper layers through a new capabilities RIL_CAPSTYPE_CALLPROGRESSNOTIFICATION that has been added to the RILDrv_GetDevCaps in caps.cpp.
Although it is not mandatory, all parties creating derivative RIL drivers are strongly encouraged to implement this feature.
The sample RIL provides examples for two types of implementation based on different modems.
%CPI Implementation
The first example, for TI based radios, uses the %CPI notification. The CPI notification contains detailed information about the call state and is a superset of information provided in the CLCC response. The sample RIL driver requests that notification is sent using mode 3 of the CPI response that contains the highest level of detail. This is requested at initialization with the AT command string %CPI=3. In this mode the notifications are of the format:
%CPI:&cId&,&msgType&,&ibt&,&tch&,&dir&,[&mode&],[&number&],[&toa&],[&alpha&], [&cause&],&line&
where the parameters are defined as follows.
ParameterDescription
Integer call identification number as described in GSM 02.30
Layer 3 message type
Status of the usage of in-band tones
Traffic channel assignment
Direction of call
Call mode (voice/data/fax/etc.)
Number of connected call
Type of address
Alpha identifier of call if in phonebook
call control cause value (generally used for disconnect codes)
Line 1 or 2
The information is parsed and put into a RILCALLINFO structure that is the same type used to store information received in the call list response (+CLCC). This structure has been extended in Windows Mobile 5.0 to include the disconnect code element.
Single Notification Code Implementation
The second example in the sample RIL works with TTPCom based radios. This is a much simpler notification that indicates, via a single integer code, that a call state change has taken place. This is enabled at initialization by the AT command +EXUNSOL="UR",1.
The notifications are of the format:
+CGURC: &event code&
The following table shows the possible values that event code can be set to, and describes what each value means.
ValueDescription
Active call cleared with held calls
Attempting to make an MO call
MO Call has failed for some reason
MO call is rin