IMessage::ModifyRecipients

Platform SDK: MAPI

IMessage::ModifyRecipients

The IMessage::ModifyRecipients method adds, deletes, or modifies message recipients.

Quick Info

HRESULT ModifyRecipients(
  ULONG ulFlags,   
  LPADRLIST lpMods 
);

Parameters

ulFlags

[in] Bitmask of flags that controls the recipient changes. If zero is passed for the ulFlags parameter, ModifyRecipients replaces all existing recipients with the recipient list pointed to by the lpMods parameter. The following flags can be set for ulFlags:

MODRECIP_ADD: The recipients pointed to by the lpMods parameter should be added to the recipient list.
MODRECIP_MODIFY: The recipients pointed to by the lpMods parameter should replace existing recipients. All of the existing properties are replaced by those in the corresponding ADRENTRY structure.
MODRECIP_REMOVE: Existing recipients should be removed from the recipient list using as an index the PR_ROWID property included in the property value array of each recipient entry in the lpMods parameter.

lpMods

[in] Pointer to an ADRLIST structure containing a list of recipients to be added, deleted, or modified in the message.

Return Value

S_OK: The recipient list was successfully modified.

Remarks

The IMessage::ModifyRecipients method changes the message's recipient list. 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.

Recipients in the ADRLIST structure can be resolved or unresolved. The difference is in the number and type of properties that are included. An unresolved recipient contains only the PR_DISPLAY_NAME and PR_RECIPIENT_TYPE properties while a resolved recipient contains those two properties plus PR_ADDRTYPE and PR_ENTRYID. If PR_EMAIL_ADDRESS is available, it can be included also.

By the time a message is submitted, it must include only resolved recipients in its recipient list. Unresolved recipients cause nondelivery reports to be created and sent to the original sender of the message. For more information about the name resolution process from the client perspective, see Resolving a Name. For more information from the perspective of the address book provider, see Implementing Name Resolution.

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.

Notes to Callers

You can create a recipient list by calling IAddrBook::Address to display the common dialog box and prompt the user to select entries. The address list pointed to by the lppAdrList parameter to Address can be passed to ModifyRecipients as the lpMods parameter.

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. When a recipient is modified, any properties not included in the ADRLIST structure are deleted. To retrieve the current set of properties for all of a message's recipients, call GetRecipientTable and retrieve all of the rows. Because an SRowSet is identical in structure to an ADRLIST, you can use them interchangeably.

ModifyRecipients replaces all of the entries in the current recipient list with the information pointed to by lpMods when none of the flags are set in the ulFlags parameter.

Notes to Callers

When you set the MODRECIP_MODIFY flag, ModifyRecipients replaces each entire recipient row with the associated row in the ADRLIST structure passed in lpMods. Be careful to specify all of the properties that a recipient should have regardless of whether they have changed to prevent them from being unintentionally deleted.

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.
Include the PR_ROWID property for all recipients when you set either the MODRECIP_REMOVE or MODRECIP_MODIFY flag in ulFlags.
Do not include the PR_ROWID property for any of the recipients when you set the MODRECIP_ADD flag in ulFlags or when you pass zero in ulFlags.

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:

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

Use the allocation rules outlined in Managing Memory for ADRLIST and SRowSet Structures to allocate memory for the recipient list. ModifyRecipients does not free the ADRLIST structure nor 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.