Working with Multivalued Columns

A multivalued column contains the data of a multivalued property, or property that has an array of values of the base type rather than a single value. Because none of the tables include multivalued properties in their default column sets, multivalued properties are included in a table only if the user of the table requests it.

Multivalued columns can be displayed in tables:

• In a single row, with all of the property values appearing in the single column instance. This is the default.

  – Or –

• In a series of rows, with one row for each of the property values. Each unique value appears in the column in its own row with there being as many rows as there are values in the multivalued property. Each row has a unique value for the PR_INSTANCE_KEY property, but the same values for the other columns.

  If a row contains more than one column with multiple values, for example, two columns with M and N values respectively, then M*N instances of the row appear in the table.

A table user requests the nondefault type of display by calling the IMAPITable::SetColumns method with the MVI_FLAG flag set in the property type of the multivalued column. The MVI_FLAG flag is a constant defined as the result of combining the MV_FLAG and MV_INSTANCE flags with a logical OR operation. In addition to being used in SetColumns, MVI_FLAG can also be passed to IMAPITable::SortTable in the lpSortCriteria parameter and IMAPITable::Restrict in the ulPropTag member of the lpRestriction parameter. When passed the MVI_FLAG, SortTable performs similarly to SetColumns, adding one row for each value in the multivalued column and sorting on the single values in the instances. One row is added for each value.

Restrict, however, does not expand the multivalued column into additional computed rows. A multivalued column with the MVI_FLAG set instructs the service provider to use that column in restricting the table. If there is a property value in the restriction, it must be a single value property tag identical to the one that would be returned by IMAPITable::QueryRows for the column.

Table implementers are only required to support the default type of display and can return the MAPI_E_TOO_COMPLEX value when a caller requests the other alternative. The ability to support both types of display is most important for message store providers implementing folder contents tables.