FieldDefinition Stream Structure
Applies to: Office 2010 | Outlook 2010 | Visual Studio
A FieldDefinition stream structure contains either the field definition of a user-defined field, or a set of data-binding settings for a built-in field.
You can programmatically manipulate a FieldDefinition stream structure if the structure contains the field definition of a user-defined field. You should not attempt to programmatically create or modify a FieldDefinition structure if the structure contains settings for a built-in field. You should use the Microsoft Outlook Forms Designer to maintain such settings for built-in fields.
Note
Outlook supports two formats of field definitions: PropDefV1 and PropDefV2. The PropDefV1 format of field definitions contains the following data elements: Flags, VT, DispId, NmidNameLength, NmidName, NameANSI, FormulaANSI, ValidationRuleANSI, ValidationTextANSI, and ErrorANSI. The PropDefV2 format contains the same elements and the InternalType and SkipBlocks elements.
Outlook does not maintain a Unicode version for the FormulaANSI, ValidationRuleANSI, and ValidationTextANSI data elements in the PropDefV2 field definition format. If these elements contain non-ASCII characters, those characters may be interpreted inconsistently depending on the ANSI Code Page of the computer on which Outlook is running. Therefore, you should use only string values that consist entirely of ASCII characters for these data elements.
Data elements in this stream are stored in little-endian byte order, immediately following each other in the order specified below.
Flags: DWORD (4 bytes), a combination of zero or more flags whose values and meanings are listed in the following table.
Flag name
Value
Description
PDO_IS_CUSTOM
0x00000001
The FieldDefinition structure contains a definition of a user-defined field.
PDO_REQUIRED
0x00000002
For a form control bound to this field, the check box for A value is required for this field is selected in the Validation tab of the Properties dialog box.
PDO_PRINT_SAVEAS
0x00000004
For a form control bound to this field, the check box for Include this field for printing and Save As is selected in the Validation tab of the Properties dialog box.
PDO_CALC_AUTO
0x00000008
For a form control bound to this field, the check box for Calculate this formula automatically is selected in the Value tab of the Properties dialog box.
PDO_FT_CONCAT
0x00000010
This is a field of type Combination and it has the Joining fields and any text fragments with each other option selected in its Combination Formula Field dialog box.
PDO_FT_SWITCH
0x00000020
This field is of type Combination and has the Showing only the first non-empty field, ignoring subsequent ones option selected in the Combination Formula Field dialog box.
PDO_PRINT_SAVEAS_DEF
0x00000040
This flag is not used by Outlook, but it is included for all user-defined field definitions.
VT: WORD (2 bytes), the data type of the field, which is a constant from the VARENUM enumeration.
DispId: DWORD (4 bytes), the dispatch identifier of the field. For a user-defined field, the value is 0.
NmidNameLength: WORD (2 bytes), the number of elements in the NmidName array.
NmidName: An array of WCHAR. For a user-defined field definition, this is the Unicode (UTF-16) representation of the field name. The count of this array is equal to NmidNameLength.
NameANSI: A PackedAnsiString stream structure. This is the ANSI representation of the field name.
FormulaANSI: A PackedAnsiString stream structure. This is an ANSI representation of the calculation formula for the field. It is shown in the Initial Value section of the Value tab of the Properties dialog box of a form control bound to this field.
ValidationRuleANSI: A PackedAnsiString stream structure. This is an ANSI representation of the field’s validation formula. It is shown in the text box for Validation Formula on the Validation tab of the Properties dialog box of a form control bound to this field.
ValidationTextANSI: A PackedAnsiString stream structure. This is an ANSI representation of the field’s validation failure text. It is shown in the text box for Display this message if the validation fails on the Validation tab of the Properties dialog box of a form control bound to this field.
ErrorANSI: A PackedAnsiString stream structure. Outlook does not use this element; you should set this element to an empty string.
InternalType: DWORD (4 bytes), the internal type of the field. This data element is present only if the field definition format is PropDefV2. The internal type is one of the following values, each of which corresponds to a type in the New Field dialog box for user-defined fields.
Internal type name
Value
Corresponding type in New Field dialog box
iTypeString
0
Text
iTypeNumber
1
Number
iTypePercent
2
Percent
Currency
3
Currency
iTypeBool
4
Yes/No
iTypeDateTime
5
Date/Time
iTypeDuration
6
Duration
iTypeCombination
7
Combination, with the Showing only the first non-empty field, ignoring subsequent ones option selected in the Combination Formula Field dialog box.
iTypeFormula
8
Formula
iTypeResult
9
This type is not used for user-defined fields.
iTypeVariant
10
This type is not used for user-defined fields.
iTypeFloatResult
11
This type is not used for user-defined fields.
iTypeConcat
12
Combination, with the Joining fields and any text fragments with each other option selected in the Combination Formula Field dialog box.
iTypeKeywords
13
Keyword
iTypeInteger
14
Integer
SkipBlocks: A series of one or more SkipBlock stream structures. This data element is present only if the field definition format is PropDefV2. If the field definition format is PropDefV2, the series should contain at least one SkipBlock structure, the SkipBlock structure that has the Size data element equal to 0, and the series should begin and terminate with this SkipBlock structure.
The purpose of a SkipBlock structure depends on its relative position in the SkipBlocks series. If the field definition is in PropDefV2 format, and the first structure is not the terminating structure (the Size data element is greater than 0), Outlook assumes the first SkipBlock structure specifies the field name in Unicode (UTF-16).
Important
If the first SkipBlock is the terminating structure, the NameANSI data element is used to determine the field name. If that string contains any non-ASCII characters, those characters may be interpreted inconsistently depending on the ANSI code page of the computer on which Outlook is running. To prevent such inconsistencies, be sure you always specify the first SkipBlock in field definitions that you create, at least when the field name includes non-ASCII characters.
If a future version of a field definition format introduces additional pieces of data in the FieldDefinition stream, this data can be stored as additional SkipBlock stream structures in the SkipBlocks series before the terminating SkipBlock structure that has the Size data element equal to 0. Earlier versions of Outlook can safely ignore these extra SkipBlock structures up to the terminating SkipBlock structure and still correctly process all the blocks that they support.