34.7. Windows Mobile APIs

The most recent versions of Windows Mobile have given mobile developers access to the next generation of APIs for accessing device information. The improvements include managed APIs for existing functionality as well as a Notification Broker that enables developers to tap into system events. This section shows you how you can get started with these APIs.

To access the Windows Mobile managed APIs, you need to add references to the WindowsMobile assemblies. You can do this using the Add Reference item from the project's right-click context menu off the Solution Explorer. Seven assemblies are listed with the prefix Microsoft.WindowsMobile in the .NET tab of the Add Reference dialog. The functionality can be broken down according to the namespaces that are included (with the exception of the DirectX library, which for the sake of brevity is not included here).

34.7.1. Configuration

The configuration namespace includes a single class, the ConfigurationManager, which is used to test and process an XML configuration file that can be used to configure a device. For example, the following code adds the Microsoft web site to the list of favorites:

Imports Microsoft.WindowsMobile
Imports System.Xml
Public Class Form1
    Private Sub configurationExample(ByVal sender As System.Object, _
                                     ByVal e As System.EventArgs) _
                                                         Handles SampleButton.Click
        Dim configDoc As XmlDocument = New XmlDocument()
        configDoc.LoadXml( _
            "<wap-provisioningdoc>" + _
            "<characteristic type=""BrowserFavorite"">" + _

"<characteristic type=""Microsoft"">" + _
            "<parm name=""URL"" value=""http://www.microsoft.com""/>" + _
            "</characteristic>" + _
            "</characteristic>" + _
            "</wap-provisioningdoc>" _
            )
        Configuration.ConfigurationManager.ProcessConfiguration(configDoc, False)

    End Sub
End Class

In addition to the ProcessConfiguration method, which applies changes on the device, there is also a TestConfiguration method that can be used to validate a particular configuration file without any impact on the device on which the code is being run.

34.7.2. Forms

The Forms namespace has managed wrappers for three forms that can be used to collect an image from a camera (CameraCaptureDialog), select a contact (ChooseContactDialog), and select an image (SelectPictureDialog). The following code snippet makes use of each of the dialogs:

Imports Microsoft.WindowsMobile
Public Class Form1
    Private Sub Example(ByVal sender As System.Object, _
                        ByVal e As System.EventArgs) Handles SampleButton.Click

        Dim camera As New Forms.CameraCaptureDialog
        camera.Mode = Forms.CameraCaptureMode.Still
        camera.StillQuality = Forms.CameraCaptureStillQuality.High
        camera.Title = "Get me a picture!!!"
        If camera.ShowDialog() = Windows.Forms.DialogResult.OK Then
            MsgBox("Photo taken.....stored as" & camera.FileName)
        End If

        Dim picture As New Forms.SelectPictureDialog
        picture.CameraAccess = True
        picture.SortOrder = Forms.SortOrder.DateDescending
        If picture.ShowDialog() = Windows.Forms.DialogResult.OK Then
            MsgBox("Found that picture - " & picture.FileName)
        End If

        Dim contact As New Forms.ChooseContactDialog
        contact.RequiredProperties = New PocketOutlook.ContactProperty() _
                                      {PocketOutlook.ContactProperty.Email1Address}
        contact.ChooseContactOnly = True
        If contact.ShowDialog Then
            MsgBox("Contact selected - " & contact.SelectedContactName)
        End If
    End Sub
End Class

34.7.3. PocketOutlook

The PocketOutlook namespace includes a series of classes that make sending and receiving e-mail and SMS messages straightforward. As the following sample shows, writing an e-mail is as easy as starting an Outlook session, putting the e-mail together, and sending it:

Imports Microsoft.WindowsMobile
Public Class Form1
    Private Sub POOMExample(ByVal sender As System.Object, _
                                  ByVal e As System.EventArgs) Handles
SampleButton.Click
        Using poom As New PocketOutlook.OutlookSession
            Dim email As New PocketOutlook.EmailMessage
            email.To.Add(New PocketOutlook.Recipient("[email protected]"))
            email.Subject = "Sample Email"
            email.BodyText = "This email contains sample text to show how easy
email is . . ."
            poom.EmailAccounts(0).Send(email)
        End Using
    End Sub
End Class

34.7.4. Status

The Status namespace contains a wealth of information about the status of the device, including static attributes, such as whether there is a camera on the device, and dynamic attributes, such as the ActiveSync status. The following example shows how these two attributes can be queried:

Imports Microsoft.WindowsMobile
Public Class Form1
    Private Sub StatusExample(ByVal sender As System.Object, _
                                    ByVal e As System.EventArgs) Handles
SampleButton.Click
        If Status.SystemState.ActiveSyncStatus = _
               Status.ActiveSyncStatus.Synchronizing Then _
                         MsgBox("Active sync is synchronising now, don't go away!")
        If Status.SystemState.CameraPresent = True Then _
                         MsgBox("There is a camera, why not take a photo")
    End Sub
End Class

You can also query entries using the RegistryState class in this namespace.

34.7.5. Telephony

The Telephony namespace contains a single class, Phone, which has a single static method called Talk, which can be used to initiate a phone call. An optional parameter, showPrompt, determines whether the user is prompted to proceed with the call or not. In the following code, the user is not prompted before the call is initiated:

Imports Microsoft.WindowsMobile
Public Class Form1
    Private Sub TelephonyExample(ByVal sender As System.Object, _
                                     ByVal e As System.EventArgs) _
                                                         Handles SampleButton.Click
        Dim t As New Telephony.Phone
        t.Talk("0412413425", False)
    End Sub
End Class

34.7.6. The Notification Broker

One of the significant improvements in Windows Mobile 5.0 and above is the Notification Broker, which can be used to notify an application of a particular system event. This may be a change in any of the status states or it may be an incoming SMS or e-mail. The following example shows how you can register your application to intercept an SMS containing a particular string (in this case, "::"). If an incoming SMS is found to contain this string, the application is notified via the appropriate event handler and given an opportunity to process the SMS, after which the SMS is deleted. The other InterceptionAction is to just notify the application, without deleting the SMS after processing:

Imports Microsoft.WindowsMobile.PocketOutlook
Imports Microsoft.WindowsMobile.PocketOutlook.MessageInterception

Public Class Form1
    'Create the Interceptor
    Dim SMSProcessor As New MessageInterceptor( _
                                          InterceptionAction.NotifyAndDelete, True)
    Private Sub NotificationExample(ByVal sender As System.Object, _
                                     ByVal e As System.EventArgs) _
                                                         Handles SampleButton.Click

        'Define the search condition, in this case must contain ::
        Dim msgCondition As New MessageCondition()
        msgCondition.Property = MessageProperty.Body
        msgCondition.ComparisonType = MessagePropertyComparisonType.Contains
        msgCondition.ComparisonValue = "::"
        SMSProcessor.MessageCondition = msgCondition

        'Attach an event handler
        AddHandler SMSProcessor.MessageReceived, _
                                             AddressOf SMSProcessor_MessageReceived
    End Sub

    'Event handler for when a matching SMS is received
    Private Sub SMSProcessor_MessageReceived _
                   (ByVal sender As Object, ByVal e As MessageInterceptorEventArgs)
        Dim theSMS As SmsMessage = CType(e.Message, SmsMessage)
        MsgBox("Message: " & theSMS.Body)
        Me.BringToFront()
    End Sub
End Class

Note that there is a trick to writing these types of SMS-intercepting applications using the emulators. Some of the emulators have built-in radio stacks, which means that they can simulate sending and receiving SMS messages. If you want to test the SMS interceptor, you can send an SMS, using Pocket Outlook or another application on the emulator, to the emulator's built-in test number, which is +1 425 001 0001. The SMS is delayed so that it doesn't appear immediately, enabling you to navigate back to your application if you need to.