The PR_RECORD_KEY property contains a unique binary-comparable identifier for a specific object.
| Header file: | MAPITAGS.H |
| Must be exposed by: | Address book container, attachment, distribution list, folder, messaging user, message, and message store objects |
| Identifier: | 0x0FF9 |
| Property type: | PT_BINARY |
| Property tag: | 0x0FF90102 |
The PR_RECORD_KEY property facilitates locating references to an object, such as finding its row in a contents table. PR_RECORD_KEY cannot be used to open an object; use the entry identifier for that purpose.
An attachment subobject should be uniquely identified within a message by PR_RECORD_KEY. This identifier is the only attachment characteristic guaranteed to stay the same after the message is closed and reopened. The store provider must preserve PR_RECORD_KEY across sessions to ensure this guarantee.
For folders, this property contains a key used in the folder hierarchy table. Typically this is the same value as that provided by the PR_ENTRYID property.
For message stores, this property is identical to the PR_STORE_RECORD_KEY property.
In a message store object, PR_RECORD_KEY should be unique across all store providers. One way to do this is to combine the value of the PR_MDB_PROVIDER property for the store (unique to that provider type) with a GUID structure or other value unique to the specific message store.
PR_RECORD_KEY is always available through the IMAPIProp::GetProps method following the first call to the IMAPIProp::SaveChanges method. Some providers can make it available immediately after instantiation.
A client or service provider can compare PR_RECORD_KEY values using memcmp. This is not possible for entry identifier values. However, PR_RECORD_KEY is guaranteed to be unique only within the same message store or address book container; two objects from different containers can have the same PR_RECORD_KEY value.
One distinction between the record and search keys is that the record key is specific to the object, whereas the search key can be copied to other objects. For example, two copies of the object can have the same PR_SEARCH_KEY value but must have different PR_RECORD_KEY values.
The following table summarizes important differences among PR_ENTRYID, PR_RECORD_KEY, and PR_SEARCH_KEY.
| Characteristic | PR_ENTRYID | PR_RECORD_KEY | PR_SEARCH_KEY |
|---|---|---|---|
| Required on attachment objects |
No | Yes | No |
| Required on folder objects |
Yes | Yes | No |
| Required on message store objects |
Yes | Yes | No |
| Required on status objects |
Yes | No | No |
| Creatable by client | No | No | Yes |
| Available before a call to SaveChanges |
Maybe | Maybe | Messages — Yes Others — Maybe |
| Changed in a copy operation |
Yes | Yes | No |
| Changeable by a client after a copy |
No | No | Yes |
| Unique within ... | Entire world | Provider instance | Entire world |
| Binary comparable (as with memcmp) |
No -- use IMAPISupport:: CompareEntryIDs |
Yes | Yes |