Programming with eMbedded Visual Basic and the Pocket Outlook Object Model

 

This article will show you how to use eMbedded Visual Basic to gain access to your PIM data. You'll also learn how to use the tools to effectively build new applications that enable you to customize the display and manipulate PIM information.

Applies to:
   Microsoft Windows Powered Pocket PC 2000
   Microsoft eMbedded Visual Basic

Coming from a programming background, the first thing I always check out when I get a new device is: Are the development tools available so if there's something I don't like I can do something about it?

I have specific requirements when it comes to PIM functions, so that's usually the first thing I look at. The Pocket PC's interface, although much better than earlier versions of Windows CE still leaves a bit to be desired, for my particular needs, when it comes to advanced PIM functionality. Personally, I like integrated applications, like Outlook on the PC, everything in a single application, easily accessible and easy to use. For this reason I delved into the Pocket Outlook Object Model (POOM) to see what I could do. It turns out, that you can do just about anything you want, from simply adding new items to your calendar or task list, to advanced queries and manipulation of your data.

Getting Started

You will need to have eMbedded Visual Basic, the Pocket PC emulator, and the SDKs installed on your PC. If you don't already have a copy of these tools, you can order them for free or download them.

The first thing you need to know is that you have full access to the POOM documentation right at your fingertips. It's located under the following tree inside the eMbedded Visual Basic Help:

Pocket PC SDK/Reference/API reference/Pocket Outlook/Interfaces

Now, in order to take advantage of eMbedded Visual Basic's ability to display all the properties and methods for a particular object, you need to add a reference to the POOM. This is undocumented and I found it only by trial and error. You will need to know where you installed the Pocket PC emulator and then add a reference to the POOM .dll. You do this by selecting References from the eMbedded Visual Basic Project Menu, then browsing to find the .dll. The following is the path for it:

\Windows CE Tools\wce300\MS Pocket PC\emulation\palm300\windows\pimstore.dll

When you attempt to add this, you will get an error "The selected library is not marked as usable in your current platform. Would you like this library added?" Answer Yes. Then select it. Your References window should now look like figure 1:

Figure1: References window, including Pocket Office Object Model.

Next you'll need to create some objects to reference information in the POOM.

Public polApp As PocketOutlook.Application

Public polItems As PocketOutlook.Items

Public Quote as string

polApp declares a reference to the POOM itself, and polItems to a POOM collection of items. Next you need to initialize these and log on to Outlook. The following code establishes this:

Set polApp = CreateObject("PocketOutlook.Application")

polApp.Logon

Quote = chr(34)

The Quote variable is used to place quotation marks around strings inside of certain statements, as you'll see below.

Retrieving Information

Now that you're connected, it's time to fetch some data to get familiar with the POOM data structures. The Pocket PC stores its PIM information in folders, and there are default folders for the basic data types: Calendar, Tasks, and Contacts. These are represented with the following constants: olFolderCalendar,olFolderTasks, and olFolderContacts.

Let's take our polItems object and assign some data to it. First, let's get today's appointments by first setting polItems to the default calendar folder as follows:

Set polItems = polApp.GetDefaultFolder(olFolderCalendar).Items

If you were to check out some of the properties of polItems at this point like polItems.count, you would get the total number of items in your calendar, past, present, and future. Clearly we don't want to look through each item to determine whether it's start date is today. Thankfully, Microsoft has provided a method called 'restrict' that enables us to select subsets of information in these folders. You can use it as follows to get just a list of today's appointments:

strquery = "[Start] = " & Chr(34) & formatdatetime(Now,vbShortDate) & Chr(34)

Set polItems = polItems.Restrict(strquery)

The variable 'strquery' looks like this after we set it up:

[Start] = "11/7/00"

The chr(34) generates a quotation mark character. The next statement causes Outlook to restrict the items in the polItems collection to only things that match the query specified in the restrict clause. Now, if you iterate through the collection you only get today's appointments. Declare a variable to hold an individual appointment and use the following loop to see each one.

Dim polAppt As PocketOutlook.AppointmentItem

Dim x as integer

For x = 1 to polItems.count

           Set polAppt = polItems.items(x)

Next x

Well, we have successfully opened and fetched today's appointments. The query we used in the above example was very simple, but can be enhanced to support multiple conditions and sorting options. A multiple condition might be:

[Start] > "1/1/00" and [IsRecurring] = True

This selects all recurring appointments that start after Jan 1, 2000. Using Parenthesis, equality operators, Boolean tests, and/or conditions, etc. you can create fairly sophisticated queries against your PIM data.

As a more advanced example let's open up the Contacts folder. Use the following code to get a reference to your complete contacts collection:

Set polItems = polApp.GetDefaultFolder(olFolderContacts).Items

Now, we can ".restrict" the data to one particular category as follows:

Strquery = "[Categories] = " & Quote & "Business" & Quote

Set polItems = polItems.Restrict(strquery)

This selects only contacts in the "Business" category. We can further restrict the collection returned by company using the following query:

Strquery = "[Categories] = " & Quote & "Business" & Quote

Strquery = strquery & " and [CompanyName] = " & Quote & "Microsoft" & Quote

Set polItems = polItems.Restrict(strquery)

This selects all contacts with a Company Name of Microsoft in the Business category. You can use "and" and "or" qualifiers to build your own complicated selection and search criteria.

These techniques apply to all the different types of data (Calendar, Tasks, and Contacts).

Creating New Information

There are two ways to create new information: programmatically and user entry. Programmatically means the software creates a new object, sets the fields to the appropriate values, and then saves the record back. The following examples use Contact data for an example, but this applies to all the different data types. This next example creates a new contact record this way.

Dim pContact As PocketOutlook.olContactItem 
Set pContact = polApp.CreateItem(olContactItem)
pContact.FirstName = "John"
pContact.LastName = "Smith"
pContact.CompanyName = "A. Datum Corporation"
pContact.BusinessTelephoneNumber = "123-456-7890"
pContact.Save 

Simple enough!

Now, the second method is to create the item the same way, but then let the user set the data using the standard Outlook entry forms.

Dim pContact As PocketOutlook.olContactItem 
Set pContact = polApp.CreateItem(olContactItem)
pContact.Display
pContact.Save 

The only reason to use this method, would be to add functionality to an application that lets the user create a PIM data item as part of some other functionality, or as part of some integrated solution.

The .Display method causes the basic Outlook contact entry form to be show with all blank fields. The user then enters the data and hits the OK button at which point your program continues with the .Save method. You can interrogate and change the data after the display method to perform validation, and so forth.

To add a Task or any other type of information you use the appropriate pre-defined constants (olContactItem, olTaskItem, olAppointmentItem) where necessary.

Sorting

One of the most basic shortcomings in the Pocket Outlook version lies in the contact applications inability to sort by anything except the 'File As' field as defined in your desktop Outlook version. That's all well and good, but if you want your contacts sorted by Company Name or First Name on an ad-hoc basis you were just out of luck.

The good news is that you can write your own basic contact sorting application very easily with eMbedded Visual Basic and do whatever sorting you want. Using the variable definitions from above:

Set polItems = polApp.GetDefaultFolder(olFolderContacts).Items

This references the entire contacts collection. To simply sort on any field you just use the '.sort' method as follows:

Call polItems.Sort("[CompanyName]", False)

This sorts the polItems collection on the '[CompanyName]' field and the False means sort it in ascending order. How simple is that! The list of all the fields and their names in a particular collection can be found in the POOM documentation.

Unfortunately there is one major restriction here: You can only sort on a single field (at least I haven't discovered how to sort on multiple fields). So for example you couldn't sort on LastName within CompanyName, which would be really nice.

You can also sort the appointment and tasks collections. For example, to sort your tasks by priority use the following code:

Call polItems.Sort("[Importance]", True)

This call sorts your tasks by priority in descending order, which is High to Low.

And Don't forget Searching...

You can search your data in any of the apps by using the '.find' and '.findnext' collection methods. The criteria that you specify for your search can be a simple search like '[CompanyName] = "ABC"' or complex using multiple conditions using and/or. Searching can again be used on any type of data!

Conclusion

Well, I hope that this brief introduction to the POOM has provided you with some basics that you can now take away to play with and expand to suit your own needs. My intent in this article was to demonstrate two things: that eMbedded Visual Basic is powerful enough to build dynamic and useful business functionality, and to show that you can tap into your own data to enhance the basic capabilities of Pocket Outlook. This is my first Pocketpc.com article, and I hope you find it effective and useful. For more information on using eMbedded Visual Basic and the POOM see the following Microsoft Knowledgebase Article entitled, Access Pocket Outlook Objects from VBCE.