Chapter 18: Working with POOM

The Pocket Outlook Object Model is the gateway to Outlook-specific data. POOM is not only a fun word to say, but also a powerful resource for developers. POOM allows you to integrate seamlessly your mobile applications into the standard core applications found on every Pocket PC.

Working with Contacts

The second of the trifecta of Pocket Outlook data sources is contacts. Contacts offer developers a variety of application opportunities. They provide an easy way to incorporate contact data into a mobile application without all of the overhead of having to roll your own contact code.

As with tasks, contacts provide a Categories property, which is useful in identifying contacts that apply specifically to your application. Contacts are accessed through the Contacts property and the Contact object of the Pocket Outlook .NET component. Each of these items is covered in the following section.

The Contacts Property

The Contacts property of the OutlookApplication object provides access to a collection of contacts that are resident on a device. This property provides an interface to the Contacts folder within POOM, within which resides the contacts. Several of the examples presented in this section demonstrate the use of the Contacts property along with its Items collection in working with contacts.

The Contact Object

All work with contacts themselves is handled through the Contact object. Commonly used properties of this object are shown in Table 18-3. Frequently used methods of the Contact object are shown in Table 18-4.

Table 18-3. Commonly Used Properties of the Contact Object

PROPERTY	DESCRIPTION
Body	Body The notes accompanying a contact
Business Address City	The city portion of the contact's address
Business Address State	The state portion of the contact's address
Business Address Street	The street portion of the contact's address
Business Fax Number	The fax number for the contact
Business Telephone Number	The business number for the contact
Company Name	The categories for which the contact is assigned
Categories	The name of the contact's company
Email Address 1	The e-mail address for the contact
File As	How the contact is filed (typically last name first)
Mobile Telephone Number	The contact's cell phone number

NOTE This is only a small subset of the properties provided by the Contact object. The properties detailed in Table 18-3 are the ones that I've found to be the most useful within a normal mobile business application.Your applications may benefit from the use of the remaining properties and as such, you should familiarize yourself with the complete property list through the Pocket Outlook .NET documentation.

Table 18-4. Frequently Used Methods of the Contact Object

METHOD	DESCRIPTION
Copy	Creates a copy of an existing contact
Delete	Deletes a contact
Display	Displays a contact using the native Contact interface
Save	Saves modifications to a contact

While you will find both of these tables are useful for reference, the following sections, along with the examples, provide a quick-start approach to incorporating contact data into your applications.

Retrieving All Contacts

While it's unusual that your application will want to retrieve a list of all contacts (that is, unless you're creating a Contacts application knockoff), I'm still going to start this section by showing you how this is accomplished. As with tasks, you can retrieve contacts in several ways:

• As a collection of all contacts
   
• As a subset of all contacts
   
• As a single contact

Listing 18-11 demonstrates how to retrieve all contacts. Please note that, depending upon the number of contacts you have resident on a device, this could result in a sizeable collection.

Listing 18-11. Retrieving All of the Contacts

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myContacts As OutlookItemCollection

Private Sub btnLoad_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnLoad.Click
   
' Retrieve all of the contacts.
  myContacts = poApplication.Contacts.Items

End Sub

The key parts of this example are as follows:

• The Imports statement, which must be located at the top of a module.
   
• The declaration statement for the OutlookApplication object.
   
• The declaration of the OutlookItemCollection object, which holds a collection of any Outlook items. In this example, it's a collection of contacts.
   
• Loading the collection of contacts from the OutlookApplication object, poApplication, into the OutlookItemCollection, myContacts.

At this point, the collection myContacts contains a set of contact objects, one for each contact that resides on the test device. As with any collection, you can loop through the collection to access individual contacts and view specific contact information.

Retrieving a Range of Contacts

With contacts, it is more common that you will need to retrieve a subset of all contacts, rather than retrieve all contacts. This subset might be comprised of only those contacts that begin with the letter A, or even as restrictive as a single contact.

Retrieving a subset of contacts is easily accomplished with the use of the Restrict method of the Items collection. Listing 18-12 demonstrates the use of this method. In this example, only contacts that begin with the letter A are returned.

Listing 18-12. Retrieving a Range of Contacts

Imports InTheHand.PocketOutlook
[at the module level]
Dim poApplication As New OutlookApplication
Dim myContacts As OutlookItemCollection

Private Sub btnSelect_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnSelect.Click
   
  Dim strA As String = "A"
  Dim strB As String = "B"
  Dim strQuery As String

' Retrieve contacts that begin with the letter A.
  strQuery = "[FileAs] >= " & ControlChars.Quote & strA & _
    ControlChars.Quote
    strQuery = strQuery & " AND [FileAs] < " & strB & _
    cmbPrefix.Items(cmbPrefix.SelectedIndex + 1) & ControlChars.Quote
  myContacts = poApplication.Contacts.Items.Restrict(strQuery)

End Sub

Much of the preparatory work is identical to that required to retrieve all contacts. You still need the Imports statement and to declare both the OutlookApplication and OutlookItemCollection objects.

The interesting code appears at the bottom of Listing 18-12. Here you build a query string, which restricts the contacts returned to only those that begin with the letter A. Applying this string to the Restrict method provides just the contacts that you're interested in.

NOTE You can restrict contacts using any of the properties provided through the Contact object. While typically this will be the File As property, you are by no means limited to it alone.

Displaying a Contact

As you have already seen with tasks, POOM provides the ability to easily accessha ha and leverage the native application interface of a data type through your application. What users see is a contact, displayed in the typical contact interface.

This functionality is provided through the Display method of the Contact object. Listing 18-13 shows an example of this technique.

Listing 18-13. Displaying a Contact

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myContacts As OutlookItemCollection

Private Sub btnDisplay_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnDisplay.Click
   
   Dim myContact As Contact
 
 ' Retrieve all of the contacts.
   myContacts = poApplication.Contacts.Items
   
'  Display the first contact.
   myContact = myContacts.Item(0)
   myContact.Display()

End Sub

As with the two previous contact examples, you need to add the Imports statement and declaration of the variables for both OutlookApplication and OutlookItemCollection to your module.

At the bottom of Listing 18-13 you'll see that all of the contacts are first retrieved. You could use a subset of the contacts or even a single contact as the starting point. I've chosen to demonstrate all contacts here because it's the easiest to understand.

From this collection of contacts, you extract a single contact, the first, into a Contact object of its own. It's through this Contact object that you gain access to the Display method, which in turn is called to display the selected contact.

Adding a Contact

Adding a contact is a three-step process. First, you need to create a new contact. Second, you need to configure the contact. Third, you need to save the contact.

Listing 18-14 demonstrates adding a contact.

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication

Private Sub btnAdd_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnAdd.Click

    Dim myContact As Contact

    ' Create a new contact.
      myContact = poApplication.CreateContact

    ' Configure the contact.
      With myContact

        .Birthday = CDate("01/01/1960")
        .Body = "This is a sample contact."
        .BusinessTelephoneNumber = "888-555-0001"
        .Categories = "demo"
        .CompanyName = "Acme"
        .Email1Address = "[email protected]"
        .FileAs = "Acme, Joe"
        .FirstName = "Joe"
        .LastName = "Acme"
       .Title = "President"       

        ' Finally, save the contact.
        .Save()
    End With

End Sub

As with all of the previous contact examples, you need to start by adding the Imports  statement and declaring the variables for OutlookApplication and OutlookItemCollection.

At the bottom of Listing 18-14 you'll see the three steps I described. First, the  CreateContact method of the OutlookApplication object is called to create your new contact. Second, you configure the properties of the new contact. Third, the Contact  object's Save method is called to save the contact.

Modifying a Contact

Modifying a contact is similar to adding a contact, only instead of creating a newcontact you load a Contact object from an existing contact. Listing 18-15 demonstrates this process.

Listing 18-15.Modifying an Existing Contact

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myContacts As OutlookItemCollection

Private Sub btnModify_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnModify.Click

    Dim myContact As Contact

    ' Retrieve all of the contacts.
     myContacts = poApplication.Contacts.Items

   ' Modify the first contact.
    myContact = myContacts.Item(0)
    With myContact
        .BusinessTelephoneNumber = "888-555-0001"
        .Save()
End With

End Sub

As with all of the previous contact examples, you start by adding an Imports statement and declaring the variables for OutlookApplication and OutlookItemCollection. At the bottom of Listing 18-15, you'll find where the contact is first retrieved. In this example, all of the contacts are retrieved, but only the first contact is loaded into the Contact object. From this point, you are free to modify any of the Contact object's properties. You finish the modification process by calling the Contact object's Save method.

Now that you've seen the basics of working with contacts, let's put all of these techniques together into a comprehensive example.