I like John Kennedy's proposed SDK TOC for Windows Mobile. And since the sample contains valid links, I was surpised at the amount of content I found which I'd not been able to locate before

While there will always be cases when organising content like this you could end up in heated debates about whether article x belongs in category y or z, I believe it's a definate improvement and gives better visibility of the scope and content of the SDK documentation. I particularly like the fact that Whats New is the first category with itemised details for each update - the SDK documentation has already received two batches of updates.

Update: I've realised there isn't any Telephony content on this contents page. It would be good to have an entry for Telephony (which is an important part of most Windows Mobile devices) and it should link through to TAPI, Phone, SMS and SIM topics.

There has been a lot of activity recently on new Windows Mobile 5.0 devices, in a few cases official announcments, in some cases details leaked through common sources such as the FCC site where products sent for testing are publically detailed.

One of the interesting models to be revealed has been discussed by WallabyFan, with the original scoop at the register. The unique feature of this device is that it is the first Windows Mobile Smartphone to feature a built in GPS. The feature has previously been available on a small number of Pocket PC devices, most recently in the iPaq 65xx range.

HTC are busy with Pocket PC devices in the form of the Universal, and the Wizard - successor to the Magician (iMate JAM and equivalents), and also new Smartphone models such as the Tornado - a WiFi equipped Smartphone.

All in all it looks like a lot of exciting new devices will bring Windows Mobile 5.0 to the market place.

As has already been shown with some of the other libraries in WindowsMobile In The Hand, the object model is generally designed to follow the Windows Mobile 5.0 APIs. There are a few examples where new functionality is exposed which is not found in the WM 5.0 APIs, some of which was designed specifically to complement Windows Mobile 5.0.

In the case of the Forms assembly, none of the WM5.0 forms are supported, this is because functionality such as CameraCaptureDialog and SelectPicture dialog rely on new functionality in the underlying OS - prior to WM 5.0 each OEM implemented their own camera support.

However in WindowsMobile In The Hand, a few new pieces of forms related functionality are added:-

The MessageBox is designed to provide a softkey-enabled message box for Windows Mobile 5.0 Pocket PCs (although it can also be used on prior versions). When used in a Smartphone project it uses the standard compact framework implementation, on a Windows Mobile 5.0 Pocket PC it produces the following:-

It's been designed to follow the Smartphone experience so you can provide the same user experience on both platforms. It supports a full range of overrides for the Show method to specify buttons, icon etc. Here the MessageBoxIcon is used to draw a watermark image on the dialog, similar in spirit to the themed icons which are used on the Smartphone equivalent.

MobileDevice provides a few helper methods to reset the device, and get the platform type identifier e.g. PocketPC or Smartphone.

MobileKeys provides a mapping between the device specific key constants (as defined in winuserm.h) and the desktop key codes, so all of the members are of type System.Windows.Forms.Keys.

OpenFileDialog is built specifically for Windows Mobile 5.0 Smartphone and matches the System.Windows.Forms version available in Pocket PC projects. Again if used in a Pocket PC project it utilises the existing implementation in System.Windows.Forms. It will currently raise a NotSupportedException if used on a Smartphone 2003 device.

Neither .NETCF v1.0 or v2.0 will support runtime hosting, this means it's not possible to write a service in managed code which will run within the Services.exe process. However it is often useful to be able to query and manipulate other system services from managed code.

An example of this is where a system service needs to be stopped so that you can access some hardware - such as the OBEX listener service on Windows Mobile which opens the Infrared port. With this scenario in mind I set about wrapping some of the CE functionality for managing services, using the desktop framework as a model.

The resultant library - InTheHand.ServiceProcess.dll is designed as a subset of System.ServiceProcess.dll - this is the assembly which is added as a reference to your project when you create a windows service project with the desktop framework. The library includes a single class ServiceController which is created with the identifier of the service you which to attach to. Under Windows CE these services have an identifier in the form of a device name e.g. AAAN: where AAA is the prefix, often providing a clue as to the purpose of the service, and N is a numerical index. Returning to our example of OBEX the service is called OBX0:. If you don't know the name of a particular service you can either trawl through the registry under HKLM\Services, or better still call the ServiceController.GetServices static method. The final consideration is to ensure you close/dispose the ServiceController when you have finished working with it. Our OBEX shutdown code looks like this:-

ServiceController scObex = new ServiceController("OBX0:");
scObex.Stop();

while(scObex.Status!=ServiceControllerStatus.Stopped)
{
    System.Threading.Thread.Sleep(1000);
}

scObex.Close();

Notice that the WaitForStatus method isn't supported so in this case we periodically check the status while sleeping. If we weren't bothered when the service shutdown you could leave out this section, even when you call Close() to close our handle to the service it will continue with it's action and shutdown in it's  own time.

In terms of platform support, this services.exe model is supported on CE.NET 4.x and above so this includes Windows Mobile 2003 and above.

You can download the library here:-

http://www.inthehand.com/Services.aspx

Greg Scott from the Windows CE Networking team has posted an interesting article on how Bluetooth Virtual COM ports are implemented on Windows CE.

Alongside the native code to setup a port, there are some details on the improvements in Windows Mobile 5.0 which now includes UI options to set both incoming and outgoing ports and is integrated into the bonding/pairing process. This means that OEMs no longer need to produce their own individual applets to expose this functionality.

For managed code the Bluetooth.NET library wraps this functionality with the BluetoothSerialPort class.

This applies equally to WindowsMobile In The Hand and the Windows Mobile 5.0 APIs. On the collection classes there exists a Restrict method which returns a subset of the collection matching your search query. You can use the resulting collection to databind or otherwise enumerate over.

The query language used is similar, but not the same, as SQL: if you imagine that what you are entering here is just the WHERE clause of a query you will not be far off. The key rules to follow are:-

• Field names must match exactly - refer to the Properties of the Appointment, Contact and Task class for valid field names
• Field names must be enclosed in square brackets e.g. [MobileTelephoneNumber]
• You can combine multiple expressions with AND and OR
• Supported operators are < (Less Than), <= (Less Than or Equal To), > (Greater Than), >= Greater Than or Equal To), = (Equals), <> (Not Equals)
• Items without the property set will not be returned in a query. So if you set a query of [BusinessAddressCity] = "London" it would not return items without the business address city present even though these are not London.
• You can use this knowledge to form a query to return all records where the property is set with [PropertyName] <> "" as all items with the property set will match this pattern.

You can return a full contact list for all items with a mobile number using this code:-

os = new OutlookSession();

PimItemCollection pic = os.Contacts.Items.Restrict("[MobileTelephoneNumber] <> \"\"");

listBox1.DataSource = pic;

listBox1.DisplayMember = "FileAs"

This example bind the collection to a control, the list will show the contact name only but you'll be able to retrieve the Contact object from the SelectedItem property of the list box to use it's other properties (e.g. the mobile number).

For Windows Mobile 5.0 you can use the new ChooseContactDialog which features a RequiredProperties property so you can easily setup the dialog to show only relevant items.

Update: Here is the VB equivalent:-

os = New OutlookSession
Dim pic As PimItemCollection = os.Contacts.Items.Restrict("[MobileTelephoneNumber] <> " & Chr(34) & Chr(34))
ListBox1.DataSource = pic
ListBox1.DisplayMember = "FileAs"

Some users may find that after installing the Windows Mobile 5.0 SDKs, although no errors were reported, they just don't show up in the Visual Studio 2005 create project dialog. The reason for this is that sometimes the install script which runs near the end of setup gets blocked by anti-spyware or anti-virus software sometimes without even prompting the user.

The workaround is quite simple, you just need to locate the script and run it from the command line. Locate the folder where you installed the SDK and the Install_files subfolder. Then run the script passing the full path to the SDK and 0 (to install, if you wanted to manually remove you would pass 1). For example if you installed to the default location you'll need something like this:-

install_script "C:\Program Files\Windows CE Tools\wce500\Windows Mobile 5.0 Pocket PC SDK\" 0

If you've tried documenting .NETCF libraries which make use of Compact Framework specific types you'll know that you have to do all sorts of workarounds and special builds to get an output which can successfully run through NDoc. This is because although the device specific assemblies such as Microsoft.WindowsCE.Forms are marked retargetable there isn't an equivalent in the desktop framework to retarget to.

One solution is aggressive conditional compilation to hide all hints of of these device classes. Another way which is cleaner and easier to deal with when you are regularly updating code and documentation is to build your own dummy classes into your NDoc configuration of your project. I've done this for documenting my own code as I often find myself using MessageWindows etc in my projects. Ratherthan everyone re-invent the wheel you can use the file (see link below) as-is. You will still be producing a separate dll for documentation purposes but the amount of code you have to hack around with is greatly reduced.

Simply add the attached cs or vb file to your project. Then when you build the project in Debug or Release configuration absolutely nothing is added into your dll which will reference Microsoft.WindowsCE.Forms normally. But when you do an NDoc build and define the NDOC conditional constant it will magically spring into life and create a local dummy copy of the whole Microsoft.WindowsCE.Forms namespace. Because of the way the compiler chooses which class to reference your local version will take preference over the official library, thus removing all dependency on the Microsoft.WindowsCE.Forms library.

Microsoft.WindowsCE.Forms.zip (1.27 KB)

For this to work in VB there are a couple of additional points, firstly make sure you don't have a Root Namespace configured (Project > Properties). You will also need VBCommenter to build the XML output used to feed Ndoc (Visual Studio 2005 will introduce built in XML comments generation for VB.NET projects).

Of course the same technique can be used for other device specific assemblies such as System.Data.SqlServerCe, although it contains a lot more types and so is less practical to do in this way. You can instead use this technique just with the individual types/methods you use...

Windows XP supports a much smaller number of socket options for Bluetooth than Windows CE, although it generally provides alternative ways to get/set those properties. The table below shows those that are supported on XP and how they relate to their Windows CE equivalent. Notice that the only one which behaves the same on both platforms is SO_BTH_ENCRYPT

The current version of the Bluetooth.NET library doesn't include the XP versions in the BluetoothSocketOptionName enumeration, but I have added these for the next release.

To illustrate how the WindowsMobile In The Hand is a subset of the Windows Mobile 5.0 APIs I've modified this class diagram for the Windows Mobile 5.0 APIs to ghost out those which are not supported in WindowsMobile In The Hand on earlier devices. The key differences are in support for system state events and in the number of properties supported - there is no easy way to do events for these system properties without a lot of polling which is bad. Also it lacks many new properties on the PIM items (such as Photos for contacts) including the ability to add custom properties - this is based on a lot of work on the underlying POOM APIs which would not be feasable to replicate on older devices.

wm5vwmith1.jpg (679.87 KB)

In a future post we will look at what is added beyond the standard Windows Mobile 5.0 APIs.

Casey posted this cool technique of using the Virtual Earth Locator in your own apps. Next task is to find out how to stop it locating me in Surrey :)

Now that the hype has died down on Virtual Earth it is interesting to see what developers are doing with the product even though it doesn't expose any kind of developer API. The best place to start is at Dr Neil's site Via Virtual Earth. There are a few articles here showing how to pull maps from virtual earth onto your own website. To a user outside the US the mapping detail available is a bit lacking, you get quite a selection of place names, but no roads and satellite imagery only at a very high level.

Hopefully the technologies demonstrated in Virtual Earth will permeate through to the Mappoint Web Service, as the dynamic pan and zoom, imagery and pushpin labels are quite impressive.

Ever wondered how Microsoft test their location products? I mean it's not like you can test them in every possible location. Well two guys in Great Britain are trying to come close by driving the length and breadth of Great Britain passing through key points as they go - They have already covered the furthest South, East and West already. You can track their progress on a special blog and win a copy of Autoroute with GPS receiver if you estimate their mileage.

Autoroute 2006 (European version of Streets & Trips) is due out in October, no details of features for the new release have been announced yet.

Today I gave a session at Slide5 on the latest version of the Bluetooth library - v1.4. Key changes for this release were some bug fixes to the samples, increased functionality for the desktop side (ability to bond devices) and service discovery (as yet XP only). I've also tidied up some of the code, in order to have just a single place to determine the platform at runtime. I'll post a version of the OBEX demo I did shortly, but I'll build it as a VS2003 project (the app used for the session demo was built with VS2005 Beta 2)

Downloads

The "Implementing a Proximity Search with SQL 2000" article describes how to create a local method of searching for nearby places on your own locally held data. However it makes a couple of assumptions, one being that you will import your data via Access.

It's quite likely that you may want to put your place data directly into SQL Server, you can then calculate the X, Y and Z co-ordinates using a stored proceedure. Firstly I'll assume you place the data into a table in your SQL database with fieldnames Latitude and Longitude storing the values in decimal degrees as a float type. You'll also need to add columns named XAxis, YAxis and ZAxis to your table, again with a float type. Then the following stored proceedure can be used to populate these fields.

UPDATE [tablename] SET XAxis = cos(RADIANS(Latitude)) * cos(RADIANS(Longitude)),
YAxis = cos(RADIANS(Latitude)) * sin(RADIANS(Longitude)),
ZAxis = sin(RADIANS(Latitude))
WHERE XAxis IS NULL;

Note that the where clause ensures it doesn't process rows you have already populated. You may choose to run this procedure manually when you add new data, or schedule it to run regularly. If your data is editable once it's in the database, you should ensure the X,Y,Z values are removed if the Latitude and Longitude are changed on a record. Once you've run this on your data you can use the FindNearby procedure described in the article.

Earlier I posted to the newsgroup a description of using Alex Feinman's Tapi Wrapper to retrieve the IMEI of the phone device. When I checked again, the specific required method is not included in the wrapper, however as Alex has made the line handles accessible it's easy to tag functionality onto the library without re-inventing the wheel. I put together a VB example to P/Invoke the lineGetGeneralInfo method to retrieve information about the phone device. If you use this on a Smartphone device you may find it doesn't work - this is because many Smartphone devices require signing to access many of the TAPI methods. I tested this on a HTC Phone Edition device

TapiVBExample.zip (52.74 KB)