Contents Tables

A contents table contains information about objects in a MAPI container. Address book providers implement contents tables for each of their containers and message store and remote transport providers implement contents tables for their folders. The contents table of an address book container lists information about its messaging user and distribution list objects while the contents table of a folder lists information about its messages. Contents tables are used primarily by client applications.

There are two types of folder contents tables:

• Standard contents tables contain standard messages — messages that can be transmitted and made visible to a user.
• Associated contents tables contain hidden, non-transmittable information created by a client for a specific purpose, such as to store an alternate representation of a standard message. Associated information is created by passing the MAPI_ASSOCIATED flag to the IMAPIFolder::CreateMessage call.

The contents tables of most address book containers and many folders do not support categorized sorting.

A contents table can be accessed by calling:

• IMAPIContainer::GetContentsTable.

  – Or –

• IMAPIProp::OpenProperty with PR_CONTAINER_CONTENTS or PR_FOLDER_ASSOCIATED_CONTENTS (folders only) specified as the property tag and IID_IMAPITable as the interface identifier.

Message store and address book providers must support both techniques for retrieving table properties. It is unacceptable for providers to support only one way for accessing these tables because clients expect to have the choice.

GetContentsTable accepts as input several flags that specify preferences. When set, the MAPI_ASSOCIATED flag retrieves an associated contents table. Because some folders do not support associated contents, and there is no way for clients to determine this ahead of time, GetContentsTable sometimes returns the error MAPI_E_NO_SUPPORT when an associated contents table is requested.

The MAPI_DEFERRED_ERRORS flag indicates to the implementer of the table that any errors encountered during the call do not need to be reported until some later time.

The call to IMAPIProp::OpenProperty involves accessing a contents table by opening its corresponding property, PR_CONTAINER_CONTENTS for address book contents tables and standard folder contents tables, and PR_FOLDER_ASSOCIATED_CONTENTS for associated contents tables. Although neither or these properties can be retrieved through a folder or container's IMAPIProp::GetProps method, they are included in the property tag array that is returned by the IMAPIProp::GetPropList method.

PR_CONTAINER_CONTENTS can also be used to include or exclude a contents table from a copy operation. If a client specifies PR_CONTAINER_CONTENTS in the lpExcludeProps parameter for IMAPIProp::CopyTo in a copy operation, the new folder or container will not support the contents table of the original folder or container.

Address book container and folder contents tables have a lengthy list of required columns — columns that clients can expect to be available after they retrieve the table from GetContentsTable or OpenProperty. Providers can add to this required set if necessary and clients, through the SetColumns method, can also request modifications.

The required columns for each of the types of contents tables are:

The entry identifier available with each row can either be a short- or long-term entry identifier, depending on the table implementation. Short-term entry identifiers are typically used in situations where performance is an issue. Either type of entry identifier can be used to access the corresponding object.

Contents tables also have a set of columns that are optional but commonly included by service providers in their implementations. These optional columns are:

Message store providers must also include PR_PARENT_DISPLAY for search-result folders contents tables only.

Named properties may be added to the column set of a folder contents table only if all messages in the folder have the same mapping signature, that is, the same mapping of property names to property identifiers. Folder contents tables should support adding message class specific properties to the column set, at least if they support the creation of arbitrary messages in the folder.

Clients can save the default sort order for a folder contents table by calling its IMAPIFolder::SaveContentsSort method. If the RECURSIVE_SORT flag is specified on the call, the sort order can be made to apply to all of the subfolders within the folder.