New Outlook Documentation Part 5 - One-Off Forms
[This is now documented here: https://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:
https://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
Anonymous
March 07, 2006
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.Anonymous
June 14, 2007
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.Anonymous
June 18, 2007
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.Anonymous
June 18, 2007
Here are some suggestions to help identify and eliminate the cause of one-off behavior when working withAnonymous
December 02, 2009
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.