通过

文件夹字段Stream结构

适用于：Outlook 2013 | Outlook 2016

邮件的 PidTagUserFields 属性包含二进制流 FolderUserFields，其中包含文件夹用户定义的字段定义。 本主题介绍文件夹用户定义字段定义的流结构。

FolderUserFields 流结构由 FolderUserFieldsA 结构或 FolderUserFieldsA 结构组成，后跟 FolderUserFieldsW 结构。

此流中的数据元素按以下指定顺序紧随其后存储：

  • FolderUserFieldsAnsi：一个 FolderUserFieldsA 流结构。

  • FolderUserFieldsUnicode (可选) ：一个 FolderUserFieldsW 流结构。

FolderUserFieldsUnicode 的存在由 FolderUserFields 的总长度大于 FolderUserFieldsAnsi 的长度检测到。

重要

FolderUserFieldsAnsi 用于与较旧的非 Unicode 版本的 MAPI 客户端兼容，因此，如果存在 FolderUserFieldsUnicode，则忽略 FolderUserFieldsAnsi 的内容。 为了避免在 ANSI 转换中丢失数据，在创建 FolderUserFields 流时，始终包括 FolderUserFieldsW 部件。

FolderUserFieldsA Stream 结构

FolderUserFieldsA 流结构是 FolderFieldDefinitionA 流结构的数组，其中包含 Outlook 文件夹中所有用户定义字段的定义，除非由 FolderUserFields 结构的 FolderUserFieldsW 部分替代。

此流中的数据元素以 little-endian 字节顺序存储，并按以下指定顺序紧跟彼此：

  • FieldDefinitionCount：DWORD (4 个字节) ，即此流中的字段定义数。 这是 FieldDefinitions 数组中的元素计数。

  • FieldDefinitions：FolderFieldDefinitionA 流结构的数组。 此数组的计数等于 FieldDefinitionCount 数据元素。

除非此 FolderUserFieldsA 被 FolderUserFieldsW 部分的 FolderUserFieldsW 部分覆盖，否则 FieldDefinitions 数组必须通过使其最后一个 FolderFieldDefinitionA 元素的 Common.FieldType 字段等于 ftNull 来“以 null 结尾”。

FolderUserFieldsW Stream 结构

FolderUserFieldsW 流结构是 FolderFieldDefinitionW 流结构的数组，其中包含 Outlook 文件夹中所有用户定义字段的定义。

此流中的数据元素以 little-endian 字节顺序存储，并按以下指定顺序紧跟彼此：

  • FieldDefinitionCount：DWORD (4 个字节) ，即此流中的字段定义数。 这是 FieldDefinitions 数组中的元素计数。

  • FieldDefinitions：FolderFieldDefinitionW 流结构的数组。 此数组的计数等于 FieldDefinitionCount 数据元素。

FieldDefinitions 数组必须“以 null 结尾”，其最后一个 FolderFieldDefinitionW 元素的 Common.FieldType 字段等于 ftNull。

FolderFieldDefinitionA Stream 结构

FolderFieldDefinitionA 流结构包含用户定义的字段的定义，该字段名称存储在 ANSI 中。

此流中的数据元素以 little-endian 字节顺序存储，并按以下指定顺序紧跟彼此：

  • FieldType：FldType (4 个字节) ，即此字段的类型。

  • FieldNameLength：WORD (2 个字节) ， 即 FieldName 数组中的元素数。

  • FieldName：CHAR 的数组。 这是字段名称的 ANSI CP_ACP代码页表示形式。 此数组的计数等于 FieldNameLength。 字段名称必须满足 UserProperties.Add 方法中指定的 Name 参数限制。

    注意

    出于旧兼容性的原因，Outlook 可能能够处理一些不符合这些限制的 FieldName 值，但本主题未涵盖此类情况。

  • 常见：FolderFieldDefinitionCommon 流结构。

FolderFieldDefinitionW Stream 结构

FolderFieldDefinitionW 流结构包含用户定义的字段的定义，该字段名称存储在 Unicode 中。

此流中的数据元素以 little-endian 字节顺序存储，并按以下指定顺序紧跟彼此：

  • FieldType：FldType (4 个字节) ，即此字段的类型。

  • FieldNameLength：WORD (2 个字节) ， 即 FieldName 数组中的元素数。

  • FieldName：WCHAR 的数组。 这是 Unicode (UTF-16) 字段名称的表示形式。 此数组的计数等于 FieldNameLength。 字段名称必须满足 UserProperties.Add 方法中指定的 Name 参数限制。

    注意

    出于旧兼容性的原因，Outlook 可能能够处理一些不符合这些限制的 FieldName 值，但本主题未涵盖此类情况。

  • 常见：FolderFieldDefinitionCommon 流结构。

FldType 枚举

下表列出了 FldType 枚举值。

名称 值 含义
ftNull
 0x0
 此字段类型用于对字段定义数组进行 null 终止。
ftString
 0x1
 Text
ftInteger
 0x3
 整数
ftTime
 0x5
 日期/时间
ftBoolean
 0x6
 是/否
ftDuration
 0x7
 持续时间
ftMultiString
 0xB
 关键字
ftFloat
 0xC
 数字或百分比
ftCurrency
 0xE
 货币
ftCalc
 0x12
 公式
ftSwitch
 0x13
 类型组合，仅显示第一个非空字段 - 忽略后续字段。
ftConcat
 0x17
 将类型联接字段和任何文本片段组合在一起。

FolderFieldDefinitionCommon Stream 结构

FolderFieldDefinitionCommon 流结构包含用户定义字段定义的数据，该定义对于 FolderFieldDefinitionA 和 FolderFieldDefinitionW 都是通用的。

此流中的数据元素以 little-endian 字节顺序存储，并按以下指定顺序紧跟彼此：

  • PropSetGuid：GUID (16 字节) ，属性集 GUID 的文件夹字段的相应 MAPI 属性名称。 此字段的值必须等于 PS_PUBLIC_STRINGS，除非字段类型为 ftNone ，在这种情况下，此字段的值必须等于 GUID_NULL。

    注意

    出于旧兼容性的原因，Outlook 可能能够处理一些不符合此限制的 PropSetGuid 值，但本主题未涵盖此类情况。

  • fcapm：DWORD (4 个字节) ，零个或更多个的组合标记了下表中列出的值和含义。 具有相同值的标志的含义取决于字段的类型，即 FldType 值。

    标志名称 值 含义
    FCAPM_CAN_EDIT
    		 0x00000001
    		 字段是可编辑的。
    FCAPM_CAN_SORT
    		 0x00000002
    		 字段可排序。
    FCAPM_CAN_GROUP
    		 0x00000004
    		 字段可分组。
    FCAPM_MULTILINE_TEXT
    		 0x00000100
    		 字段可以包含多行文本。
    FCAPM_PERCENT
    		 0x01000000
    		 ftFloat 类型的此字段是百分比字段。
    FCAPM_DATEONLY
    		 0x01000000
    		 ftTime 类型的此字段是仅限日期的时间字段。
    FCAPM_UNITLESS
    		 0x01000000
    		 对于 ftInteger 类型的此字段，不允许使用任何单位的显示格式;例如，“计算机 - 640 K...”等格式不允许。
    FCAPM_CAN_EDIT_IN_ITEM
    		 0x80000000
    		 可以在项目中编辑字段：这是专用于自定义窗体。

  • dwString：DWORD (4 个字节) 。 请参阅下面的第一个说明。

  • dwBitmap：) DWORD (4 个字节。 请参阅下面的第一个说明。

  • dwDisplay：) DWORD (4 个字节。 请参阅下面的第一个说明。

  • iFmt：INT) (4 个字节。 对于在“新建字段”、“编辑字段”和“字段属性”对话框中具有“Format：”组合框的字段类型，该组合框中所选格式的从 0 开始的索引。 对于没有该组合框的字段类型，这必须为 0。 字段的值与字段类型一起唯一地决定了 dwString、 dwBitmap 和 dwDisplay 字段的值，请参阅下面的第一个说明。

  • wszFormulaLength：WORD (2 个字节) ， 即 wszFormulaLength 数组中的元素数。

  • wszFormulaLength：WCHAR 的数组。 这是 Unicode (UTF-16) 字段公式字符串的标准格式表示形式。 有关字段公式的标准格式和 UI 格式的说明，请参阅下面的第二个说明。 此数组的计数等于 wszFormulaLength。 除非字段类型为 ftCalc、 ftSwitch 或 ftConcat，否则公式字符串必须为空字符串。

注意

尽管 dwString、 dwBitmap 和 dwDisplay 的值是基于 FldType 值和 iFmt 值（这些值是冗余的）唯一确定的，但它们的正确值仍需要 Outlook 正确处理字段定义。 对于执行此确定的算法，没有简单的说明。

因此，若要找出哪些 dwString、 dwBitmap 和 dwDisplay 值对应于给定 的 FldType 值和 iFmt 值，请通过创建该类型的用户定义的字段来执行测试，并在“ 格式 ”组合框中选中该格式（假设其适用性），检查 Outlook 为该用户定义字段创建的生成的 FolderUserFields 流。

在用户定义字段的“新建字段”、“编辑字段”和“字段属性”对话框的“公式”文本框中，将编辑其 UI 格式的字段公式。 将公式从 UI 格式转换为标准格式的算法取决于字段类型，如下所述：

  • 对于 ftCalc 和 ftSwitch 类型的字段，内置字段的标准格式（相应的 MAPI 属性不是MNID_STRING类型的命名属性）是通过替换字段名称片段（即 [<field_name>] 片段 ）获取的 [_<field_dispid_decimal>]。

    例如，如果公式类型为 “公式”（即 ftCalc）的字段的 UI 格式（Office UI 语言为 US English）为 [Business Phone] & [My custom field]，其中 My custom field 是用户定义的字段的名称，则此类公式的标准格式将为 [_14856] & [My custom field]。

  • 对于 ftConcat 类型的字段，可通过执行以下操作来获取标准格式：

    1. 截断前导空格和尾随空格。
    2. 将公式分析为以下两种类型的片段序列：
      • 方括号中的字段名称，即 [<field_name>]。
      • 不包含任何方括号的子字符串。
        确保序列中没有第二类的两个片段相邻。 如果公式无法以这种方式进行分析，则被视为无效。
    3. 对第一种类型的片段执行与 ftCalc 和 ftSwitch 字段相同的替换。
    4. 对于第二类的每个片段，请转义所有双引号 (“”“) 字符（如果有），并用双引号括起来。
    5. 在 & 每对相邻片段之间插入 () 和字符串。

    例如，使用 Office UI 语言美国英语，如果 ftConcat 类型字段的公式的 UI 格式为 text1 [Business Phone] "text2" [My custom field]，其中 My custom field 是用户定义的字段的名称，则此类公式的标准格式将为 ""text1" & [_14856] & """text2""" & [My custom field]"。

另请参阅