IMessage::ModifyRecipients

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

Quick Info

See IMessage : IMAPIProp3LEP_T6.

HRESULT ModifyRecipients(

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_ROWID1P3N3GU property included in the property value array of each recipient entry in the lpMods parameter.

lpMods

[in] Pointer to an ADRLIST16760YG 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 ADRLIST16760YG structure, that the recipient table is built.

The ADRLIST structure contains one ADRENTRYWLHOWG 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_NAME1KS30YA and PR_RECIPIENT_TYPE1VRJ4HY properties while a resolved recipient contains those two properties plus PR_ADDRTYPE7C7E4S and PR_ENTRYID2JH9H8T. If PR_EMAIL_ADDRESSJ.C5HA 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 NameN2JFNJ. For more information from the perspective of the address book provider, see Implementing Name Resolution0PQZ7M.

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::Address6P2ISS 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 ADRLIST16760YG 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 GetRecipientTable12Z640H 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 ADRLIST16760YG 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_ROWID1P3N3GU 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_ADDRTYPE7C7E4S property or PR_EMAIL_ADDRESSJ.C5HA 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_ENTRYID2JH9H8T, 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 StructuresJEZ06_ to allocate memory for the recipient list. ModifyRecipients does not free the ADRLIST structure nor any of its substructures. The ADRLIST structure and each SPropValue81C9._8 structure must be separately allocated by using the MAPIAllocateBuffer1MW3BAZ 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 MAPIFreeBuffer16U06F. The original SPropValue structure should also be freed using MAPIFreeBuffer.

See Also