Restricting Pim Item Collections

This applies equally to WindowsMobile In The Hand and the Windows Mobile 5.0 APIs. On the collection classes there exists a Restrict method which returns a subset of the collection matching your search query. You can use the resulting collection to databind or otherwise enumerate over.

The query language used is similar, but not the same, as SQL: if you imagine that what you are entering here is just the WHERE clause of a query you will not be far off. The key rules to follow are:-

• Field names must match exactly – refer to the Properties of the Appointment, Contact and Task class for valid field names
  
• Field names must be enclosed in square brackets e.g. [MobileTelephoneNumber]
  
• You can combine multiple expressions with AND and OR
  
• Supported operators are < (Less Than), <= (Less Than or Equal To), > (Greater Than), >= Greater Than or Equal To), = (Equals), <> (Not Equals)
  
• Items without the property set will not be returned in a query. So if you set a query of [BusinessAddressCity] = “London” it would not return items without the business address city present even though these are not London.
  
• You can use this knowledge to form a query to return all records where the property is set with [PropertyName] <> “” as all items with the property set will match this pattern.

You can return a full contact list for all items with a mobile number using this code:-

os = new OutlookSession();

PimItemCollection pic = os.Contacts.Items.Restrict(“[MobileTelephoneNumber] <> “””);

listBox1.DataSource = pic;

listBox1.DisplayMember = “FileAs”

This example bind the collection to a control, the list will show the contact name only but you’ll be able to retrieve the Contact object from the SelectedItem property of the list box to use it’s other properties (e.g. the mobile number).

For Windows Mobile 5.0 you can use the new ChooseContactDialog which features a RequiredProperties property so you can easily setup the dialog to show only relevant items.

Update: Here is the VB equivalent:-

os = New OutlookSession
Dim pic As PimItemCollection = os.Contacts.Items.Restrict(“[MobileTelephoneNumber] <> “ & Chr(34) & Chr(34))
ListBox1.DataSource = pic
ListBox1.DisplayMember = “FileAs”