Outlook Data Collections

In Pocket Outlook, the IPOutlookItemCollection object is used to represent all of the contacts, tasks, and appointments in a folder. Once you have the pointer to a collection object, you can use it to add or delete items, find an individual object, and filter Outlook items based on their content.

Table 10.7 describes the methods supported by the IPOutlookItemCollection interface.

Table 10.7. IPOutlookItemCollection Methods

Method	Description
Add()	Creates a new item in the collection
Find()	Finds the first item in the collection that matches the search criteria
FindNext()	Finds the next item in the collection that matches the search criteria
Item()	Gets a specified item in the collection
Remove()	Deletes an item from the collection
Restrict()	Creates a new collection based on search criteria
Sort()	Sorts the items in the collection

Table 10.8 describes the properties supported by the IPOutlookItemCollection interface.

Table 10.8. IPOutlookItemCollection Properties

Property	Get/Put	Description
Application	Get	Returns a pointer to the IPOutlookApp interface
Count	Get	Gets the number of items in the collection
IncludeRecurrences	Get/put	Indicates whether recurrences should be included in the collection

To get the pointer for an IPOutlookItemCollection object that represents the contents of an individual folder, you can use the IFolder::get_Items() function. Once you have the pointer to a valid collection interface for a particular Outlook folder, getting an item is as simple as calling the IPOutlookItemCollection::Item() method, which is defined as follows:

 HRESULT IPOutlookItemCollection::Item(int iIndex,   IDispatch **ppolItem); 

The first parameter is the index (which starts at one) of the item from the collection that you are interested in looking at. The second parameter, ppolItem, is a pointer to a pointer that will be filled in with the appropriate Outlook Item, as shown in the following example:

 // Get the calendar items IPOutlookItemCollection *pICalItems = NULL; hr = pIFolder->get_Items(&pICalItems); if(FAILED(hr)) {    pIFolder->Release();    return FALSE; } // Get an item IAppointment *pICalEntry = NULL; hr = pICalItems->Item(1, (IDispatch **)&pICalEntry); if(SUCCEEDED(hr)) {    // Do something with it   // Clean up   if(pICalEntry)      pICalEntry->Release(); } // Clean up if(pICalItems)    pICalItems->Release(); 

Adding and Deleting Folder Items

To create a new item in an Outlook collection for a particular folder, you can call the IPOutlookItemCollection::Add() method:

 HRESULT IPOutlookItemCollection::Add(IDispatch **ppolItem); 

The only parameter the method needs is a pointer to a pointer for the new object that you wish to add to the collection. If you attempt to add an invalid object type for the folder (for example, if you attempt to add a task to the Contacts folder) an error will be returned. When adding a new Outlook item, you must also remember to call the ::Save() method of the object you are adding in order for it to be saved in the object store. If you do not, the new item will exist only in memory and will be destroyed when the collection is destroyed.

The following example shows how to create a new Contact item and add it to the Contact collection:

 // Folder IFolder *pIFolder = NULL; hr = pOlApp->GetDefaultFolder(olFolderContacts, &pIFolder); if(FAILED(hr)) {    OutputDebugString(TEXT("Could not get the contacts        folder"));    return FALSE; } // Add a new contact IPOutlookItemCollection *pIContactItems = NULL; hr = pIFolder->get_Items(&pIContactItems); if(FAILED(hr)) {    pIFolder->Release();    return FALSE; } // Get an item IContact *pNewContact = NULL; hr = pIContactItems->Add((IDispatch **)&pNewContact); if(FAILED(hr))    return FALSE; // Configure the contact pNewContact->put_FirstName(TEXT("Randy")); pNewContact->put_LastName(TEXT("Rants")); pNewContact->put_WebPage(TEXT("http://www.randyrants.com")); // Save it hr = pNewContact->Save(); if(FAILED(hr)) {    pNewContact->Release();    return FALSE; } if(pNewContact)    pNewContact->Release(); 

To remove an item from the collection, you call the IPOutlookItemCollection::Remove() method, which requires only the index of the object to remove. The index is based on the current sort order of the collection. The function is defined as follows:

 HRESULT IPOutlookItemCollection::Remove(int iIndex); 

Sorting Items

You can sort the data in a collection using the following function:

 HRESULT IPOutlookItemCollection::Sort(BSTR pwszProperty,    VARIANT_BOOL fDescending); 

The first parameter is the property that you want to sort the collection of items on. This can be any property that the items contained in the collection support, except for the Categories, BodyInk, ReminderTime, or Recipients properties. You must also remember to enclose the property string you are using in brackets (i.e., [ ]).The next property determines the sort order, which should be set to TRUE for descending, or FALSE for ascending.

For example, the following code sorts a collection of contacts by first name:

 IPOutlookItemCollection *pIContactItems = NULL; hr = pIFolder->get_Items(&pIContactItems); if(FAILED(hr)) {    pIFolder->Release();    return FALSE; } // Sort by first name hr = pIContactItems->Sort(TEXT("[FirstName]"), TRUE); if(FAILED(hr)) {    pIContactItems->Release();    pIFolder->Release();    return FALSE; } 

Finding and Filtering Outlook Items

There are two different ways to find items (or an individual item) located within an Outlook collection:

1. The IPOutlookItemCollection::Find() and IPOutlookItemCollection::FindNext() methods can be used to enumerate items that match a search string in an existing collection.

2. The IPOutlookItemCollection::Restrict() method can be used to create a new collection object based on your search criteria.

Regardless of which method you use to find items within a collection, both require you to specify a restriction string. A restriction string is a Boolean expression that returns either TRUE or FALSE for a particular item. The IPOutlookItemCollection::Find(), IPOutlookItemCollection::FindNext(), and IPOutlookItemCollection::Restrict() methods return only those items that evaluate to TRUE.

Remember a few things about restriction strings:

• Property names should be enclosed in brackets.

• Expressions can be combined using AND or OR.

• Restrictions cannot be made on the BodyInk, ReminderTime, and Recipients properties.

• Comparisons can be made using the <, <=, >, >=, =, or < > operators.

For example, the following restriction string would return only those contacts that have Kirk as the first name:

 [FirstName] = "Kirk" 

To enumerate through the items in the current collection for a particular restriction string, you can use the following method:

 HRESULT IPOutlookItemCollection::Find(BSTR pwszRestriction,    IDispatch **ppItem); 

The first parameter, pwszRestriction, should be the string you want to use to find the items that match, and ppItem points to a pointer to the first item found by the function. If ppItem is NULL, then no matches were found.

To find the next item that matches the restriction, you use the IPOutlookItemCollection::FindNext() method:

 HRESULT IPOutlookItemCollection::FindNext(IDispatch   **ppItem); 

The method takes a single parameter, which is a pointer to a pointer for the next item that matches the restriction pattern. You can keep calling the IPOutlookItemCollection::FindNext() method until ppItem returns NULL, which indicates that no more items match.

The following code shows how you can enumerate a list of contacts located in the state of Washington:

 // Find contacts IPOutlookItemCollection *pIContactItems = NULL; hr = pIFolder->get_Items(&pIContactItems); if(FAILED(hr)) {    pIFolder->Release();    return FALSE; } IContact *pContact = NULL; hr = pIContactItems->Find(TEXT("[HomeAddressState] =   \"WA\""), (IDispatch **)&pContact); if(FAILED(hr)) {    OutputDebugString(TEXT("No entries found"));    return FALSE; } // Walk though the entries while(pContact != NULL) {    // Do something with the contact    BSTR bstrFirstName = NULL, bstrLastName = NULL;    pContact->get_FirstName(&bstrFirstName);    pContact->get_LastName(&bstrLastName);    TCHAR tchName[64] = TEXT("\0");    wsprintf(tchName, TEXT("%s %s"), bstrFirstName,        bstrLastName);    MessageBox(NULL, tchName, TEXT("Contacts"), MB_OK);    // Clean up    if(bstrFirstName)       SysFreeString(bstrFirstName);    if(bstrLastName)       SysFreeString(bstrLastName);    pContact->Release();    // Get the next one    hr = pIContactItems->FindNext((IDispatch **)&pContact);    if(FAILED(hr))       break; }; 

When you have a large number of results that match a restriction string, it is sometimes easier to just create a new IPOutlookItemCollection interface based on the restriction string. You can do so by using the following method:

 HRESULT IPOutlookItemCollection::Restrict(BSTR   pwszRestriction, IPOutlookItemCollection **ppolItems); 

The first parameter is the restriction string you want to use to evaluate items for your new collection. The ppolItems parameter points to a pointer that will receive the new collection interface pointer.

The IPOlItems Interface

When working with the Contacts folder, you can use an additional interface to speed up the generation of a collection of Contact items. By using the IPOlItems interface, you can specify a list of the properties that you are interested in, rather then retrieving all of them (there are 55+ properties for a Contact item). This can be extremely useful when you want to examine a few fields in a large number of contacts quickly.

Note that when you use the IPOlItems interface to specify the columns to be returned for the objects, all of the other item's properties will be automatically set to NULL. Therefore, when you use the IPOutlookItemCollection::Item() method to get a particular item, it will have only the properties that you specified set. This being the case, you cannot modify contacts that were found with the IPOlItems interface.

Table 10.9 describes the method supported by the IPOlItems interface.

Table 10.9. IPOlItems Method

Method	Description
SetColumns()	Limits the columns that are returned, to enhance performance

To specify the columns that are to be returned in a Contact's item collection list, you can use the IPOlItems::SetColumns() method:

 HRESULT IPOlItems::SetColumns(BSTR Columns); 

The only parameter that the method takes is a string that specifies the columns to be returned. Each column name should be separated by a comma.

The following example shows how you can get a list of contacts containing only the Company Name, First Name, and Last Name columns:

 IPOutlookItemCollection *pIContactItems = NULL; hr = pIFolder->get_Items(&pIContactItems); if(FAILED(hr)) {    pIFolder->Release();    return FALSE; } IPOlItems *pFastContacts = NULL; hr = pIContactItems->QueryInterface(IID_IPOlItems,   (LPVOID *)&pFastContacts); if(FAILED(hr)) {    pIContactItems->Release();    pIFolder->Release();    return FALSE; } hr = pFastContacts->SetColumns(TEXT("CompanyName, FirstName,   LastName")); if(FAILED(hr)) {    pFastContacts->Release();    pIContactItems->Release();    pIFolder->Release();    return FALSE; } // The contacts now only have the Company Name, First Name, // and Last Name // Do something that's read-only... // Cleanup below... if(pFastContacts)    pFastContacts->Release(); 

Because the IPOutlookItemCollection interface returned with IPOlItems is considered read-only, you can get access to the full item by using the IPOutlookApp::GetItemFromOid() method.