IPOlItems::SetColumns

This method is not supported in Windows CE Platform Builder 3.0.

This method applies only to collections of contacts. It enables you to retrieve contacts quicker by specifying only the properties you want to retrieve. When you retrieve a contact the specified properties will be set to their current values, and all other properties will be set to NULL.

HRESULT SetColumns( BSTR Columns );

Parameters

• Columns
  Columns you want to retrieve. For example, to retrieve FileAs and BusinessTelephoneNumber, you would use the string "FileAs,BusinessTelephoneNumber" for Columns.

Return Values

S_OK indicates that the string was parsed correctly. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use this method when you want to examine one or two fields in a lot of contacts very quickly. For example, to look iteratively at the FileAs and BusinessTelephoneNumber properties of all Contacts, you can first call SetColumns as follows:

pContacts->SetColumns("FileAs, BusinessTelephoneNumber")

Then when you use the IPOutlookItemCollection interface method Item to get a contact, it will have only these two properties set.

The tradeoff for the enhanced performance is that you cannot modify the contacts found with the columns set. Therefore use SetColumns when you need to examine or use specified properties of all or many contacts in a collection, but you need to modify relatively few or none of the contacts.

To modify a contact, you can use the IPOutlookApp interface method GetItemFromOid to get the contact and modify it. (Oid and Application are special properties still available after you call SetColumns.) Alternatively, you can use a second Contact Items collection pointer that has not had SetColumns called on it, and use the Item method on it to get the Contact and modify it.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	pimstore.h

See Also

IPOlItems::Unknown, IPOutlookItemCollection::Unknown

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.