2. Jason Browne Software Engineering Manager Bsquare Corporation ECE307 Inside the Radio Interface Layer (RIL)

3. Agenda What is the RIL? How does the RIL work? Using the RIL from Applications Demo: Putting it all together RIL differences between Microsoft Windows Embedded CE 6.0 and Microsoft Windows Mobile 6

4. What is The RIL? Radio Interface Layer Abstraction layer for cellular technologies A stream driver named “RIL” Main responsibilities Controlling the Radio Hardware (“AT commands,” for example) Instructing the audio manager to control volume and path Provide NDIS interface to Radio Hardware Providing an SMS interface to Radio Hardware Add to image with SYSGEN_CELLCORE_RIL

5. Cellular Architecture Applications / UI Logic Module Windows API Cellular API Core Provider HW Interface Radio Software SMS API Router UDP SIM API WTLS WDP Winsock Auto Bind LSP PPP TCP/IP NDIS WWAN Miniport for GPRS Radio interface Layer (RIL) MUX Driver Radio Stack SIM ToolKit UI SIMTK Policy SIMTK Transport WTP TAPI ExTAPI Cellular TSP NDISUIO Protocol Driver Control Channel Notification Channel DataPort(s) Etc WDP Text RIL Proxy (RIL)

6. RIL Proxy RIL functions to RIL_* IOCTLS RIL_Dial() to RIL_IOCTL_DIAL Passes these IOCTLs to RIL “driver” through RIL_IOControl()

7. RIL Proxy Registration for notifications using callbacks HRESULT RIL_Initialize( DWORD dwIndex, RILRESULTCALLBACK pfnResult, RILNOTIFYCALLBACK pfnNotify, DWORD dwNotificationClasses, DWORD dwParam, HRIL* lphRil ); Two callbacks Asynchronous Function Results Unsolicited Messages/Notifications

8. RIL_Initialize() Example HANDLE hRingEvent; int WINAPI WinMain() { hRingEvent=CreateEvent(NULL,FALSE,FALSE,NULL); hRIL = RIL_Initialize(1, MyRILResult, MyRILNotify,RIL_NCLASS_CALLCTRL, dwParam,&hRil); WaitForSingleObject(hRingEvent,INFINITE); MessageBox(NULL,TEXT("Ring"),TEXT("The Phone is Ringing!"),MB_OK); }

9. RIL_Initialize() Example void CALLBACK MyRILResult( DWORD dwCode, // result code HRESULT hrCmdID, // Command ID const void* lpData, // result data DWORD cbData, // size of lpData DWORD dwParam // parameter passed // to ) { // At this time we do nothing. We could put any initial RIL request handling in here. RETAILMSG(1,(TEXT("TEST Result : I : RIL Result - dwCode = 0x%08x\n"),dwCode)); }

10. RIL_Initialize() Example void CALLBACK MyRILNotify( DWORD dwCode, // notification code const void* lpData, // notification data DWORD cbData, // size of lpData DWORD dwParam // parameter passed // to ) { switch (dwCode) { case RIL_NOTIFY_RING: { SetEvent(hRingEvent); }

11. RIL Proxy Filters for notifications HRESULT RIL_EnableNotifications( HRIL hRil, DWORD dwNotificationClasses ); HRESULT RIL_DisableNotifications( HRIL hRil, DWORD dwNotificationClasses ); Get notifications IOCTL_RIL_GETNEXTNOTIFICATION

12. RIL Proxy RIL_NCLASS_FUNCRESULT – Function Results RIL_NCLASS_CALLCTRL – Call Control RIL_NCLASS_MESSAGE – Messaging RIL_NCLASS_NETWORK – Network Related RIL_NCLASS_SUPSERVICE – Supplementary Service RIL_NCLASS_PHONEBOOK - Phonebook RIL_NCLASS_SIMTOOLKIT – SIM Toolkit RIL_NCLASS_MISC – Miscellaneous RIL_NCLASS_RADIOSTATE – Radio State RIL_NCLASS_VGCSVBS – Voice Group Call and Voice Broadcast Call RIL_NCLASS_DEVSPECIFIC – Device Specific Notification classes

13. RIL Driver RIL_Init() Called during boot up RIL_DeInit() Called when driver is unloaded. (Rarely occurs.) RIL_Open() Called when RIL_Initialize() is called RIL_Read(), RIL_Write(), RIL_Seek() RIL_Powerup(), RIL_PowerDown() Old style Power management functions RIL_IOControl() Most of the functionality is created using this Entrypoint

14. RIL Bootup Process in Microsoft Windows Mobile 6 Phone Client (dialer, SMS API, Call Progress, etc.); calls RIL_Initialize() Fails since RIL not ready Regenum calls RIL_Init() Open communication to Radio Hardware (COM port) Phone Client calls RIL_Initialize Calls RIL_Open Calls IOCTL_RIL_NOTIFICATIONS Initializes Notification Data Structures Calls IOCTL_RIL_REGISTERWITHCPM Register with Call Progress Monitor. (Undocumented not needed.)

15. RIL Bootup Process in Windows Mobile 6 Phone Client Continues to Call Calls PhoneFeature Levels IOCTL_PHGFL_LOCKFACILITY IOCTL_PHGFL_UNIQUECALLTRACKING IOCTL_INTLPLUS IOCTL_PHGFL_SMSUNICODE IOCTL_PHGFL_SUPPORTMOSMS IOCTL_PHGFL_GSM dwCode=0x0300248

16. RIL Bootup Process in WM 6 Phone Client Calls RIL_GETCURRENTPRIVACYSTATUS RIL_CALLPRIVACY_STANDARD RIL_CALLPRIVACY_ENHANCED Phone Client Calls RIL_IOCTL_GETCURRENTSYSTEMTYPE RIL_SYSTEMTYPE_NONE RIL_SYSTEMTYPE_IS95A RIL_SYSTEMTYPE_IS95B RIL_SYSTEMTYPE_1XRTTPACKET RIL_SYSTEMTYPE_GSM RIL_SYSTEMTYPE_GPRS

17. RIL Bootup Process in Windows Mobile 6 RIL proxy scans for notifications using IOCTL_RIL_GETNEXTNOTIFICATION

18. Simple Dialing Commands HRESULT RIL_Dial( HRIL hRil, LPCSTR lpszAddress, DWORD dwType, DWORD dwOptions ); Address String telephone number Types RIL_CALLTYPE_VOICE RIL_CALLTYPE_DATA Options RIL_DIALOPT_RESTRICTID RIL_DIALOPT_PRESENTID

19. Simple Dialing Commands HRESULT RIL_Answer( HRIL hRil ); HRESULT RIL_Hangup( HRIL hRil );

20. Advanced Call Management HRESULT RIL_ManageCalls( HRIL hRil, DWORD dwCommand, DWORD dwID ); Commands RIL_CALLCMD_RELEASEHELD RIL_CALLCMD_RELEASEACTIVE_ACCEPTHELD RIL_CALLCMD_RELEASECALL RIL_CALLCMD_HOLDACTIVE_ACCEPTHELD RIL_CALLCMD_HOLDALLBUTONE RIL_CALLCMD_ADDHELDTOCONF RIL_CALLCMD_ADDHELDTOCONF_DISCONNECT RIL_CALLCMD_INVOKECCBS

21. RIL OEM Extensions Very similar to IOControl HRESULT RIL_DevSpecific( HRIL hRil, const BYTE* lpbParams, DWORD dwSize BYTE* pbAsyncResults = NULL, DWORD dwAsyncResultsSize; DWORD* pcbAsyncResults = NULL, DWORD dwTimeOut; );

22. RIL Call List RIL_GetCallList( HRIL hRIL ); typedef struct { DWORD cbSize; DWORD dwParams; DWORD dwID; DWORD dwDirection; DWORD dwStatus; DWORD dwType; DWORD dwMultiparty; RILADDRESS raAddress; WCHAR wszDescription[ MAXLENGTH_DESCRIPTION ]; DWORD dwDisconnectCode; DWORD dwPriority; } RILCALLINFO; GPRS Calls are not on this list

23. Audio Driver/RIL Connections RIL to Audio Driver Connection Accessory Audio Control Uses RIL_Get/SetAudioDevices, RIL_Get/SetAudioMuting, RIL_Get/SetAudioGain, Easier to create a separate Audio Manager to handle all audio cases than to integrate this directly into the RIL Audio Manager controls Prioritization Path logic Volume control

24. SMS Sending an SMS Message HRESULT RIL_SendMsg( HRIL hRil, const RILMESSAGE* lpMessage, DWORD dwOptions ); Receiving an SMS Message RIL_NOTIFY_MESSAGE lpData Pointer points to a RILMESSAGE

25. NDIS Miniport Newer data connection model “Always on” Uses NDIS to RIL interface to provide the RIL-based data transport to the operating system NDIS Miniport Driver talks to RIL Operating system believes that this is just an NDIS Driver Uses special RIL NDIS callback functions RILNDISTRANSMITTCALLBACK RILNDISRECEIVECALLBACK RILNDISSTATUSCALLBACK

26. RASDIAL for Internet Connections TAPI calls the RIL SetBearerServiceOptions() function with a pointer to RILBEARERSVCINFO structure to set : RIL_SPEED_9600_V32 RIL_BSVCNAME_DATACIRCUIT_ASYNC_UDI_MODEM RIL_BSVCCE_NONTRANSPARENT The return value should be RIL_RESULT_OK. TAPI then calls RIL Dial "T14255551212“ RIL_CALLTYPE_DATA RIL_DIALOPT_NONE.

27. RASDIAL for Internet Connections The RIL driver generates RIL_NOTIFY_DATASVCNEGOTIATED notification with lpData pointing to a RILSERVICEINFO structure set to asynchronous non-transparent Notification ignored The RIL driver generates RIL_NOTIFY_CONNECT notification pointing to a RILCONNECTINFO structure with dwCallType member set to RIL_CALLTYPE_DATA and the dwBaudRate member set to 9600 (or the actual rate of connection)

28. RASDIAL for Internet Connections The driver returns RIL_RESULT_OK for the dial command with lpData = NULL. RAS opens the data port and starts the Point-to-Point Protocol (PPP) negotiation.

29. RASDIAL for Internet Connections TAPI calls RIL GetCallList to verify that the call is active. This step may occur multiple times. The return value should be RIL_RESULT_OK with lpData pointing a RILCALLINFO structure with the following values dwID 1 dwDirection RIL_CALLDIR_OUTGOING dwStatus RIL_CALLSTAT_ACTIVE dwType RIL_CALLTYPE_DATA dwMultiparty RIL_CALL_SINGLEPARTY raAddress "14255551212"

30. Using The RIL from TAPI The application calls the Telephony API (TAPI) lineMakeCall or lineDial functions to initiate the call The TSP creates a new TAPI call in the dialing state The TSP calls the RIL SetAudioDevices function to set the RIL_AUDIO_HANDSET constant as the device for both Transmit (TX) and Receive (RX) audio Returns RIL_RESULT_OK

31. Using The RIL from TAPI The TSP calls the RIL Dial function using the IOCTL_RIL_DIAL IOCTL. This causes RIL_IOControl to be called with IOCTL_RIL_DIAL The RIL driver issues a dial command to the radio. The radio acknowledges that the dial is initiated. The RIL driver returns RIL_RESULT_OK for the dial command

32. Using The RIL from TAPI The RIL driver generates RIL_NOTIFY_CONNECT and RIL_CALLTYPE_VOICE constants The TSP calls RIL GetCallList waits for the RIL_CALLSTAT_ACTIVE mode Returns RIL_RESULT_OK with a RILCALLINFO structure with the following values DwID 1 DwDirection RIL_CALLDIR_OUTGOING DwStatus RIL_CALLSTAT_ACTIVE DwType RIL_CALLTYPE_VOICE DwMultiparty RIL_CALL_SINGLEPARTY RaAddress "14255551212"

33. RIL: Putting it All Together

34. Differences between Windows Embedded CE 6 and Windows Mobile 6 Windows Mobile has WAP-capable browser Windows Mobile has built-in Dialer, Contacts, Call History, SMS Client, Call Progress, etc. Windows Embedded CE 6.0 has renamed the libraries to reflect the MDD/PDD architecture Windows Mobile has a Connection Manager

35. Summary RIL abstracts the Radio Hardware Clients use RIL proxy to connect to RIL Clients use RIL functions and receive RIL notifications RIL provides both voice and data interfaces

36. While You're Here Fill out your session evaluation Enter to win a Windows Mobile ® phone or Zune™ The Battle Begins Stay tuned for the Sumo Robotics competition at the Tao attendee party Meet the geeks The Expert Cabana is packed with MEDC speakers and MVPs

37. © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.