Looking at Pocket Outlook's Object Model The object model of POOM is fairly straightforward. There are several objects, but similar to many Microsoft Office automations, the object classes that are directly creatable are limited. In fact, the only directly creatable object in POOM is PocketOutlook.Application. All other objects in POOM need to be derived from the Application object. The derivable objects in POOM: -
AppointmentItem is a calendar item record object. -
CityItem contains information about a city and is provided from the World Clock application. It may have different entries based on the manufacturer's specifications. The folder where CityItem persists can have custom-defined cities added, but, default cities are ROM-based and can't be modified. -
ContactItem is a contact item record object. -
Exception is a single exception to the recurrence pattern of a calendar record (AppointmentItem). -
Exceptions is a collection of the Exception object. -
Folder is a collection of items, and can contain any of four objects: Contacts, Appointments, Tasks, or Cities. -
Recipient is a single attendee of an Appointment. Strictly read-only in eMbedded Visual Basic. -
Recipients is a collection of recipients for an Appointment. -
RecurrencePattern represents the recurrence pattern for an appointment. -
TaskItem is a task, "To-Do" item record object. -
TimeZone represents a singular time zone. It provides information such as observation of daylight savings time and the difference between "Universal Time" (Greenwich Mean Time) and the particular time zone the object represents. The PocketOutlook.Application Object The POOM PocketOutlook.Application object provides interfaces to access the rest of the objects within the POOM SDK. All other objects are derived from the PocketOutlook.Application object. Let's see how PocketOutlook.Application is created and initiated for use: Public gobjPoom As PocketOutlook.Application ' create the PocketOutlook application once and only once.... Set gobjPoom = CreateObject("PocketOutlook.Application") ' logon - can not use until Logon is called... gobjPoom.Logon As with all ActiveX DLL objects in eMbedded Visual Basic, the CreateObject memory leak needs to be minimized by creating the ActiveX object only once. In the preceding example, the variable reference to hold the PocketOutlook.Application object is declared Public. PocketOutlook.Application is then instantiated by using the CreateObject function. Next , the Logon method is called to initialize the object; although there's currently no security or user profiles on the PIM store, POOM follows the Microsoft Office model with the Logon method call. The POOM object won't operate properly without calling Logon. The PocketOutlook.Folder Object The PocketOutlook.Folder object is basically an object to access, sort , filter, and modify a collection of other POOM objects. The Folder object is derived by calling the GetDefaultFolder method of PocketOutlook.Application. GetDefaultFolder takes a single parameter of type PocketOutlook.olDefaultFolders. This enumeration allows access to the following folders: | Object Type | Enumeration | Description | | Calendar(Appointments) | olFolderCalendar | All Appointments from the Calendar application. | | Cities | olFolderCities | Collection of cities from both the World Clock application and custom-defined cities. | | Contacts | olFolderContacts | All Contacts from the Contacts application. | | Infrared | olFolderInfrared | "Parking lot" for any item to be beamed or received via infrared. | | Tasks | olFolderTasks | All Tasks from the Tasks application. | A PocketOutlook.Folder object is derived as the return value of the GetDefaultFolder method. Let's look at how you can create a folder containing all the Contact objects (records): Dim objFolderContacts As PocketOutlook.Folder ' get all contacts Set objFolderContacts = gobjPoom.GetDefaultFolder(olFolderContacts) The first statement here declares a local variable, objFolderContacts, to hold the reference to the folder. The PocketOutlook.Application, gobjPoom, declared globally as discussed previously, is used to derive the Contacts folder into the variable objFolderContacts. This reference now allows access to all contact records within the object store. Each ContactItem, AppointmentItem, and TaskItem object has a Category property. This property contains a comma-delimited list of the categories assigned to the item. The PocketOutlook.Items Collection The PocketOutlook.Items collection belongs to the PocketOutlook.Folder object. This collection allows access to each item within the folder. It is this collection that allows enumeration of the object to a derived reference for PocketOutlook.ContactItem, PocketOutlook.TaskItem, or PocketOutlook.AppointmentItem. Enumerating the Items Once a PocketOutlook.Folder is derived, PocketOutlook provides the Items collection of objects, which individually correlate to a PIM record. Depending on which folder was derived, the folder allows an enumeration through the Items collection to individually inspect and manipulate the object (PIM record), as shown in Listing 6.1. These objects provide a singular reference to a record existing in the native PIM object store. Each object provides properties that correspond to a field within the PIM record. Some data is represented in a collection, such as the Recipient collection on an Appointment object. Listing 6.1 Enumerating Folder Objects Dim objFolderContacts As PocketOutlook.Folder Dim objContact As PocketOutlook.ContactItem ' create the application object Set gobjPOOM = CreateObject("PocketOutlook.Application") ' logon - can not use until Logon is called... gobjPOOM.Logon ' get all contacts Set objFolderContacts = gobjPOOM.GetDefaultFolder(olFolderContacts) For Each objContact In objFolderContacts.Items MsgBox objContact.FileAs Next In Listing 6.1, the PocketOutlook.Application is created, Logon is called, and then a Folder object (of type ContactItem) is derived from GetDefaultFolder. Each Contact object within the Items collection is then enumerated, and the FileAs property is then displayed via a message box. Sorting Items with the Items.Sort Method The Items collection can be sorted via the Items.Sort method. The Sort method has two parameters: -
pwszProperty is a string value for the field (or property) to sort on. The actual property name needs to be enclosed in brackets (for example, [LastName], [Subject], or [Importance]). The sort can be accomplished on any property except Categories, Recipients, and ReminderTime. -
fDescending is an optional Boolean, as to whether to sort descending, where True means to sort descending. When the Sort method is called, the Items will present themselves in the requested sort order. It's important to remember a reference to the Items must be made first and then the Sort method called on it; if Sort is called directly from the Items collection on the folder, the sort will revert to the default sort order. Listing 6.2 shows an example of this approach. Listing 6.2 Sorting Items Dim objFolderContacts As PocketOutlook.Folder Dim objContact As PocketOutlook.ContactItem Dim objItems As PocketOutlook.Items ' create the application object Set gobjPOOM = CreateObject("PocketOutlook.Application") ' logon - can not use until Logon is called... gobjPOOM.Logon ' get all contacts Set objFolderContacts = gobjPOOM.GetDefaultFolder(olFolderContacts) ' get the items Set objItems = objFolderContacts.Items ' Sort By The FirstName property objItems.Sort "[FirstName]", False ' enumerate thru For Each objContact In objItems MsgBox objContact.FirstName Next In Listing 6.2, a PocketOutlook.Items object is declared as objItems. This objItems holds the Items collection from the folder. This object reference is then populated with the collection by setting it equal to the PocketOutlook.Items collection, objFolderContacts.Items. Then it's sorted by the FirstName property in ascending order. Finally, it's enumerated through and each FirstName value is displayed in a message box. Filtering Items with the Items.Restrict Method You can filter the Items collection to meet certain criteria, such as a ContactItem.LastName starting with a certain letter, an AppointmentItem.Start (datetime) to be within a date range, or a Task.Importance (priority) being one of the enumerated values. The Restrict method on the Items collection will actually return another Items collection (subset) that has been filter by the supplied criteria. The Restrict method takes one string parameter (pwszRestriction) as the criteria by which to filter. As with the Sort method, when specifying the property, you need to enclose it in brackets (for example, [Start], [LastName], or [Importance]). The available operators are =, <, >, >=, <=, and <>. You also can use the keywords AND and OR for multiple criteria. The criteria for filtering can be any of the properties for the object except Recipients and ReminderTime. When specifying the actual criteria, there are some formatting requirements: -
For String Properties, enclose the criteria in quotes: '[LastName] > "Sm"' -
For Date Properties, leave the criteria in date format'[Start]>=8/1/2001'without the eVB date symbol #. -
For Enumeration Properties (for example, TaskItem.Importance, Appointment.BusyStatus), special attention needs to be given to enumeration properties for filtering. Rather than include the enumeration directly or the enumeration as string, the actual integer value needs to be specified. '[Importance] = olImportanceHigh' should actually be specified as '[Importance] = 2'. The Restrict method won't return items that meet the criteria simply because the item has no value for the property. For example, a criteria of '[LastName] <> "Smith"' won't return ContactItems that have a blank ( essentially NULL) LastName value. Listing 6.3 shows an example of filtering contacts with the Restrict method and the LastName value of "Smith". Listing 6.3 Filtering Items Using Restrict Dim objFolderContacts As PocketOutlook.Folder Dim objContact As PocketOutlook.ContactItem Dim objItems As PocketOutlook.Items Dim objRestrictedItems As PocketOutlook.Items ' create the application object Set gobjPOOM = CreateObject("PocketOutlook.Application") ' logon - can not use until Logon is called... gobjPOOM.Logon ' get all contacts Set objFolderContacts = gobjPOOM.GetDefaultFolder(olFolderContacts) ' get the items Set objItems = objFolderContacts.Items ' Find all Contacts with LastName of "Smith" Set objRestrictedItems = objItems.Restrict("[LastName] = ""Smith""") ' enumerate thru For Each objContact In objRestrictedItems MsgBox objContact.FirstName Next Listing 6.3 follows the same structure as previous examples. The new functionality added is the second PocketOutlook.Items object reference, objRestrictedItems. The object objRestrictedItems is used as a secondary Items collection to receive the filtered subset of the contact Items collection and is populated by the Restrict method on the nonfiltered Items collection objItems. The criteria specifies to return a collection of Items that have the value "Smith" for the LastName collection. Then, the filtered Items, objRestrictedItems, is enumerated showing the values for the FirstName property. Using the Items.Find and Items.FindNext Methods The Find and FindNext methods work under the same principle as the Restrict method. The main difference between Find/FindNext is these methods return a singular item (ContactItem, TaskItem, or AppointmentItem) instead of an Items collection. The restriction clause syntax is the same as Restrict, and is passed to the Find method. The Find method returns an object for the first PIM record meeting the criteria. If no item meets the criteria, the object is set to Nothing. If the criteria have been met, each subsequent call to FindNext returns the next object meeting the criteria, until the objects meeting the criteria are exhausted and then Nothing is returned. Listing 6.4 will attempt to find contacts with a CompanyName of "Rubicon Technologies" and enumerate through them. Listing 6.4 Find and FindNext Dim objFolderContacts As PocketOutlook.Folder Dim objContact As PocketOutlook.ContactItem Dim objItems As PocketOutlook.Items ' create the application object Set gobjPOOM = CreateObject("PocketOutlook.Application") ' logon - can not use until Logon is called... gobjPOOM.Logon ' get all contacts Set objFolderContacts = gobjPOOM.GetDefaultFolder(olFolderContacts) ' get the items Set objItems = objFolderContacts.Items ' Find all Contacts with Company Name of "Rubicon Technologies" Set objContact = objItems.Find("[CompanyName] = ""Rubicon Technologies""") ' enumerate thru Do While Not objContact Is Nothing MsgBox objContact.LastName & "," objContact.FirstName Set objContact = objItems.FindNext Loop Again, Listing 6.4 follows the same basic structure as previous examples. The new functionality added is that rather than enumerate directly through all Items or a filtered collection of Items, retrieval of the first object is attempted using the Find method. The criteria used in this example attempts to locate ContactItem objects that have the value Rubicon Technologies for their Company Name property. If a ContactItem meets that criteria, it's returned as a object reference to the variable objContact. If that reference holds a valid ContactItem, the Do While loop is entered and the contact's LastName and FirstName values are displayed in a message box. After display, a subsequent call to FindNext is made. FindNext will continue to look for objects that meet the criteria. An object is returned from the FindNext method until the objects meeting the criteria are exhausted. When exhausted, the object reference objContact will be Nothing and the Do While loop will exit because of the test condition of Not objContact Is Nothing. The PIM Objects: ContactItem, TaskItem, and AppointmentItem Any of the PIM objects behave in similar ways. Each is representative of a single PIM record and has properties that correlate to a particular field in that record. All PIM objects are derived from the Items collection of the PocketOutlook.Folder objectand each is manipulated, displayed, saved, and deleted in similar ways. Several polymorphic methods and properties are associated with these objects. These methods include, but aren't limited to, Copy, Delete, Save, and Display. A common property to each object is OID, the object's unique ID. Listing 6.5 shows an example of the Display method. Listing 6.5 Displaying an Object Dim objFolderContacts As PocketOutlook.Folder Dim objContact As PocketOutlook.ContactItem ' create the application object Set gobjPOOM = CreateObject("PocketOutlook.Application") ' logon - can not use until Logon is called... gobjPOOM.Logon ' get all contacts Set objFolderContacts = gobjPOOM.GetDefaultFolder(olFolderContacts) ' get the first contact Set objContact = objFolderContacts.Items(1) ' display it objContact.Display In Listing 6.5, the same initialization is completed. Then a singular Contact object is retrieved via the Items collection using a hard-coded index value. This contact is then displayed using the Display method. The PocketOutlook.ContactItem Object Each ContactItem is an object representation of a Contact record from the native Contact PIM application. It exposes several properties and methods. Each field in the native application is exposed as a property. Commonly used properties are FirstName, LastName, CompanyName, BusinessTelephone, and Email1Address. The PocketOutlook.AppointmentItem Object The AppointmentItem object is an object representation of an Appointment (Calendar) record from the native Calendar PIM application. Each field is exposed as a property. Commonly used properties are Subject, Start, and Location. A more unique method on the Appointment object is GetRecurrencePattern, which derives a PocketOutlook.RecurrencePattern object. This object is used to inspect and manipulate the recurrence of the appointment. The PocketOutlook.TaskItem Object A TaskItem object represents a Task record from the native Task PIM application. Again, each field in the native application is exposed as a property. Commonly used properties are Subject, DueDate, DateCompleted, and StartDate. The Importance property refers to an enumeration type of PocketOutlook.olImportance, which contains values for Low, Medium, and High priorities. The OID Property As mentioned earlier, each of the PIM record objects, ContactItem, AppointmentItem, and TaskItem have the OID property, a unique ID for the a particular item. It's even unique across item types. In other words, a value for a ContactItem can't be duplicated as an OID value for a TaskItem or AppointmentItem. Persisting the OID property in another datastore isn't recommended because the value can change for an item if a backup and restore is performed on the device. This does present a problem to extend the PIM object model with a secondary datastore such as Pocket Access or SQL Server CE. Although it's not within the scope of this chapter, it would be feasible to create an XML node within the item's Body property and store a second ID within the XML that your application controls. This could be a possible solution with the exception of users manipulating or deleting this information. The Category Property The ContactItem, AppointmentItem, and TaskItem objects all have a Category property. This property contains a comma-delimited list of the categories assigned to the item.  | 
