This documentation is archived and is not being maintained.

FieldDefinition Stream Structure

Last modified: October 10, 2010

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 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 note 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.

Show: