New Outlook Documentation Part 5 - One-Off Forms

[This is now documented here: http://msdn2.microsoft.com/en-us/library/bb820932.aspx]

This should help dealing with scenarios in Outlook that cause forms to become one-offed.

Topic
How to remove one-off form attributes from a message which has unexpectedly been “one-offed”.

One-Off Forms
A message which has been “one-offed” is one where a custom form definition has been saved with the message. While there are legitimate scenarios for one-offing a form, typically this happens unexpectedly. The negative side effects and descriptions of how messages can become one-offed are discussed in the following Knowledge Base article:
http://support.microsoft.com/kb/207896

Removing One-Off  Properties
A message which has been marked as a one-off can be restored to a regular message by deleting a set of named properties and removing some flags from another named property. This process can be done with Extended MAPI or CDO. The properties which must be deleted are all in the PSETID_Common namespace and are dispidFormStorage, dispidPageDirStream, dispidFormPropStream, and dispidScriptStream. The property which must be modified is also in the PSETID_Common namespace. The flags INSP_ONEOFFFLAGS must be removed from dispidCustomFlag.

In addition, the property dispidPropDefStream in the PSETID_Common namespace may also be removed. If this property is removed, then the flag INSP_PROPDEFINITION should be removed from dispidCustomFlag. A side effect of removing this property is that the Outlook Object Model and the Outlook User Interface will no longer be able to access user properties which have been set on the item. These properties and their values will still be accessible through MAPI. Note that if this property is not removed and the items is one-offed again, it is possible that the property can be overwritten with new data.

Definitions

#define dispidFormStorage    0x850F
#define dispidPageDirStream  0x8513
#define dispidFormPropStream 0x851B
#define dispidPropDefStream  0x8540
#define dispidScriptStream   0x8541
#define dispidCustomFlag     0x8542

#define INSP_ONEOFFFLAGS     0xD000000
#define INSP_PROPDEFINITION  0x2000000

DEFINE_OLEGUID(PSETID_Common, MAKELONG(0x2000+(8),0x0006),0,0);

Usage
The following sample code illustrates how to remove one-off attributes from a message using Extended MAPI:

ULONG aulOneOffIDs[] = {dispidFormStorage, 
dispidPageDirStream,
dispidFormPropStream,
dispidScriptStream,
dispidPropDefStream, // dispidPropDefStream must remain next to last in list
dispidCustomFlag}; // dispidCustomFlag must remain last in list

#define ulNumOneOffIDs (sizeof(aulOneOffIDs)/sizeof(aulOneOffIDs[0]))

HRESULT RemoveOneOff(LPMESSAGE lpMessage, BOOL bRemovePropDef)
{
  if (!lpMessage) return MAPI_E_INVALID_PARAMETER;

  HRESULT hRes = S_OK;
  MAPINAMEID  rgnmid[ulNumOneOffIDs];
  LPMAPINAMEID rgpnmid[ulNumOneOffIDs];
  LPSPropTagArray lpTags = NULL;

  ULONG i = 0;
  for (i = 0 ; i < ulNumOneOffIDs ; i++)
  {
    rgnmid[i].lpguid = (LPGUID)&PSETID_Common;
    rgnmid[i].ulKind = MNID_ID;
    rgnmid[i].Kind.lID = aulOneOffIDs[i];
    rgpnmid[i] = &rgnmid[i];
  }
  
  hRes = lpMessage->GetIDsFromNames(
    ulNumOneOffIDs,
    rgpnmid,
    0,
    &lpTags);
  if (lpTags)
  {
    // The last prop is the flag value 
    // we'll be updating, don't count it
    lpTags->cValues = ulNumOneOffIDs-1;

    // If we're not removing the prop def stream don't count it
    if (!bRemovePropDef)
    {
      lpTags->cValues = lpTags->cValues-1;
    }

    hRes = lpMessage->DeleteProps(
      lpTags,
      0);
    if (SUCCEEDED(hRes))
    {
      SPropTagArray  pTag = {0};
      ULONG      cProp = 0;
      LPSPropValue  lpCustomFlag = NULL;

      // Grab dispidCustomFlag, the last tag in the array
      pTag.cValues = 1;
      pTag.aulPropTag[0] = CHANGE_PROP_TYPE(
        lpTags->aulPropTag[ulNumOneOffIDs-1],
        PT_LONG);

      hRes = lpMessage->GetProps(
        &pTag,
        fMapiUnicode,
        &cProp,
        &lpCustomFlag);
      if (SUCCEEDED(hRes) && 
        1 == cProp && lpCustomFlag && 
        PT_LONG == PROP_TYPE(lpCustomFlag->ulPropTag))
      {
        // Clear the INSP_ONEOFFFLAGS bits so OL 
        // doesn't look for the props we deleted
        lpCustomFlag->Value.l = 
          lpCustomFlag->Value.l&~(INSP_ONEOFFFLAGS);
        if (bRemovePropDef)
        {
          lpCustomFlag->Value.l = 
           lpCustomFlag->Value.l&~(INSP_PROPDEFINITION);
        }
        hRes = lpMessage->SetProps(
          1,
          lpCustomFlag,
          NULL);
      }

      hRes = lpMessage->SaveChanges(KEEP_OPEN_READWRITE);
    }
  }
  MAPIFreeBuffer(lpTags);

  return hRes;
}

The following sample code illustrates how to remove one-off attributes from a message using CDO 1.21:

Sub DeleteFormDefinitionWithCDO(MessageEID As String, bDeletePropDef As Boolean)
  Const strPSetCommonGUID = "0820060000000000C000000000000046" ' PSETID_Common

  Dim objSession As MAPI.Session
  Dim oFolderCDO As MAPI.Folder
  Dim oMessages As MAPI.Messages
  Dim oMessage As MAPI.Message
  Dim myFields As MAPI.Fields

  Set objSession = New MAPI.Session
  objSession.Logon , , True, False
  Set oMessage = objSession.GetMessage(MessageEID)
  Set myFields = oMessage.Fields
  On Error Resume Next
  myFields.Item("{" & strPSetCommonGUID & "}0x850F").Delete ' dispidFormStorage
  myFields.Item("{" & strPSetCommonGUID & "}0x8513").Delete ' dispidPageDirStream
  myFields.Item("{" & strPSetCommonGUID & "}0x851B").Delete ' dispidFormPropStream
  myFields.Item("{" & strPSetCommonGUID & "}0x8541").Delete ' dispidScriptStream
  ' Update dispidCustomFlag
  myFields.Item("{" & strPSetCommonGUID & "}0x8542") = _
    myFields.Item("{" & strPSetCommonGUID & "}0x8542") And Not &HD000000 ' INSP_ONEOFFFLAGS

  If bDeletePropDef Then
    myFields.Item("{" & strPSetCommonGUID & "}0x8540").Delete ' dispidPropDefStream
    myFields.Item("{" & strPSetCommonGUID & "}0x8542") = _
      myFields.Item("{" & strPSetCommonGUID & "}0x8542") And Not &H2000000 ' INSP_PROPDEFINITION
  End If

  oMessage.Update
  objSession.Logoff
  Set objSession = Nothing
End Sub