IMessage::ModifyRecipients

Article
08/28/2006

The ModifyRecipients method replaces the current recipient list with a new one.

Syntax

HRESULT ModifyRecipients (
  ULONG ulFlags,
  LPADRLIST lpMods
);

Parameters

ulFlags
[in] Bitmask of flags that controls the recipient changes. MODRECIP_ADD must be set, indicating that the recipients pointed to by lpMods will replace the existing recipient list; all other flags are ignored.
lpMods
[in] Reference to an ADRLIST structure containing a list of recipients; cannot be NULL.

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
Indicates success.

Remarks

ModifyRecipients changes the message's recipient list, and it is from this list, held in an ADRLIST structure, that the recipient table is built.

The ADRLIST structure contains one ADRENTRY structure for each recipient, and each ADRENTRY structure contains an array of property values describing the recipient properties.

In addition to resolved and unresolved recipients, a recipient can be NULL. That is, the cValues member of the ADRENTRY structure for the recipient is set to zero and the rgPropVals member is set to NULL.

When you specify properties for a recipient in the ADRLIST structure, include all of the recipient's properties, not only the new or changed ones. To retrieve the current set of properties for all of a message's recipients, call IMessage::GetRecipientTable and retrieve all of the rows. Because an SRowSet is identical in structure to an ADRLIST, you can use them interchangeably.

Following are some rules for setting the properties of the recipients in the ADRLIST structure:

Do not use PT_NULL as a property type. ModifyRecipients returns an error when encountering this value.
Do not use PT_ERROR as a property type. ModifyRecipients ignores this value.
Do not include the PR_ROWID property for any of the recipients.

If you include either the PR_ADDRTYPE property or PR_EMAIL_ADDRESS property for a recipient, and one or both of these properties are inconsistent with the address type and address of the recipient as identified by PR_ENTRYID, the results are undefined. That is, there are three possibilities, depending on the service provider, as follows:

The message is delivered to the address described by the PR_ADDRTYPE and PR_EMAIL_ADDRESS properties.
The message is delivered to the recipient identified by PR_ENTRYID.
The message is declared undeliverable due to the ambiguity of the address information.

ModifyRecipients does not free the ADRLIST structure or any of its substructures. The ADRLIST structure and each SPROPVALUE structure must be separately allocated by using the MAPIAllocateBuffer function, such that each can be freed individually. If the method requires additional space for any SPROPVALUE structure, it can replace the SPROPVALUE structure with a new one that can later be freed using MAPIFreeBuffer. The original SPROPVALUE structure should also be freed using MAPIFreeBuffer.

Requirements

Pocket PC: Pocket PC 2002 and later
Smartphone: Smartphone 2002 and later
OS Versions: Windows CE 3.0 and later
Header: mapidefs.h
Library: cemapi.lib