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
Comments (5)

  1. gosaca says:

    Form One-offs are a major headache and in practice appears to rarely be the desired behavior – is there some major technical roadblock from allowing developers to completely short-curcuit the creation of one-offs?  

    It would be interesting to be enlightened as to the details of the original decision to add the current form one-off behavior and why it persists to this day.

  2. Jeff says:

    Hello. I’m new to the Outlook programming and I have headaches on the one-off forms. If I were to reopen the previously saved item, the item becomes one-off, am I right? Can you teach me what I have to do if I need to run the code on the previously saved item? I have done everything done almost everything that prevents the item to go one-off but still can’t work. My email is natur3_dr3am3rz@hotmail.com Thanks in advance.

  3. waltwa says:

    Gosaca – I can’t speak for the original designers of the Outlook form features, but my understanding is that the initial design was based on the assumption that when a developer made a change to the form definition they wanted that change to stick -for example adding a new user-defined field to the item and being able to reference that field later. Back in the Outlook 97/98/2000 days one-offs weren’t as big of a headache because users would still be prompted to run the VBScript code in a one-off item (via the Enable/Disable Macro dialog). Although one-offs still weren’t very desirable by most form developers, some intentionally designed one-off forms with the assumption that users would be able to click Enable on the Enable/Disable macro button. This was fairly common with form solutions distributed in the .oft (Outlook Template) file format. Since the Outlook Object Model Security features released around the Outlook 2000 SR1 timeframe security has been improved, but one-off forms have been less and less useful due to the default blocking VBScript and non-default ActiveX controls. Now, one-offs are pretty much a headache for most form developers. There is always risk in trying to make a significant change to the architecture of a developer feature especially when developers have depended on it working a specific way for several years. It is not easy to predict all of the consequences of making a change. The good news is that most of the time one-off behavior can be avoided, and going forward the new Outlook 2007 Form Regions feature provides a more robust solution, especially if multiple developers from other companies need to customize the same item. I hope this helps add some perspective.

  4. Here are some suggestions to help identify and eliminate the cause of one-off behavior when working with

  5. Glenn says:

    I have a problem where all my recuring tasks no longer function. I dabled with a custom form and used it for a while instead of tasks. I then decided I didn’t like it so reset msgclass back to default task form. however all my tasks still look like the original form. (i.e. I must have saved the definition). Now I can’t undo anything. My standard tasks still work but the recurring ones no longer allow me to make changes or complete etc. I am not a programmer so have no idea how to apply what you have raised in this blog. Someone please develop a generic tool to help us non programmers recover our system.

Skip to main content