Contents Tables

Applies to: Office 2010 | Outlook 2010 | Visual Studio

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:

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:

Required column

Type of contents table

PR_ADDRTYPE (PidTagAddressType)

Address book container tables

PR_DISPLAY_NAME (PidTagDisplayName)

Address book container tables

PR_DISPLAY_CC (PidTagDisplayCc)

Message store folder tables

PR_DISPLAY_TO (PidTagDisplayTo)

All folder contents tables

PR_DISPLAY_TYPE (PidTagDisplayType)

Address book container tables

PR_ENTRYID (PidTagEntryId)

All contents tables

PR_HASATTACH (PidTagHasAttachments)

All folder contents tables

PR_INSTANCE_KEY (PidTagInstanceKey)

All contents tables

PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime)

Message store folder tables

PR_MAPPING_SIGNATURE (PidTagMappingSignature)

Message store folder tables

PR_MESSAGE_CLASS (PidTagMessageClass)

All folder contents tables

PR_MESSAGE_DOWNLOAD_TIME (PidTagMessageDownloadTime)

Remote transport folder tables

PR_MESSAGE_FLAGS (PidTagMessageFlags)

All folder contents tables

PR_MESSAGE_SIZE (PidTagMessageSize)

All folder contents tables

PR_MSG_STATUS (PidTagMessageStatus)

All folder contents tables

PR_OBJECT_TYPE (PidTagObjectType)

All contents tables

PR_PARENT_ENTRYID (PidTagParentEntryId)

Message store folder tables

PR_RECORD_KEY (PidTagRecordKey)

Address book container and message store folder tables

PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName)

Remote transport folder tables

PR_STORE_ENTRYID (PidTagStoreEntryId)

Message store folder tables

PR_STORE_RECORD_KEY (PidTagStoreRecordKey)

Message store folder tables

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:

Optional column

Type of contents table

PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime)

Message store folder tables

PR_CONTENT_COUNT (PidTagContentCount)

Standard folder contents tables

PR_CONTENT_UNREAD (PidTagContentUnreadCount)

Standard folder contents tables

PR_CONVERSATION_INDEX (PidTagConversationIndex)

Message store folder tables

PR_EMAIL_ADDRESS (PidTagEmailAddress)

Address book container tables

PR_IMPORTANCE (PidTagImportance)

All folder contents tables

PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime)

All folder contents tables

PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject)

All folder contents tables

PR_PRIORITY (PidTagPriority)

All folder contents tables

PR_SEARCH_KEY (PidTagSearchKey)

Address book container tables

PR_SEND_RICH_INFO (PidTagSendRichInfo)

Address book container tables

PR_SENDER_NAME (PidTagSenderName)

All folder contents tables

PR_SENSITIVITY (PidTagSensitivity)

All folder contents tables

PR_SUBJECT (PidTagSubject)

All folder contents tables

PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)

Address book container tables

Message store providers must also include PR_PARENT_DISPLAY (PidTagParentDisplay) 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, 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.

See Also

Concepts

MAPI Tables