| Platform SDK: MAPI |
The MapiRecipDesc structure, which describes a recipient, contains both the recipient's address and the recipient's "friendly name." The address, contained in the lpszAddress member, contains the address that the messaging system uses to deliver the message. This can take a number of forms depending on what type of address it is. All addresses are of the form [AddressType][E-mail Address]. For example, an internet address could be SMTP:jdoe@microsoft.com, while a fax gateway address could be FAX:206-555-1212.
The friendly name, stored in the lpszName member, typically contains the recipient's actual name or some variation of it. Whenever possible, the messaging system places a value in this member when a message is retrieved from a message store. However, not all addresses can be assigned a friendly name. For example, a fax gateway address might not correspond to a specific person, so the address book might not contain a name associated with that address. Similarly, the nature of internet addresses is such that the messaging system might not be able to determine a friendly name for messages that come into the system through an internet gateway; the address book cannot contain entries for every valid internet address, and the format of internet addresses does not mandate that a friendly name be attached to them.
You should display friendly names to the user when these names are available. When they are not, it is acceptable to display the actual address instead. When forwarding or replying to a message, you should never allow the user to edit the friendly name or address fields of a MapiRecipDesc structure that the messaging system has returned with a message. Both friendly names and addresses should be treated as indivisible entities.
When displaying a message to the user, make a distinction between different types of recipients that might be present in the message's lpOriginator and lpRecips members. The lpOriginator member contains the address and friendly name of the individual who sent the message. Display this recipient (note that the originator of a message is still called a recipient because both originators and actual recipients are described by MapiRecipDesc structures) so that the user is aware of this recipient's role.
Recipients stored in the lpRecips member can have one of four different roles. The ulRecipClass member of the MapiRecipDesc structure stores this information.
| Role | Description |
|---|---|
| MAPI_TO | The recipient is a primary recipient of the original message. |
| MAPI_CC | The recipient received a carbon copy of the original message. |
| MAPI_BCC | The recipient received a blind carbon copy of the original message. |
| MAPI_ORIG | The recipient sent the message. |
In practice, MAPI_BCC and MAPI_ORIG are less common than the others. MAPI_BCC should only occur if the user reading the message is the one who received a blind carbon copy. The semantics of MAPI_BCC are such that no one besides the originator and a MAPI_BCC recipient should ever know that the recipient received the message. MAPI_ORIG should only occur if the user sent a message to himself or herself.