HOWTO: Access, Restore, Delete Soft Deleted Item Exchange Server

ID: Q232265

The information in this article applies to:

Extended Messaging Application Programming Interface (MAPI), version 1.0

SUMMARY

On a Microsoft Exchange server, when a message or a folder is deleted from a Public or Deleted Items Folder, a backup copy of that item is kept for a defined period of time. This period of time is known as deleted item retention time (The backup item will be referred to as a Soft Deleted Item or a Tombstone). Outlook allows you to get a list of the Soft Deleted messages in a folder and to either restore the messages back to the original folders or permanently remove the messages from the system. This article shows you how to use Extended MAPI with the SHOW_SOFT_DELETES and DELETE_HARD_DELETE flags, to programatically access, restore, and permanently delete these Soft Deleted Items.

MORE INFORMATION

The same Extended MAPI commands that are used with regular items (messages and folders) are used with Soft Deleted Items. In order to access these Soft Deleted Items, you must use the SHOW_SOFT_DELETES flag defined in the following. Here are a list of options that one can perform on the Soft Deleted Items.

In order to get a list of Soft Deleted Folders in a folder, call the GetHierarchyTable command with the SHOW_SOFT_DELETES flag. Use the following as an example:
```
   hr = lpIPMTestFold->GetHierarchyTable(SHOW_SOFT_DELETES,&lpPubFoldTable); 
```

In order to get a list of Soft Deleted Messages in a folder, call the GetContentsTable command with the SHOW_SOFT_DELETES flag. Use the following code an example:
```
   hr = lpIPMTestFold->GetContentsTable(SHOW_SOFT_DELETES,&lpPubFoldContents); 
```

In order to open a Soft Deleted Message or Folder, call the OpenEntry command with the SHOW_SOFT_DELETES flag. Use the following as an example:


   hr = lpSession->OpenEntry(lpRows->aRow[0].lpProps[2].Value.bin.cb,
               (LPENTRYID)lpRows->aRow[0].lpProps[2].Value.bin.lpb,
                          NULL,
                          SHOW_SOFT_DELETES | MAPI_BEST_ACCESS,
                          &ulObjType, 
         (LPUNKNOWN FAR *)&lpIPMTestMessage);

If you need to restore a Soft Deleted Item, call the CopyMessages or CopyFolder command on the EntryID of the Soft Deleted Item to recreate it in a folder. Use the following as an example:


   hr = lpIPMRestoreFold->CopyMessages(&sbaEIDSoftDeletedList, 
                                    NULL,
                                    lpIPMRestoreFold,
                                    NULL,
                                    NULL,
                                    NULL);

To permanently remove items, Soft Deleted or not, one must use the DELETE_HARD_DELETE flag defined below. However, once an item has been permanently deleted, the item can NOT be restored on the Exchange Server. The following steps show two ways in which to implement the DELETE_HARD_DELETE flag.

In order to Hard Delete the messages in a folder, call the DeleteMessages command passing in the DELETE_HARD_DELETE flag. Use the following as an example:


   hr = lpIPMTestFold->DeleteMessages(&sbaEIDList,
                                   NULL,
                                   NULL,
                                   DELETE_HARD_DELETE);

In order to Hard Delete a folder, call the DeleteFolder command passing in the DELETE_HARD_DELETE flag. Use the following as an example:


   hr = lpIPMPubFold->DeleteFolder(lpspvTestFoldEID->Value.bin.cb,
                     (LPENTRYID)lpspvTestFoldEID->Value.bin.lpb,
                                NULL,
                                NULL,
                                DELETE_HARD_DELETE | DEL_FOLDERS | DEL_MESSAGES);

NOTES:

The deleted item retention time is zero by default, and it can be specified in the General tab of Private or Public Information Store Properties page from Exchange Administration program. It can also be set for individual recipients or public folders (the Information Store settings by default).

The SHOW_SOFT_DELETES flag is defined as follows:


   #define SHOW_SOFT_DELETES		((ULONG) 0x00000002)

The DELTETE_HARD_DELETE flag is defined as follows:


   #define DELETE_HARD_DELETE		((ULONG) 0x00000010)

Additional query words: Tombstones Soft Delete Hard DELETE_HARD_DELETE SHOW_SOFT_DELETES kbMAPI kbGrpMsg kbMsg kbDSupport


Keywords          : kbMAPI kbMsg kbGrpMsg kbDSupport 
Version           : WINDOWS:1.0
Platform          : WINDOWS 
Issue type        : kbhowto

Last Reviewed: July 13, 1999