| Platform SDK: MAPI |
MAPI divides message properties into three types:
Message content properties describe the text of a message. Every message class has its own set of content properties. MAPI defines content properties for note and report messages; it is up to the clients and message store providers that handle these classes of messages to set the properties appropriately for their implementations. PR_BODY and PR_RTF_COMPRESSED are examples of content properties for note messages. PR_BODY contains the unformatted contents of a note while PR_RTF_COMPRESSED contains the compressed version of a note's formatted contents.
For new message classes, clients can define content-specific properties in one of two ways:
The identifier range for custom message class content properties is available to any client creating a custom message class. Therefore, one property identifier in this range can be used for multiple message classes. Users of properties in this range cannot make assumptions as to the behavior of the properties.
With named properties, clients create a name for each new property that is made up of a property set and either a character string or a numeric value and associate it with an identifier in the named property range. Users of named properties access them by name or identifier through the IMAPIProp methods GetIDsFromNames and GetNamesFromIDs.
Envelope properties provide information used to transmit a message from one recipient to another. As with message content properties, it is possible for clients or service providers to define their own envelope properties to supplement those defined by MAPI. Clients and transport providers set the envelope properties defined by MAPI based on the definition that MAPI provides. Transport providers that implement special features can define their own envelope properties to expose those features to clients. MAPI sets aside a range of property identifiers that can be used for these special provider-defined properties. Transport providers typically implement a special property page to display these properties and allow clients to edit them. PR_SUBJECT and PR_MESSAGE_CLASS are examples of envelope properties.
Recipient properties describe the destination for a sent message. A recipient can be a messaging user, distribution list, or a machine. Recipient properties are defined by MAPI and set by service providers. Some recipient properties are supported by address book providers for their messaging user and distribution list objects; other recipient properties are supported by clients, message store providers, or transport providers. For example, all recipients require an address and an address type; these are properties maintained by an address book provider when the recipient is stored in one of its containers. Recipients also have a type, PR_RECIPIENT_TYPE, which identifies a recipient as either a primary, carbon copy, or blind carbon copy recipient.
Many message properties are optional, meaning that clients cannot expect them to be available or set to valid values. Some message properties are required but available only when a message is in a particular state. For example, a newly created message is not required to have an entry identifier until after the message has been saved and is not required to have a message class until the message is ready to be submitted. Clients should always be prepared to handle the situation where a requested property is unavailable by checking the results of their IMAPIProp::GetProps and IMAPIProp::OpenProperty calls and by having default values ready as a backup.
Most message properties that are set by service providers are read-only to clients.
For a list of the most commonly used message properties, see Message Properties.