Have you ever wanted to mess around with calling functionality of a mobile phone running Windows Mobile?

I have this nifty phone but how do I control it programmatically?

Well, first of all, the Windows Mobile Radio Interface Layer works by having specific modules control the cellular component. Since we are in North America there are two different cellular protocol implementations: GSM and CDMA. Above this layer is an abstraction layer that hides the implementation of the underlying protocol so that applications/OEM phone developers can use the functionality of call handling (and other useful information) without getting down to how things work under the hood. So how do we, as an application, talk to this abstraction layer, which we'll just clump together and call it the RIL( Radio Interface Layer )? Good Question!

Since cellular devices are really just modems that use AT commands, the RIL operates mainly from an asynchronous callback system. In fact most of the RIL functions really just map to AT commands. The application accessing the RIL makes a request to the RIL, and the RIL takes some time to process this request and sends back a result code indicating the success or failure of the request. In addition the RIL spits out notifications which our application can hook into and be informed of status changes related to the cellular network. So let's dig a little with some RIL examples.

There are a few pitfalls by going down this path. Firstly you might run into situations where you're fighting for control with the resident dialer (the default phone application supplied to the mobile device; developed by Microsoft). There may also be some undocumented internal states that need to be obeyed or else it can lead to unintended behavior (i.e. device lock up).

There are also some differences to note between CDMA and GSM RIL implementations. With GSM devices there can be multiple lines, and as such the RIL can fetch call information for each line. RIL can also manage the GSM lines to perform actions such as putting the call on hold or switching lines. In the CDMA environment, there is only one "real" line and one "virtual" line. That is, one line is used to represent two lines. Access between the two lines is achieved by sending a "flash" command. Call management is also not possible with CDMA. So when you call "RIL_GetCallList" for GSM, for example, you may be returned information for one or more lines depending on the call state. For CDMA, you will only see at most one line.

You will have to get your hands on the ril.h and ril.lib files. Both of these files are floating around somewhere on the internet (try here). If you can get both of these files, link your application with ril.lib and away you go. If you can’t find ril.lib but have ril.h, you can dynamically link with the ril.dll file (contained in the “windows” folder on the device) since you know what some of the prototypes are.

First we need to initialize our application with the RIL so that we can receive both results and notifications callbacks. Here’s some code to do this:

...

// keep this handle handy as we need it for further RIL commands
HRIL rilHandle;

...

HRESULT hr = RIL_Initialize(
   1,                  // index of the RIL port to use (e.g., 1 for RIL1:)
   &resultCallBack,    // this is a pointer to your result call back method
   &notifyCallback,    // this is a pointer to your notify call back method
   RIL_NCLASS_ALL,     // all notification (except device specific)
   (DWORD) this,       // custom param (could be a pointer to an instance of a class)
   &rilHandle);        // returned handle to RIL instance


...

void CALLBACK resultCallback(
   DWORD dwCode,
   HRESULT hrCmdID,
   const void *lpData,
   DWORD cbData,
   DWORD dwParam)

{
   // handle the results

...

void CALLBACK notifyCallback(
   DWORD dwCode,
   const void *lpData,
   DWORD cbData,
   DWORD dwParam)
{
   // handle the notification

...

Note that we’ve initialize the RIL with a reference to our class as the user parameter which is passed to the result and notification callbacks. The parameter is optional; however having the class reference would be especially useful if you would like to perform further actions after receiving a result or notification. More on this later.

OK so what - I've just initialized myself with RIL - what can I do now?
To answer that question, anything under the Sun related to call handling, and then some!!

For example if you wish to check the call status of the phone you can do the following. First send a request for call list:

HRESULT cmdID;

...

void getCallList()
{
   // call RIL_GetCallList with RIL handle from the initialization
   cmdID = RIL_GetCallList(rilHandle);
}

Next we have to wait for the results:

...

void CALLBACK resultCallback(
   DWORD dwCode,
   HRESULT hrCmdID,
   const void *lpData,
   DWORD cbData,
   DWORD dwParam)
{
   If (cmdID == hrCmdID && RIL_RESULT_OK == (dwCode & 0xff))
   {
       // lpData points to an array of  structures.
       RILCALLINFO *lpCallInfo = (RILCALLINFO *)lpData;
       // extract the call info from the structure and do something...
...

Notice how the cmdID return value of RIL_GetCallList matches hrCmdID in the callback. In a realistic scenario, multiple commands are sent and the results do not necessary return in the same order the commands were sent. As a result we would need to queue up the command IDs in order to properly identify the command represented by each callback

Now what is notifiyCallback useful for? This function is called basically whenever an event occurs that is of a notification class that was registered during initialization (we registered with RIL_NCLASS_ALL in this case). For example, for an incoming call you would receive and handle the “ring” notification as follows:

void CALLBACK notifyCallback(
   DWORD dwCode,
   const void *lpData,
   DWORD cbData,
   DWORD dwParam)
{
   if(dwCode & RIL_NCLASS_CALLCTRL)
   {
       switch(dwCode & (0xff | RIL_NCLASS_CALLCTRL))
       {
       case RIL_NOTIFY_RING:
           // do something here
...

Since the phone is ringing, it is probably best to get more information about the incoming call. If you remember from initialization we use the class reference as the custom parameter. This gives us the flexibility to send further RIL commands by either passing in the RIL handle (HRIL) or point to a function in the class. In this case we can point back to the getCallList function created earlier.

MyClass* myClass = (MyClass*)dwParam;
myClass->getCallList();

If we don’t have a function to point to, we can always send an RIL command on the fly by passing in the RIL handle from our class. For example to answer the call right away:

MyClass* myClass = (MyClass*)dwParam;
HRESULT hr = RIL_Answer(myClass->rilHandle);

As a note, if we're not using the interface anymore we'll need to de-register ourselves:

RIL_Deinitialize(rilHandle);

To learn more about RIL and all its wonders, you should closely examine the ril.h header. There is some information on the msdn site as well. The best way to learn about it, of course, is to just try it out yourself.

(Originally written and concept by Quan Nguyen; modified and edited by Henry Yi)

Labels: RIL, Windows Mobile