Difference between revisions of "Symbian Orbiter Programmer's Guide"

Revision as of 19:51, 24 February 2008

There are many models of phones, using many different operating systems with varying capabilities. We wanted to make it very quick and easy to add support for all these phones, whether they use Symbian C++, Java, or some proprietary language. Our goal was also to use the same code that runs on the Linux, Windows, and Windows CE Orbiters, so that all the logic and functionality is one place.

Of course, it's not possible for the mobile phones to run Orbiter directly. So, we created a DCE Device, "Bluetooth Dongle". This runs on the media director and is responsible for interfacing with the bluetooth system. It runs on both Linux, using Bluez, and Windows. When a Bluetooth mobile phone comes within range, the Bluetooth Dongle creates a bi-directional communications link with the phone using our BD library. Bluetooth Dongle then spawns internally a copy of Orbiter for the phone. This is the exact same Orbiter code that runs on the PDA's, web pads, and the Linux desktop. The Orbiter program was already designed so that almost all the code is in shared base classes, and there is only a small class that handles the rendering the output and capturing input (i/o) for the target operating system (Windows, X, etc.). So, the Orbiter that is spawned internally within Bluetooth Dongle has a different i/o class--one that instead of rendering to the screen, creates a "Show Image" command which it sends to the phone via the BD processor. And instead of getting input via the touchscreen or mouse, it gets input from the phone via the BD processor.

This means that the software running on the phone itself is very small and simple, since it is effectively only a 'dumb terminal'. The real Orbiter is running on the Linux or Windows pc, rendering each screen, all the text, the data-grids, etc., and just feeding the rendered output to the phone to display. By taking this approach we are able to use almost any phone as an Orbiter, even if it doesn't have enough 'horsepower' to run a real user interface. Also, the code on the phone is short and simple so it should be easy to target other phones.

The BD library, which encapsulates the bi-directional communication used between the phone and the pc, is written in ansi c++. Symbian phones use Symbian C++, which is proprietary and different from regular ansi C++. Yet we figured the code would be much more maintainable if the phone was running the same BD library that the pc runs. So rather than writing a new BD library for Symbian C++, we focused on writing macros and classes that allow Symbian C++ to compile and execute ansi C++ code. In some cases, this meant writing macros to translate ansi C++ into Symbian C++. For example, rather than using the ansi C++ stl "list" template, we created macros which, when compiled under an ansi C++ compiler translate to stl lists, and under Symbian C++ translate into Symbian's proprietary list mechanism. Sometimes we had to write our own Symbian C++ code to provide functionality that was missing in Symbian C++. For example, we wrote our own 'string' class for Symbian that mimics the functionality of the ansi C++ string.

Hopefully, these macros and classes will work across all the various Symbian flavors, although we wrote the code for Series 60 phones.

If you want to run the software on other phones there are only 2 places where the code may be different for the other versions of Symbian. The first is the low-level Bluetooth code in BD, and the second is in the Render Menu, which handles putting graphics on the screen and receiving input.

For the Bluetooth code, see the files BDCommandProcessor_Symbian_Bluetooth.cpp and BDCommandProcessor_Symbian_Base.cpp file in the BD project. All the logic is in the cross-platform base classes, but these 2 handle the actual sending and receiving data.

Then look at the LinuxMCE MO project, which has our Symbian Series 60 project. In the source there is a file PlutoVMCUtil.cpp. This implements the drawing and input. All the logic is in the cross-platform base classes, but this file handles the OS-specific part.