Developing NokSync

NokSync on SourceForge

NokSync is hosted by SourceForge, where you may download the latest release, or access the Subversion repository directly.

There is also a Developers Discussion Forum, and a number of Trackers for bug reporting, patches, etc.

NokSync is a Thunderbird extension.
As such it consists of JavaScript (.js) and XML User Interface Language (.xul) files.
The JavaScript calls an XPCOM component called noksyncDLL,
which again calls COM componens from the "Nokia PC suite".

Contents of the NokSync Directory

The interface for the XPCOM DLL (noksync.dll) is defined in INokSync.idl

The main window functionality is defined in main.js_

Building a responsive GUI

When NokSync is running, we want

to have progress indications
to be able to abort long operations

The first solution which comes to mind is to use threads in the .dll.
However, XPCOM threading seems to be quite difficult, and not well documented.
Moreover, the functions in the Nokia PC Suite .dll's are quite "atomic"; i.e. checking for whether a phone is connected returns "immediatly" with "yes" or "no", and reading contacts and appointments is "one-by-one". So, unless something in the Nokia PC Suite is severely broken, it should actually be quite responsive.

So, a better solution would be to implement threads or asynchronous messaging in JavaScript.
However, it does not seem that threading is possible from JavaScript - at least it does not seem to be documented at all.
Further, messaging in Mozilla seems always to be synchronous. E.g. trying commandDispatcher or creating a new window and using dispatchEvent both works synchronously.

The solution? Well, in NokSync we use a timer: windows.setTimeout(), e.g.

	window.setTimeout(stepPreferences, 0);

This will release the current thread to check on the GUI, and as soon as possible call the stepPreferences function.

NokSync Error Handling

Attention:: You must catch all C++ exceptions! Exceptions in dll's will crash Thunderbird.

In NokSync, this is implemented with the macros:

nsresult, hResult and nmpResult in NokSync

Most methods in NokSync are defined like this:

	void someMethod(otherargs..., inout long hResult, inout long nmpResult);

If the windows com system returns a HRESULT failure, the value is returned in hResult.

If the error ultimatly originated in the NMP DLL library, nmpResult will be set to the NmpAdapterError returned.

In both of the above cases, NS_ERROR_UNEXPECTED will be returned as the nsresult return value.

Other C++ exceptions will not return a specific error code.

A textual description of the error can usually be found using GetLastErrorString.

See also:: inout parameters in XPCOM IDL / JavaScript

Hints about Thunderbird and Extensions

Building a Thunderbird extension

The canonical resource is http://developer.mozilla.org/ and a good tutorial can be found at http://kb.mozillazine.org/Getting_started_with_extension_development

However, for XUL the best resource is http://www.xulplanet.com/

And a JavaScript reference: http://www.w3schools.com/jsref/

You may also want reload of the chrome: http://addons.mozilla.org/thunderbird/964/ although NokSync development works fine without.

The Thunderbird Addressbook

The Thunderbird addressbook is documented at http://www.xulplanet.com/references/xpcomref/group_AddressBook.html

You may also want to take a look at another addressbook synchronization extension: http://www.gargan.org/extensions/synckolab.html

Building an XPCOM component

Official tutorial: http://developer.mozilla.org/en/docs/Creating_XPCOM_Components

You must have the Gecko SDK.

Official page: http://www.mozilla.org/projects/xpcom/book/cxc/html/appA.html
How to use Gecko SDK: http://developer.mozilla.org/en/docs/Creating_XPCOM_Components:Setting_up_the_Gecko_SDK#Downloading_and_Setting_the_SDK
Download ftp://ftp.mozilla.org/pub/mozilla.org/mozilla/releases/mozilla1.7/gecko-sdk-i586-pc-msvc-1.7.zip

Some libraries (e.g. libIDL-0.6.dll) are missing in Gecko SDK, so you will also need: http://ftp.mozilla.org/pub/mozilla.org/mozilla/source/wintools-19990429.zip

How to access a component: http://developer.mozilla.org/en/docs/Creating_XPCOM_Components:Using_XPCOM_Components

Browsing installed components should be possible with http://www.hacksrus.com/~ginda/cview/ but I can not get it to work

xpi and registering with regxpcom

Components should be registered with regxpcom. But I could not get it to work:

..\regxpcom.exe  -x . INokSync.xpt
Can not initialize XPCOM Glue
Can not aquire component registrar
Registration failed: (c1f30001) INokSync.xpt

So here is the cool solution: Just copy the .dll and .xpt file in the extensions/components directory, and it works like a charm!

inout parameters in XPCOM IDL / JavaScript

Parameters defined as inout in IDL must be initialized as new Object(); in JavaScript before calling.

For example, myFunction defined in xidl:

	void myFunction(inout long x);

must be called from JavaScript as:

	var myX=new Object();
	myFunction(myX);

Nokia PC Suite

The canonical interface for NOKIA phones is the Nokia PC Suite (http://europe.nokia.com/pcsuite).
However, there are two problems:

Nokia PC Suite only works on Microsoft Windows
Nokia PC Suite synchronizes with Microsoft Outlook, not Mozilla Thunderbird.

Bluetooth through Java

Trying to overcome the two problems, I wanted to implement an interface to (NOKIA) phones over Bluetooth using Java.

There is a standard for such things: JSR-82 (http://jcp.org/aboutJava/communityprocess/final/jsr082/)
... and there is even implementations which can be downloaded. For example from Sun, as described at http://developers.sun.com/techtopics/mobility/apis/articles/bluetoothintro/
... but this is now only for unix!!!
Anyway there is an implementation somewhere

The problem is, that JSR-82 relies on a transport mechanism, which is not standardized. I could not get UARTTransport (the default with Sun) to work. Also tried RXTXcomm (http://users.frii.com/jarvi/rxtx/index.html) and could not get it to work.

So, back to Nokia PC Suite...

Nokia PC Suite and Thunderbird

When Nokia PC Suite is installed, it comes with a few nice .dll's, such as:

Stngs3AS.dll (common functions)
SCM3aS.dll (contact manager)
Cal3aS.dll (calendar)

The documentation can be downloaded here: http://forum.nokia.com/info/sw.nokia.com/id/3bc7878b-9ebf-4d26-8a26-e7b13003d3c9/Nokia_PC_Connectivity_SDK_3.0_Component_Library_Reference.pdf.html

Bad news (1): Only for Windows

As described above (Bluetooth through Java), I could not get a generic Bluetooth interface through Java to work, so we are stuck with Nokia PC Suite.
And since Nokia PC Suite is only available for Microsoft Windows, NokSync will only work on Microsoft Windows.
(What a shame, considering that Thunderbird and XPCOM is cross platform)

Bad news (2): Not for all NOKIA phones

There are many different NOKIA phones with different capabilities, and NOKIA - in their wisdom - has implemented different interfaces for different phones.

Since my phone is a NOKIA 6280, NokSync is using the IPhonebook3 and IContact2 interfaces.

NOKIA is not very clear on which phones are supported by the IPhonebook3 and IContact2 interfaces in the SCM3aS.dll library used by NokSync. The official statement from year 2002 is, that series 62xx and 71xx are supported.

If the NOKIA phone can store more than one phone number per contact (such as both a cellular number and a landline number), there is a good chance that NokSync will work with the phone.

Whether it works or not, please be so kind as to report your model number and product type on the Open Discussion Forum.

Using doxygen

doxygen homepage: http://www.stack.nl/~dimitri/doxygen/
Thank you Dimitri (http://www.stack.nl/~dimitri/)

I was considering using doxygen just for the "code documentation", and using DocBook (http://www.docbook.org/) for the "main body" of documentation. There is a nice package for windows at http://www.e-novative.info/software/ede.php
However, why waste time with this, when doxygen has it all?

doxygen and JavaScript

Native doxygen does not handle JavaScript.
However, there is a nice perl script js2doxy.pl at http://jsunit.berlios.de/internal.html which can be downloaded at http://svn.berlios.de/wsvn/jsunit/trunk/jsunit/util/js2doxy.pl?op=file

Using doxygen for NokSync documentation

The html documentation is generated into the doc directory.

The documentation is generated from the (JavaScript, IDL, and C++) source code, plus the additional files in the dox subdirectory.

The dox subdirectory contains a doxygen.bat file which will call js2doxy.pl for .js files (generating an .js_ file) and then call doxygen.

The doxygen config file dox/Doxygen contains a few customizations; most importantly some EXPAND_AS_DEFINED to make the match between .idl, .h, and .cpp definitions.