IMessage::ModifyRecipients (Compact 7)

3/12/2014

This method adds, deletes, and modifies a message's list of recipients. This list is contained in an ADRLIST structure.

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 that the lpMods parameter points to will replace the existing recipient list. All other flags are ignored.

• lpMods
  [in] Pointer to a reference to an ADRLIST structure that contains a list of recipients. Cannot be NULL.

Return Value

This following table shows the possible return values.

Remarks

The ModifyRecipients method 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 that describe 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.

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

• Do not use PT_NULL or PT_ERROR as a property type. ModifyRecipients ignores these values.
• 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 that the PR_ADDRTYPE and PR_EMAIL_ADDRESS properties describe.
• The message is delivered to the recipient that PR_ENTRYID identifies.
• The message is declared undeliverable because of the ambiguity of the address information.

The ModifyRecipients method does not free the ADRLIST structure or any of its substructures. The ADRLIST structure and each SPROPVALUE structure must be separately allocated using the MAPIAllocateBuffer function, so 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 you can later free using MAPIFreeBuffer. You also free the original SPROPVALUE structure using MAPIFreeBuffer.

Requirements

See Also

Reference

IMessage