PidTagSearchKey Canonical Property

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Contains a binary-comparable key that identifies correlated objects for a search.

Associated properties:

PR_SEARCH_KEY

Identifier:

0x300B

Data type:

PT_BINARY

Area:

ID properties

Remarks

This property provides a trace for related objects, such as message copies, and facilitates finding unwanted occurrences, such as duplicate recipients.

MAPI uses specific rules for constructing search keys for message recipients. The search key is formed by concatenating the address type (in uppercase characters), the colon character ':', the e-mail address in canonical form, and the terminating null character. Canonical form here means that case-sensitive addresses appear in the correct case, and addresses that are not case-sensitive are converted to uppercase. This is important in preserving correlations among messages.

For message objects, this property is available through the IMAPIProp::GetProps method immediately following message creation. For other objects, it is available following the first call to the IMAPIProp::SaveChanges method. Because this property is changeable, it is unreliable to obtain it through GetProps until a SaveChanges call has committed any values set or changed by the IMAPIProp::SetProps method.

For profiles, MAPI also furnishes a hard-coded profile section named MUID_PROFILE_INSTANCE, with this property as its single property. This key is guaranteed to be unique among all profiles ever created, and can be more reliable than the PR_PROFILE_NAME (PidTagProfileName) property, which can be, for example, deleted and recreated with the same name.

The following table summarizes important differences among the PR_ENTRYID (PidTagEntryId), PR_RECORD_KEY (PidTagRecordKey), and this property.

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 SaveChanges

Depends on the provider implementation

Depends on the provider implementation

For messages, Yes. For others, It depends on the provider implementation.

Changed in a copy operation

Yes

Yes

No

Changeable by 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

Protocol Specifications

  • [MS-OXPROPS]
    Provides references to related Exchange Server protocol specifications.

  • [MS-OXCMSG]
    Handles message and attachment objects.

  • [MS-OXOABK]
    Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

  • Mapidefs.h
    Provides data type definitions.

  • Mapitags.h
    Contains definitions of properties listed as alternate names.

See Also

Reference

PidTagResponsibility Canonical Property

PidTagStoreRecordKey Canonical Property

Concepts

MAPI Properties

MAPI Canonical Properties

Mapping Canonical Property Names to MAPI Names

Mapping MAPI Names to Canonical Property Names