Fast and Simple Mobile Access to Pocket Outlook Data

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.

The ABCs of Pocket Outlook Access

To utilize the new managed classes for Pocket Outlook, you need the following:

  • Visual Studio 2005
  • A Windows Mobile 5.0 device (Pocket PC, Pocket PC Phone Edition, or Smartphone)

The new managed classes are not available for Windows Mobile 2003 Second Edition or earlier devices. You can, however, use Visual Studio 2005 to develop either .NET Compact Framework 1.0 or 2.0 projects that take advantage of the new managed classes.

You need to perform only a few basic steps to access Pocket Outlook data from a Smart Device project in Visual Studio 2005:

  1. Add references to required assemblies.
  2. Create an instance variable for a Pocket Outlook session.
  3. Access the needed collection of information (appointments, tasks, contacts).
  4. Work with the collection.
  5. Dispose the Pocket Outlook session object.

By performing these steps, you can gain access to any information you need.

Adding References to Your Project

To gain access to the new managed classes for Pocket Outlook, you need to add references to two .NET Compact Framework assemblies to your project. You'll find Microsoft.WindowsMobile.dll and Microsoft.WindowsMobile.PocketOutlook.dll in the Add References dialog, as shown in Figure 1.

Figure 1: Necessary References for Pocket Outlook Access

From a coding perspective, you access classes only in the Microsoft.WindowsMobile.PocketOutlook namespace. The other assembly is required, however, because the PocketOutlook assembly has dependencies on the first assembly for interfaces.

The PocketOutlook namespace contains a vast array of classes. Figure 2 shows just some of the available classes you'll see in the Visual Studio Object Browser.

Figure 2: PocketOutlook Namespace Viewed in the Object Browser

Going forward, this article points out some of the more relevant classes to get you started.

Creating an OutlookSession Instance

For developers who have worked with the object model for Microsoft Outlook on the desktop, the Pocket Outlook object model should seem quite familiar. The object hierarchy and tasks associated with programming against this object model are very similar. One example of this is the initial programming step for accessing Pocket Outlook data: creating an instance of an Outlook session.

In the sample project, I created a single form containing a ListView control (named lvAppt) that I programmatically populate with Appointment information. Figure 3 shows this screen in design mode.

Figure 3: Appointments Screen in Design Mode

As you can see, I set up the ListView control into three columns for relevant appointment information. I use a ListViewItem object and its associated SubItems collection to populate this information.

To hold an instance of the PocketOutlook session, I created an instance variable in my form class named AppSession:

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

Fast and Simple Mobile Access to Pocket Outlook Data

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

The 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.

[PocketOutlook5.jpg]

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.

[PocketOutlook6.jpg]

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).

[PocketOutlook7.jpg]

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).

[PocketOutlook8.jpg]

Figure 8: Contact Picker Displayed

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

[PocketOutlook9.jpg]

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");
         }
      }
   }
}

Give Users an Invaluable Resource

For applications that require either extending the existing functionality of Pocket Outlook applications or integrating with Pocket Outlook data, the new managed classes exposed in Windows Mobile 5.0 and the .NET Compact Framework are an invaluable resource. With a minimal amount of time and effort, your Smart Device project can read and manipulate task, contact, and appointment information. If you have been hesitant to add this functionality to your application before, I strongly urge you to reconsider. For others, now might be a good time to evaluate the benefits of providing this type of functionality to your end users.



About the Author

Don Sorcinelli

Don Sorcinelli has been involved in the design, development and deployment of enterprise software applications for over 15 years. Don has also worked with mobile and distributed architectures for almost a decade, and has worked with the PDA and Windows Mobile platform since their inceptions.

Don is a frequent presenter on Windows Mobile development and technologies for MSDN, developer groups and conferences. He is also the Manager of the Boston Windows Mobile Developer Group and founder of BostonPocketPC.com, a web site focused on Microsoft mobile technologies.

Comments

  • There are no comments yet. Be the first to comment!

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: August 14, 2014 @ 2:00 p.m. ET / 11:00 a.m. PT Data protection has long been considered "overhead" by many organizations in the past, many chalking it up to an insurance policy or an extended warranty you may never use. The realities of today makes data protection a must-have, as we live in a data-driven society -- the digital assets we create, share, and collaborate with others on must be managed and protected for many purposes. Check out this upcoming eSeminar and join Seagate Cloud …

  • Cisco and Intel have harnessed flash memory technology and truly innovative system software to blast through the boundaries of today's I/O-bound server/storage architectures. See how they are bringing real-time responsiveness to data-intensive applications—for unmatched business advantage. Sponsored by Cisco and Intel® Partnering in Innovation

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds