Writing a Remote Viewer

A remote viewer is a window in a client application that provides controlled access to messages stored on another computer. This controlled access might be with a modem or other type of slow link. Rather than retrieve a complete selection of available messages every time a user opens a folder, the remote viewer first displays only the headers. The user then selects from the headers which of the messages to display in full. Remote viewer clients can allow their users to delete messages before they are ever downloaded.

    To retrieve the headers of messages stored remotely
  1. Call IMAPISession::GetStatusTable to access the status table.
  2. Call IMAPITable::Restrict to limit the status table to only those rows that have their PR_RESOURCE_TYPE column set to MAPI_TRANSPORT_PROVIDER.
  3. Call IMAPITable::SetColumns to include the following columns in the status table: PR_ENTRYID, PR_RESOURCE_METHODS, PR_RESOURCE_TYPE, PR_PROVIDER_DISPLAY, and PR_STATUS_CODE.
  4. Call HrQueryAllRows to retrieve all the rows in the status table.
  5. Pass the entry identifier for each row in the table in a call to IMAPISession::OpenEntry. Because this interface is marshaled from the MAPI spooler's process context to the client's process context — unlike interfaces typically obtained from address book or message store providers — issues concerning multithreading are of more importance.
  6. Call the status object's IUnknown::QueryInterface method, passing IID_IMAPIFolder as the interface identifier, to retrieve the remote folder.

    The remote folder is not a complete folder implementation; it supports only a subset of folder methods and properties. One of the required methods, IMAPIProp::GetProps, supports the retrieval of the following properties:

PR_ACCESS PR_ACCESS_LEVEL
PR_CONTENT_COUNT PR_ASSOC_CONTENT_COUNT
PR_FOLDER_TYPE PR_OBJECT_TYPE
PR_SUBFOLDERS PR_CREATION_VERSION
PR_CREATION_TIME PR_DISPLAY_NAME
PR_DISPLAY_TYPE

Remote folders must also support the IMAPIProp::GetPropList, IMAPIContainer::GetContentsTable, and IMAPIFolder::SetMessageStatus methods. Remote folder contents tables typically support the following columns:

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

  1. Call the transport provider's IMAPIStatus::ValidateState method the first time that one of the transfer options is picked. Either the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE process flag should be set as well as the SHOW_XP_SSESSION_UI flag to allow the user interface to be shown.

Note To mark a particular message header for downloading or deletion, a client calls IMAPIFolder::SetMessageStatus and sets either the MSGSTATUS_REMOTE_DOWNLOAD or MSGSTATUS_REMOTE_DELETE flag.