Folder Fields Stream Structures

Office 2013 and later

Last modified: July 06, 2012

Applies to: Outlook

A message’s PidTagUserFields property contains a binary stream, FolderUserFields, which contains the folder user-defined field definitions. This topic describes the stream structures for folder user-defined field definitions.

A FolderUserFields stream structure consists of either a FolderUserFieldsA structure or a FolderUserFieldsA structure followed by a FolderUserFieldsW structure.

Data elements in this stream are stored immediately following each other in the following specified order:

  • FolderUserFieldsAnsi: A FolderUserFieldsA stream structure.

  • FolderUserFieldsUnicode (optional): A FolderUserFieldsW stream structure.

The presence of FolderUserFieldsUnicode is detected by the total length of the FolderUserFields being greater than the length of FolderUserFieldsAnsi.

Important note Important

FolderUserFieldsAnsi is used for compatibility with older, non-Unicode, versions of MAPI clients, therefore if FolderUserFieldsUnicode is present, the contents of FolderUserFieldsAnsi is ignored. To avoid possible data loss in ANSI conversion, when creating a FolderUserFields stream always include the FolderUserFieldsW part.

FolderUserFieldsA Stream Structure

A FolderUserFieldsA stream structure is an array of FolderFieldDefinitionA stream structures that contain definitions for all user-defined fields in an Outlook folder, unless overridden by the FolderUserFieldsW part of the FolderUserFields structure.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldDefinitionCount: DWORD (4 bytes), the number of field definitions in this stream. This is the count of elements in the FieldDefinitions array.

  • FieldDefinitions: An array of FolderFieldDefinitionA stream structures. The count of this array is equal to the FieldDefinitionCount data element.

Unless this FolderUserFieldsA is overridden by the FolderUserFieldsW part of the FolderUserFields structure, the FieldDefinitions array must be "null-terminated" by having its last FolderFieldDefinitionA element’s Common.FieldType field equal to ftNull.

FolderUserFieldsW Stream Structure

A FolderUserFieldsW stream structure is an array of FolderFieldDefinitionW stream structures that contain definitions for all user-defined fields in an Outlook folder.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldDefinitionCount: DWORD (4 bytes), the number of field definitions in this stream. This is the count of elements in the FieldDefinitions array.

  • FieldDefinitions: An array of FolderFieldDefinitionW stream structures. The count of this array is equal to the FieldDefinitionCount data element.

The FieldDefinitions array must be "null-terminated" by having its last FolderFieldDefinitionW element’s Common.FieldType field equal to ftNull.

FolderFieldDefinitionA Stream Structure

A FolderFieldDefinitionA stream structure contains a definition of a user-defined field with the field name stored in ANSI.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldType: FldType (4 bytes), the type of this field.

  • FieldNameLength: WORD (2 bytes), the number of elements in the FieldName array.

  • FieldName: An array of CHAR. This is the ANSI CP_ACP codepage representation of the field name. The count of this array is equal to FieldNameLength. The field name must satisfy the restrictions on the Name parameter as specified in the UserProperties.Add Method.

    Note Note

    For reasons of legacy compatibility, Outlook may be able to handle some FieldName values not satisfying these restrictions, however such cases are not covered by this topic.

  • Common: A FolderFieldDefinitionCommon stream structure.

FolderFieldDefinitionW Stream Structure

A FolderFieldDefinitionW stream structure contains a definition of a user-defined field with the field name stored in Unicode.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldType: FldType (4 bytes), the type of this field.

  • FieldNameLength: WORD (2 bytes), the number of elements in the FieldName array.

  • FieldName: An array of WCHAR. This is the Unicode (UTF-16) representation of the field name. The count of this array is equal to FieldNameLength. The field name must satisfy the restrictions on the Name parameter as specified in the UserProperties.Add Method.

    Note Note

    For reasons of legacy compatibility, Outlook may be able to handle some FieldName values not satisfying these restrictions, but such cases are not covered by this topic.

  • Common: A FolderFieldDefinitionCommon stream structure.

FldType Enumeration

FldType enumeration values are listed in the following table.

Name

Value

Meaning

ftNull

0x0

This field type is used to null-terminate an array of field definitions.

ftString

0x1

Text

ftInteger

0x3

Integer

ftTime

0x5

Date/Time

ftBoolean

0x6

Yes/No

ftDuration

0x7

Duration

ftMultiString

0xB

Keywords

ftFloat

0xC

Number or Percent

ftCurrency

0xE

Currency

ftCalc

0x12

Formula

ftSwitch

0x13

Combination of type showing only the first non-empty field – ignoring subsequent ones.

ftConcat

0x17

Combination of type joining fields and any text fragments to each other.

FolderFieldDefinitionCommon Stream Structure

A FolderFieldDefinitionCommon stream structure contains the data of a user-defined field definition that is common to both a FolderFieldDefinitionA and a FolderFieldDefinitionW.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • PropSetGuid: GUID (16 bytes), the property set GUID of the folder field’s corresponding MAPI property name. This field’s value must be equal to PS_PUBLIC_STRINGS, unless the field type is ftNone in which case this field’s value must be equal to GUID_NULL.

    Note Note

    For reasons of legacy compatibility, Outlook may be able to handle some PropSetGuid values not satisfying this restriction, however such cases are not covered by this topic.

  • fcapm: DWORD (4 bytes), a combination of zero or more flags the values of which and meanings are listed in the following table. Flags with the same value have meanings dependent on the field’s type, that is, FldType value.

    Flag name

    Value

    Meaning

    FCAPM_CAN_EDIT

    0x00000001

    The field is editable.

    FCAPM_CAN_SORT

    0x00000002

    The field is sortable.

    FCAPM_CAN_GROUP

    0x00000004

    The field is groupable.

    FCAPM_MULTILINE_TEXT

    0x00000100

    The field can hold multiple lines of text.

    FCAPM_PERCENT

    0x01000000

    This field of the type ftFloat is a percentage field.

    FCAPM_DATEONLY

    0x01000000

    This field of the type ftTime is a date-only time field.

    FCAPM_UNITLESS

    0x01000000

    For this field of the type ftInteger, no unit is allowed in display format; for example such formats as "Computer – 640 K…" are not allowed.

    FCAPM_CAN_EDIT_IN_ITEM

    0x80000000

    The field can be edited in the item: This is specifically for custom forms.

  • dwString: DWORD (4 bytes). See the first following Note.

  • dwBitmap: DWORD (4 bytes). See the first following Note.

  • dwDisplay: DWORD (4 bytes). See the first following Note.

  • iFmt: INT (4 bytes). For the field types that have the "Format:" combo box in the "New Field", "Edit Field", and "Field Properties" dialogs, the 0-based index of the format selected in that combo box. For the field types without that combo box, this must be 0. The field’s value together with the field type uniquely determine the values of the dwString, dwBitmap, and dwDisplay fields, see the first following Note.

  • wszFormulaLength: WORD (2 bytes), the number of elements in the wszFormula array.

  • wszFormula: An array of WCHAR. This is the Unicode (UTF-16) representation of the field’s formula string in its standard format. See the second following Note for the description of the standard and UI formats of a field’s formula. The count of this array is equal to wszFormulaLength. The formula string must be an empty string unless the field type is ftCalc, ftSwitch or ftConcat.

Note Note

Although the values of dwString, dwBitmap, and dwDisplay are uniquely determined based on the FldType value and the iFmt value, which are redundant, their correct values are still necessary for correct processing of the field definition by Outlook. There is no simple description of the algorithm that performs this determination. Therefore, to find out which dwString, dwBitmap, and dwDisplay values correspond to a given FldType value and iFmt value, perform a test by creating a user-defined field of that type and with that format selected in the "Format:" combo box, assuming its applicability, inspect the resulting FolderUserFields stream that Outlook creates for that user-defined field.

Note Note

The field’s formula in its UI format is edited in the "Formula:" textbox of the "New Field", "Edit Field", and "Field Properties" dialogs for the user-defined field. The algorithm to convert a formula from the UI format to the standard format depends on the field type as described in the following:

  • For fields of types ftCalc and ftSwitch, the standard format for built-in fields, which corresponding MAPI properties are not named properties of the kind MNID_STRING, is obtained by replacing field name fragments, that is "[<field_name>]" with fragments "[_<field_dispid_decimal>]". For example, if the UI format of a formula for a field of the type "Formula", that is ftCalc, with the Office UI language being US English is "[Business Phone] & [My custom field]" where "My custom field" is the name of a user-defined field, the standard format of such a formula would be "[_14856] & [My custom field]".

  • For fields of the type ftConcat, the standard format is obtained by performing the following:

    1. Truncate leading and trailing whitespace.

    2. Parse the formula into a sequence of fragments of the following two kinds:

      • A field name in square brackets, that is, [<field_name>].

      • A substring not containing any square brackets.

      Assure that no two fragments of the second kind are adjacent in the sequence. If the formula cannot be parsed this way, it is considered invalid.

    3. Perform the same replacement for fragments of the first kind as for the ftCalc and ftSwitch fields.

    4. For each fragment of the second kind, escape all double-quote (""") characters, if any, with two consecutive double-quote characters, and enclose it in double quotes.

    5. Insert an ampersand string, that is, " & " between each pair of adjacent fragments.

    For example, using the Office UI language US English, if the UI format of a formula for a field of the type ftConcat is " text1 [Business Phone] "text2" [My custom field] ", where "My custom field" is the name of a user-defined field, the standard format for such a formula would be ""text1 " & [_14856] & """text2""" & [My custom field]".

Show: