S3 Tech Blog: Fast and Simple Mobile Access to Pocket Outlook Data

Share |

For a new developer tool function to be useful, it must be easy to implement, provide a significant benefit to the task at hand, and perform well. As a Windows Mobile developer, I believe the addition of managed classes for accessing and interacting with the data contained within Pocket Outlook (contacts, tasks, and appointments) meets all these criteria.

Developers who build .NET Compact Framework applications for Pocket PCs and Smartphones must all-too-often provide access to Pocket Outlook data. Previously, this meant using P/Invoke to either call native DLLs' functionalities or access internal data stores directly, or acquiring third-party managed code libraries. The result was increased development time and/or increased cost. With the new managed classes, C# and VB .NET Compact Framework developers can quickly gain access to this often-vital information and modify it (if necessary) without additional products.

private OutlookSession AppSession;

For this demonstration, I added code to the form's constructor (immediately following the call to the InitializeComponent method that creates the instance of the PocketOutlook session):

public Form1()
{
   InitializeComponent();

   //Create an instance of the Pocket Outlook session
   AppSession = new OutlookSession();

Accessing the Appointments Collection

The PocketOutlook object hierarchy provides simple access to collections of information. The collections are exposed through properties representing the folders containing associated items. They are accessed directly from the OutlookSession object. The most commonly used of these objects are the following:

Appointments (OutlookSession.Appointments)
Tasks (OutlookSession.Tasks)
Contacts (OutlookSession.Contacts)

Each of these categories also has associated collection objects in the forms of AppointmentCollection, TaskCollection, and ContactCollection. In my sample project, I need to access appointments. So, I created an instance variable to hold an Appointment collection (named AppAppts). To access the Appointments collection, I use the following code:

//Capture the AppointmentCollection into a variable
AppAppts = AppSession.Appointments.Items;

Once you have the collection, you can access individual items using the Appointment object. In my project, I used this object in conjunction with a foreach loop to walk through the collection:

//We now iterate through the entire collection with a foreach,
//using an appointment object...
foreach (Appointment appt in AppAppts)
{
   //Create a ListViewItem object
   lviAppt = new ListViewItem ();

   //Add the appointment date to the ListViewItem, and the time
   //and subject to ListViewItem SubItems
   lviAppt.Text = appt.Start.ToShortDateString();

   lviAppt.SubItems.Add(appt.Start.ToShortTimeString());
   lviAppt.SubItems.Add(appt.Subject);

   //Add the ListViewItem to the ListView
   lvAppts.Items.Add(lviAppt);
}

Note: The Task object for tasks and the Contact object for contacts can be used for this same purpose. Each of these objects provides programmatic access to all of the properties that are stored locally in the Pocket Outlook data stores. Figure 4 shows some of the properties associated with a Task object in the Object Browser.

Figure 4: Task Object Properties Displayed in the Object Browser

Disposing the Pocket Outlook Session Object

When you have completed use of the Pocket Outlook data, you should dispose the session object to free up resources. To do this, simply call the Dispose method of the session instance:

//Don't forget to close the PocketOutlook session when done!
AppSession.Dispose();

Running the Completed Project

he completed code for this sample project looks like the following:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;

using Microsoft.WindowsMobile;
using Microsoft.WindowsMobile.PocketOutlook;

namespace OutlookMobileAPI
{
    public partial class Form1 : Form
    {
        private OutlookSession AppSession;
        private AppointmentCollection AppAppts;
        private ListViewItem lviAppt;

        public Form1()
        {
            InitializeComponent();

            //Create an instance of the Pocket Outlook session
            AppSession = new OutlookSession();

            //Capture the AppointmentCollection into a variable
            AppAppts = AppSession.Appointments.Items;

            //We now iterate through the entire collection with a
            //foreach, using an appointment object...
            foreach (Appointment appt in AppAppts)
            {
                //Create a ListViewItem object
                lviAppt = new ListViewItem();

                //Add the appointment date to the ListViewItem, and
                //the time and subject to ListViewItem SubItems
                lviAppt.Text = appt.Start.ToShortDateString();
                lviAppt.SubItems.Add(
                   appt.Start.ToShortTimeString()
                   );
                lviAppt.SubItems.Add(appt.Subject);

                //Add the ListViewItem to the ListView
                lvAppts.Items.Add(lviAppt);
            }

            //Don't forget to close the PocketOutlook session
            //when done!
            AppSession.Dispose();

        }
    }
}

Before running the application in the emulator, you will need to add some data for appointments. You can do this easily by first bringing up the emulator using the Tools -> Connect to Device. option from the Visual Studio menu. I added three appointments to the emulator, as shown in Figure 5.

Figure 5: Test Data for the Sample Project

When the project is compiled and run in the emulator, it displays the three appointments, as shown in Figure 6.

Figure 6: Sample Data Dsiplayed in the Sample Application

As you can see, very little code is required to expose Pocket Outlook data to your .NET Compact Framework application!

Using the ChooseContactDialog Class

Another useful class in the new managed APIs is the ChooseContactDialog class (also referred to as the Contact Picker). Simply put, use this class in your application to bring up a Contact selection dialog and return the selected contact to your application. This can be extremely useful when you want to quickly provide your user with a means of selecting contact information.

To use the Contact Picker, you will need to add a reference to the Microsoft.WindowsMobile.Forms.dll assembly to your project (this is where the ChooseContactDialog class resides.). To demonstrate this functionality, I created a simple Smart Device project consisting of one form. The form contains holders for information in the form of TextBox and Label objects, and it has one button (see Figure 7).

Figure 7: Contact Picker Demonstration Form

When the user chooses the Select. button in the application, the Contact Picker is displayed and the user can choose a contact. Once selected, the application populates information from the associated Contact object into the fields for display.

To accomplish this, I added the following code to the button's Click event handler to display the Contact Picker:

//Create the instance of the Contact Picker and disable the
//ability to create new contacts from it.
ChooseContactDialog appContactDialog = new ChooseContactDialog();
appContactDialog.HideNew = true;
appContactDialog.ShowDialog();

I then created logic (surrounded by a try...catch block in case the user backs out of the process) to capture the selected contact into an instance variable (named AppContact) and assign the form fields:

try
{
   appContact = appContactDialog.SelectedContact;

   textBox1.Text = appContact.FileAs;
   lblMobile.Text = appContact.MobileTelephoneNumber.ToString();
   lblPhone.Text = appContact.HomeTelephoneNumber;
}
catch
{
   MessageBox.Show("No contact selected");
}

Before running this code in the emulator, I once again need to make sure that I have some contact records available. I used the Connect to Device. menu option in Visual Studio 2005 to populate two records.

When I run the application in the emulator and tap on the button, the Contact Picker appears (see Figure 8).

Figure 8: Contact Picker Displayed

Selecting a contact then returns control to my application, resulting in the contact data being displayed (see Figure 9).

Figure 9: Contact Information Displayed in the Application

Once again, the total amount of coding required for this functionality was very minimal. The following is the complete code for the form class:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using Microsoft.WindowsMobile;
using Microsoft.WindowsMobile.Forms;
using Microsoft.WindowsMobile.PocketOutlook;

namespace ContactPickerDemo
{
    public partial class Form1 : Form
    {
        //Contact object instance
        private Contact appContact;

        public Form1()
        {
            InitializeComponent();
        }

        private void button1_Click(object sender, EventArgs e)
        {
            //Create the instance of the Contact Picker and disable
            //the ability to create new contacts from it.
            ChooseContactDialog appContactDialog =
                new ChooseContactDialog();
            appContactDialog.HideNew = true;
            appContactDialog.ShowDialog();

            try
            {
                //Assign the selected contact to a Contact object
                appContact = appContactDialog.SelectedContact;

                //Populate the form fields
                textBox1.Text = appContact.FileAs;
                lblMobile.Text =
                   appContact.MobileTelephoneNumber.ToString();
                lblPhone.Text = appContact.HomeTelephoneNumber;
            }
            catch
            {
                //If the user backed out, display a message.
                MessageBox.Show("No contact selected");
            }
        }
    }
}