IMessage::ModifyRecipients

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

Ajoute, supprime ou modifie des destinataires du message.

HRESULT ModifyRecipients(
  ULONG ulFlags,
  LPADRLIST lpMods
);

Paramètres

ulFlags

[in] Masque de bits d'indicateurs qui contr�le les modifications apport�es par destinataire. Si zéro est passé pour le paramètre ulFlags , ModifyRecipients remplace tous les destinataires existants par la liste de destinataires pointée par le paramètre lpMods . Les indicateurs suivants peuvent être définis pour ulFlags :

MODRECIP_ADD

Les destinataires pointés par le paramètre lpMods doivent être ajoutés à la liste des destinataires.

MODRECIP_MODIFY

Les destinataires pointés par le paramètre lpMods doivent remplacer les destinataires existants. Toutes les propri�t�s existantes sont remplac�es par celles de la structure ADRENTRY correspondante.

MODRECIP_REMOVE

Les destinataires existants doivent être supprimés de la liste des destinataires en utilisant comme index la propriété PR_ROWID (PidTagRowid) incluse dans le tableau de valeurs de propriété de chaque entrée de destinataire dans le paramètre lpMods .

lpMods

[in] Pointeur vers une structure ADRLIST qui contient une liste de destinataires pour �tre ajout�s, supprim�s ou modifi�s dans le message.

Valeur renvoyée

S_OK

La liste des destinataires a �t� modifi�e avec succ�s.

Remarques

La m�thode IMessage::ModifyRecipients modifie la liste des destinataires du message. Il est � partir de cette liste, organis�e dans une structure ADRLIST , que la table de destinataires est g�n�r�e.

La structure ADRLIST contient une structure ADRENTRY pour chaque destinataire et chaque structure ADRENTRY contient un tableau de valeurs de propri�t�s d�crivant les propri�t�s du destinataire.

Destinataires de la structure ADRLIST peuvent �tre r�solus ou non r�solues. La diff�rence r�side dans le nombre et le type des propri�t�s qui sont inclus. Un destinataire non résolu contient uniquement les propriétés PR_DISPLAY_NAME (PidTagDisplayName) et PR_RECIPIENT_TYPE (PidTagRecipientType), tandis qu’un destinataire résolu contient ces deux propriétés plus PR_ADDRTYPE (PidTagAddressType) et PR_ENTRYID (PidTagEntryId). Si PR_EMAIL_ADDRESS (PidTagEmailAddress) est disponible, il peut également être inclus.

Au moment o� qu'un message est envoy�, il doit inclure uniquement les destinataires r�solus dans sa liste des destinataires. Destinataires non r�solus provoquent des rapports de non-remise � �tre cr�� et envoy� � l'exp�diteur d'origine du message. Pour plus d'informations sur le processus de r�solution de nom � partir du point de vue du client, consultez la rubrique r�solution d'un nom. Pour plus d'informations � partir du point de vue du fournisseur de carnet d'adresses, voir Impl�mentation de la r�solution de noms.

En plus des destinataires r�solus et non r�solus, un destinataire peut �tre NULL. Le membre cValues de la structure ADRENTRY pour le destinataire est d�fini sur z�ro et le membre rgPropVals est d�fini sur NULL.

Remarques pour les appelants

Vous pouvez cr�er une liste de destinataires en appelant IAddrBook::Address pour afficher la bo�te de dialogue commune et demandez � l'utilisateur de s�lectionner des entr�es. La liste d’adresses pointée par le paramètre lppAdrList sur Address peut être passée à ModifyRecipients en tant que paramètre lpMods .

Lorsque vous sp�cifiez les propri�t�s d'un destinataire dans la structure ADRLIST , inclure toutes les propri�t�s du destinataire, non seulement celles nouvelles ou modifi�es. Lorsqu'un destinataire est modifi�, toutes les propri�t�s non incluses dans la structure ADRLIST sont supprim�es. Pour r�cup�rer l'ensemble actuel des propri�t�s pour tous les destinataires d'un message, appelez GetRecipientTable et r�cup�rer toutes les lignes. Un SRowSet �tant identique en structure � une ADRLIST, vous pouvez les utiliser indiff�remment.

ModifyRecipients remplace toutes les entrées de la liste de destinataires actuelle par les informations pointées par lpMods lorsqu’aucun indicateur n’est défini dans le paramètre ulFlags .

Lorsque vous définissez l’indicateur MODRECIP_MODIFY, ModifyRecipients remplace chaque ligne de destinataire entière par la ligne associée dans la structure ADRLIST passée dans lpMods. Veillez � sp�cifier toutes les propri�t�s ayant un destinataire doit qu'elles ont chang� pour emp�cher leur involontairement supprim�.

Voici quelques r�gles pour d�finir les propri�t�s des destinataires dans la structure ADRLIST:

N'utilisez pas PT_NULL comme un type de propri�t�. ModifyRecipients renvoie une erreur si vous rencontrez cette valeur.
N'utilisez pas PT_ERROR comme un type de propri�t�. ModifyRecipients ignore cette valeur.
Incluez la propriété PR_ROWID pour tous les destinataires lorsque vous définissez l’indicateur MODRECIP_REMOVE ou MODRECIP_MODIFY dans ulFlags.
N’incluez pas la propriété PR_ROWID pour les destinataires lorsque vous définissez l’indicateur MODRECIP_ADD dans ulFlags ou lorsque vous passez zéro dans ulFlags.

Si vous incluez soit la PR_ADDRTYPE propri�t� ou PR_EMAIL_ADDRESS pour un destinataire et un ou deux de ces propri�t�s sont incompatibles avec le type d'adresse et l'adresse du destinataire comme identifi� par PR_ENTRYID, les r�sultats ne sont pas d�finis. En d'autres termes, il existe trois possibilit�s, selon le fournisseur de services :

Le message est remis � l'adresse d�crit par les propri�t�s PR_ADDRTYPE et PR_EMAIL_ADDRESS.
Le message est remis au destinataire identifi� par PR_ENTRYID.
Le message sera d�clar� non remis en raison de l'ambigu�t� de l'adresse.

Utiliser les r�gles de r�partition d�crites dans la Gestion de la m�moire ADRLIST et SRowSet des Structures d'allocation de m�moire pour la liste des destinataires. ModifyRecipients ne la lib�re pas la structure ADRLIST ni aucun de ses sous-structures. La structure ADRLIST et chaque SPropValue doivent �tre allou�s s�par�ment � l'aide de la fonction MAPIAllocateBuffer telle que chacun peut �tre lib�r� individuellement. Si la m�thode requiert un espace suppl�mentaire pour n'importe quelle structure SPropValue, elle peut remplacer la structure de SPropValue avec un fichier qui peut ult�rieurement lib�r� � l'aide de MAPIFreeBuffer. La structure SPropValue d'origine doit aussi �tre lib�r�e � l'aide de MAPIFreeBuffer.