IMAPIContainer::GetContentsTable

The IMAPIContainer::GetContentsTable method returns a pointer to the container's contents table.

Quick Info

HRESULT GetContentsTable(
  ULONG ulFlags,              
  LPMAPITABLE FAR * lppTable  
);

Parameters

ulFlags

[in] Bitmask of flags that controls how the contents table is returned. The following flags can be set:

MAPI_ASSOCIATED: The container's associated contents table should be returned rather than the standard contents table. This flag is used only with folders. The messages that are included in the associated contents table were created with the MAPI_ASSOCIATED flag set in the call to IMAPIFolder::CreateMessage. Clients typically use the associated contents table to retrieve forms and views.
MAPI_DEFERRED_ERRORS: GetContentsTable can return successfully, possibly before the table is made accessible to the caller. If the table is not accessible, making a subsequent table call can result in an error.
MAPI_UNICODE: Requests that the columns containing string data be returned in the Unicode format. If the MAPI_UNICODE flag is not set, the strings should be returned in the ANSI format.

lppTable

[out] Pointer to a pointer to the contents table.

Return Values

S_OK: The contents table was successfully retrieved.
MAPI_E_BAD_CHARWIDTH: Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
MAPI_E_NO_SUPPORT: The container has no contents and cannot provide a contents table.

Remarks

The IMAPIContainer::GetContentsTable method returns a pointer to the contents table of a container. A contents table contains summary information about objects within the container.

Contents tables have lengthy column sets. For a complete list of the required and optional columns in contents tables, see Contents Tables.

It is possible for some containers to have no contents. These containers return MAPI_E_NO_SUPPORT from their implementations of GetContentsTable.

Notes to Implementers

If you support a contents table for your container, you must also:

Support calls to the container's IMAPIProp::OpenProperty method to open the PR_CONTAINER_CONTENTS property.
Return PR_CONTAINER_CONTENTS in response to a call to the container's IMAPIProp::GetProps and IMAPIProp::GetPropList methods.

A remote transport provider's implementation of this method must return a pointer to an IMAPITable interface in the ppTable parameter passed into the GetContentsTable method. If your transport provider has an existing contents table, it suffices to return a pointer to it. If not, then this method must create a new IMAPITable object, populate the table with message headers (if any are available), and return a pointer to the new table. The ITableData method HrGetView is useful for generating a return value and storing the table pointer in the ppTable parameter. The contents table must support at least the following property columns:

PR_ENTRYID	PR_SENDER_NAME
PR_SENT_REPRESENTING_NAME	PR_DISPLAY_TO
PR_SUBJECT	PR_MESSAGE_CLASS
PR_MESSAGE_FLAGS	PR_MESSAGE_SIZE
PR_PRIORITY	PR_IMPORTANCE
PR_SENSITIVITY	PR_MESSAGE_DELIVERY_TIME
PR_MSG_STATUS	PR_MESSAGE_DOWNLOAD_TIME
PR_HASATTACH	PR_OBJECT_TYPE
PR_INSTANCE_KEY	PR_NORMALIZED_SUBJECT

Notes to Callers

String and binary contents table columns can be truncated. Typically, providers return 255 characters. Because you cannot know ahead of time whether or not a table includes truncated columns, assume that a column is truncated if the length of the column is either 255 or 510 bytes. You can always retrieve the full value of a truncated column if necessary from the object directly by using its entry identifier to open it and then calling the IMAPIProp::GetProps method.

Depending on the provider's implementation, restrictions and sorting operations can apply to an entire string or to the truncated version of that string.