Autocomplete Stream
Applies to: Outlook 2013 | Outlook 2016
In addition to knowing how Microsoft Outlook interacts with the autocomplete stream, you must also understand the binary format of the autocomplete stream.
The autocomplete stream is a set of recipient property rows that are saved as a binary stream together with some bookkeeping metadata that is used only by Microsoft Outlook 2013, Microsoft Outlook 2010, Microsoft Office Outlook 2007, and Microsoft Outlook 2003. The metadata is relevant to Outlook interactions with the autocomplete stream so third parties must preserve what is in each metadata block when they save a modified autocomplete stream. In other words, third parties should modify only the row-set part of the binary format and preserve what was already in the metadata blocks of the autocomplete stream.
Stream Visualization
The high-level layout of the autocomplete stream is as follows:
Metadata (4 bytes)
Major Version Number (4 bytes)
Minor Version Number (4 bytes)
Number of rows n (4 bytes)
Number of properties p in row one (4 bytes)
Property 1's property tag (4 bytes)
Property 1's reserved data (4 bytes)
Property 1's value union (8 bytes)
Property 1's value data (0 or variable bytes)
… (property 2 through property P-1)
Property p's property tag (4 bytes)
Property p's reserved data (4 bytes)
Property p's value union (8 bytes)
Property p's value data (0 or variable bytes)
Number of properties q in row two (4 bytes)
… (row two's properties)
… (row 3 through row n-1)
Number of properties r in row n (4 bytes)
… (row n's properties)
Extra information byte count EI (4 bytes)
Extra information (EI bytes)
Metadata (8 bytes)
For an example of a binary structure, see Binary Example in the Outlook 2003/2007 NK2 File Format and Developer Guidelines.
High-level Layout
Broadly speaking, the layout of the autocomplete stream is as follows:
| Value Data | Number of Bytes |
|---|---|
| Metadata |
4 |
| Major Version Number |
4 |
| Minor Version Number |
4 |
| Row-set |
Variable |
| Extra information byte count EI |
4 |
| Extra information |
EI |
| Metadata |
8 |
When reading this stream, if the major version is different than 12, then this stream should not be read or written. The current minor version of the autocomplete stream is 0, which has the Extra Information Byte count set to 0. If the minor version is different than 0, then there will be information in the extra information that needs to be read when reading the stream and preserved when writing the stream. The minor version will also need to be preserved when writing the stream. If both of these are not preserved, instances of Outlook that wrote the extra information will lose data.
Note
Applications must not add custom data to the Extra Information field or change the minor version as this functionality is to support Outlook extensions to the format and not arbitrary third-party extensions.
Row-set Layout
The row-set layout is as follows:
| Value Data | Number of Bytes |
|---|---|
| Number of rows |
4 |
| Rows |
Variable |
The number of rows identifies how many rows come in the next part of the binary stream sequence.
Row Layout
Each row is of the following format:
| Value Data | Number of Bytes |
|---|---|
| Number of properties |
4 |
| Properties |
Variable |
The number of properties identifies how many properties come in the next part of the binary stream sequence.
Property Layout
Each property is of the following format:
| Value Data | Number of Bytes |
|---|---|
| Property Tag |
4 |
| Reserved Data |
4 |
| Property Value Union |
|
| Value Data |
0 or variable (depending on the prop tag) |
Interpreting the Property Value
The Property Value Union and the Value Data are to be interpreted based on the property tag in the first 4 bytes of the property block. This property tag is in the same format as a MAPI property tag. Bits 0 through 15 of the property tag are the property's type. Bits 16 through 31 are the property's identifier. The property type determines how the rest of the property should be read.
Static Value
Some properties have no Value Data and only have data in the union. The following property types (which come from the Property Tag) should interpret the 8-byte Property Union data as follows:
| Prop Type | Property Union Interpretation |
|---|---|
| PT_I2 |
short int |
| PT_LONG |
long |
| PT_ERROR |
long |
| PT_R4 |
float |
| PT_DOUBLE |
double |
| PT_BOOLEAN |
short int |
| PT_SYSTIME |
FILETIME |
| PT_I8 |
LARGE_INTEGER |
Dynamic Values
Other properties have data in a Value Data block after the first 16 bytes that contain the Property Tag, the Reserved Data, and the Property Value Union. Unlike static values, the data that is stored in the 8-byte Property Value union is irrelevant on reading. When writing, make sure that you fill these 8 bytes with something. However, the content of the 8 bytes is not important. In dynamic values, the property tag's type determines how to interpret the Value Data.
PT_STRING8
| Value Data | Number of Bytes |
|---|---|
| Number of bytes n |
4 |
| Bytes to be interpreted as an ANSI string (includes NULL terminator) |
n |
PT_CLSID
| Value Data | Number of Bytes |
|---|---|
| Bytes to be interpreted as a GUID |
16 |
PT_BINARY
| Value Data | Number of Bytes |
|---|---|
| Number of bytes n |
4 |
| Bytes to be interpreted as a byte array |
n |
PT_MV_BINARY
| Value Data | Number of Bytes |
|---|---|
| Number of binary arrays X |
4 |
| A run of bytes that contains X binary arrays. Each array should be interpreted exactly like the PT_BINARY byte run. | Variable |
PT_MV_STRING8 (Outlook 2007, Outlook 2010, and Outlook 2013)
| Value Data | Number of Bytes |
|---|---|
| Number of ANSI strings X |
4 |
| A run of bytes that contains X ANSI strings. Each string should be interpreted exactly like the PT_STRING8 byte run. | Variable |
PT_MV_UNICODE (Outlook 2007, Outlook 2010, Outlook 2013)
| Value Data | Number of Bytes |
|---|---|
| Number of UNICODE strings X |
4 |
| A run of bytes that contains X UNICODE strings. Each string should be interpreted exactly like the PT_UNICODE byte run. | Variable |
Significant properties
As mentioned previously in this topic, the binary blocks that represent properties have property tags that correspond to properties on address book recipients. For properties that are not listed here, you can look up the property description at https://msdn.microsoft.com/library/cc433490(EXCHG.80).aspx.
| Property Name | Property Tag | Description (see MSDN for more information) |
|---|---|---|
| PR_NICK_NAME_W (not transmitted on recipients, specific to autocomplete stream only) |
0x6001001f |
This property must be first in each recipient row. It functionally serves as a key identifier for the recipient row. |
| PR_ENTRYID |
0x0FFF0102 |
The address book entry identifier for the recipient. |
| PR_DISPLAY_NAME_W |
0x3001001F |
The recipient's display name. |
| PR_EMAIL_ADDRESS_W |
0x3003001F |
The recipient's email address (e.g. johndoe@contoso.com or /o=Contoso/OU=Foo/cn=Recipients/cn=johndoe) |
| PR_ADDRTYPE_W |
0x3002001F |
The recipient's address type (e.g. SMTP or EX). |
| PR_SEARCH_KEY |
0x300B0102 |
The recipient's MAPI search key. |
| PR_SMTP_ADDRESS_W |
0x39FE001f |
The recipient's SMTP address. |
| PR_DROPDOWN_DISPLAY_NAME_W (not transmitted on recipients, specific to autocomplete stream only) |
0X6003001f |
The display string that appears in the autocomplete list. |
| PR_NICK_NAME_WEIGHT (not transmitted on recipients, specific to autocomplete stream only) |
0x60040003 |
The weight of this autocomplete entry. The weight is used to determine in what order autocomplete entries occur when matching the autocomplete list. Entries with higher weight will show before entries with lower weight. The complete autocomplete list is sorted by this property. The weight periodically decreases over time and increases when the user sends an email to this recipient. See the description later in this topic for more information about this property. |
PR_NICK_NAME_WEIGHT
The set of rows in the autocomplete stream is sorted in descending order by the PR_NICK_NAME_WEIGHT property and the autocomplete stream should always preserve this sorted characteristic. Therefore, any changes to a row's weight should also ensure that the row's position maintains the sorted order of the complete set of rows. Any additions to the row-set should be inserted to the correct position to maintain the sorted order.
The minimum value of this weight is 0x1 and the maximum value is LONG_MAX. Any other values for the weight are considered invalid.
When Outlook 2007 sends a mail to or resolves a recipient, it will increase that recipient's weight by 0x2000.