IMAPIProp::CopyTo

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

Copie ou déplace toutes les propriétés, à l’exception des propriétés spécifiquement exclues.

HRESULT CopyTo(
 ULONG ciidExclude,
 LPCIID rgiidExclude,
 LPSPropTagArray lpExcludeProps,
 ULONG_PTR ulUIParam,
 LPMAPIPROGRESS lpProgress,
 LPCIID lpInterface,
 LPVOID lpDestObj,
 ULONG ulFlags,
 LPSPropProblemArray FAR * lppProblems
);

Paramètres

ciidExclude

[in] Nombre d’interfaces à exclure lorsque des propriétés sont copiées ou déplacées.

rgiidExclude

[in] Tableau d’identificateurs d’interface (IID) qui spécifient des interfaces qui ne doivent pas être utilisées lorsque des informations supplémentaires sont copiées ou déplacées vers l’objet de destination.

lpExcludeProps

[in] Pointeur vers un tableau de balises de propriété qui identifie les balises de propriété qui doivent être exclues de l’opération de copie ou de déplacement. Le passage de null dans le paramètre lpExcludeProps indique que toutes les propriétés de l’objet doivent être copiées ou déplacées. CopyTo retourne MAPI_E_INVALID_PARAMETER lorsque le membre cValues de la structure SPropProblemArray pointée par lpExcludeProps est défini sur 0.

ulUIParam

[in] Handle de la fenêtre parente de l’indicateur de progression.

lpProgress

[in] Pointeur vers l’implémentation d’un indicateur de progression. Si null est passé dans le paramètre lpProgress , MAPI fournit l’implémentation de progression. Le paramètre lpProgress est ignoré, sauf si l’indicateur MAPI_DIALOG est défini dans le paramètre ulFlags .

lpInterface

[in] Pointeur vers l’identificateur d’interface (IID) qui représente l’interface à utiliser pour accéder à l’objet vers lequel pointe le paramètre lpDestObj . Le paramètre lpInterface ne doit pas être null.

lpDestObj

[in] Pointeur vers l’objet pour recevoir les propriétés copiées ou déplacées.

ulFlags

[in] Masque de bits d’indicateurs qui contrôle l’opération de copie ou de déplacement. Les indicateurs suivants peuvent être définis :

MAPI_DECLINE_OK

Si CopyTo appelle la méthode IMAPISupport ::D oCopyTo pour gérer l’opération de copie ou de déplacement, elle doit retourner immédiatement avec la valeur d’erreur MAPI_E_DECLINE_COPY. L’indicateur MAPI_DECLINE_OK est défini par MAPI pour limiter la récursivité. Les clients ne définissent pas cet indicateur.

MAPI_DIALOG

Affiche un indicateur de progression.

MAPI_MOVE

CopyTo doit effectuer une opération de déplacement au lieu d’une opération de copie. Lorsque cet indicateur n’est pas défini, CopyTo effectue une opération de copie.

MAPI_NOREPLACE

Les propriétés existantes dans l’objet de destination ne doivent pas être remplacées. Lorsque cet indicateur n’est pas défini, CopyTo remplace les propriétés existantes.

lppProblems

[in, out] En entrée, pointeur vers un pointeur vers une structure SPropProblemArray ; sinon, null, indiquant qu’aucune information d’erreur n’est nécessaire. Si lppProblems est un pointeur valide en entrée, CopyTo renvoie des informations détaillées sur les erreurs de copie d’une ou plusieurs propriétés.

Valeur renvoyée

S_OK

Les propriétés ont été correctement copiées ou déplacées.

MAPI_E_COLLISION

Impossible de copier un sous-objet, car un sous-objet portant le même nom d’affichage (spécifié par la propriété PR_DISPLAY_NAME (PidTagDisplayName) existe déjà dans l’objet de destination.

MAPI_E_DECLINE_COPY

Le fournisseur de services n’implémente pas l’opération de copie.

MAPI_E_FOLDER_CYCLE

L’objet source effectuant l’opération de copie ou de déplacement contient directement ou indirectement l’objet de destination. Un travail important peut avoir été effectué avant la découverte de cette condition, de sorte que les objets source et de destination peuvent être partiellement modifiés.

MAPI_E_INTERFACE_NOT_SUPPORTED

L’interface identifiée par le paramètre lpInterface n’est pas prise en charge par l’objet de destination.

MAPI_E_NO_ACCESS

Une tentative d’accès à un objet pour lequel l’appelant dispose d’autorisations insuffisantes a été effectuée. Cette erreur est retournée si l’objet de destination est identique à l’objet source.

Les valeurs suivantes peuvent être retournées dans la structure SPropProblemArray , mais pas en tant que valeurs de retour pour CopyTo. Les erreurs suivantes s’appliquent à une seule propriété :

MAPI_E_BAD_CHARWIDTH

Soit l’indicateur MAPI_UNICODE a été défini et CopyTo ne prend pas en charge Unicode, soit MAPI_UNICODE n’a pas été défini et CopyTo prend uniquement en charge Unicode.

MAPI_E_COMPUTED

La propriété ne peut pas être modifiée par l’appelant, car il s’agit d’une propriété en lecture seule, calculée par le propriétaire de l’objet de destination. Cette erreur n’est pas grave ; l’appelant doit autoriser la poursuite de l’opération de copie.

MAPI_E_INVALID_TYPE

Le type de propriété n’est pas valide.

MAPI_E_UNEXPECTED_TYPE

Le type de propriété n’est pas le type attendu par l’appelant.

Remarques

Par défaut, la méthode IMAPIProp ::CopyTo copie ou déplace toutes les propriétés de l’objet actuel vers un objet de destination. CopyTo est utilisé lorsqu’un objet doit être copié ou déplacé exactement, avec la totalité ou la plupart de ses propriétés intactes.

Tous les sous-objets de l’objet source sont automatiquement inclus dans l’opération et sont copiés ou déplacés dans leur intégralité. Par défaut, CopyTo remplace toutes les propriétés de l’objet de destination qui correspondent aux propriétés de l’objet source. Si l’une des propriétés copiées ou déplacées existe déjà dans l’objet de destination, les propriétés existantes sont remplacées par les nouvelles propriétés, sauf si l’indicateur MAPI_NOREPLACE est défini dans le paramètre ulFlags . Les informations existantes de l’objet de destination qui ne sont pas remplacées restent inchangées.

Remarques pour les responsables de l’implémentation

Vous pouvez fournir une implémentation complète de CopyTo ou vous appuyer sur l’implémentation que MAPI fournit dans son objet de support. Si vous souhaitez utiliser l’implémentation MAPI, appelez IMAPISupport ::D oCopyTo. Toutefois, si vous effectuez un traitement délégué à DoCopyTo et que l’indicateur MAPI_DECLINE_OK vous est transmis, évitez l’appel de support et retournez MAPI_E_DECLINE_COPY à la place. MAPI appelle avec cet indicateur pour éviter la récursivité qui peut se produire lorsque des dossiers sont copiés.

Étant donné que l’opération de copie peut être longue, vous devez afficher un indicateur de progression. Utilisez l’implémentation IMAPIProgress passée dans le paramètre lpProgress , le cas échéant. Si lpProgress a la valeur null, appelez la méthode IMAPISupport ::D oProgressDialog pour utiliser l’implémentation MAPI.

N’essayez pas de définir des propriétés connues en lecture seule dans l’objet de destination ; retourner MAPI_E_NO_ACCESS à la place.

Les objets source et de destination doivent utiliser les mêmes interfaces. Retourne MAPI_E_INVALID_PARAMETER si lpInterface n’est pas défini.

Retourne MAPI_E_INTERFACE_NOT_SUPPORTED si toutes les interfaces connues sont exclues.

Remarques pour les appelants

Ne définissez pas l’indicateur MAPI_DECLINE_OK ; MAPI l’utilise dans ses appels aux implémentations CopyTo du fournisseur de magasin de messages.

Étant donné que les opérations de copie et de déplacement peuvent prendre du temps, vous devez demander l’affichage d’un indicateur de progression en définissant l’indicateur MAPI_DIALOG. Vous pouvez définir le paramètre lpProgress sur votre implémentation de IMAPIProgress, si vous en avez un, ou sur null. Si lpProgress a la valeur null, CopyTo utilise l’indicateur de progression par défaut fourni par MAPI.

Vous pouvez supprimer l’affichage d’un indicateur de progression en ne définissant pas l’indicateur MAPI_DIALOG. CopyTo ignore les paramètres ulUIParam et lpProgress et n’affiche pas l’indicateur.

CopyTo peut signaler des erreurs globales et individuelles, ou des erreurs qui se produisent avec une ou plusieurs propriétés. Ces erreurs individuelles sont placées dans une structure SPropProblemArray . Vous pouvez supprimer le rapport d’erreurs au niveau de la propriété en passant null, au lieu d’un pointeur valide, pour le paramètre de structure du tableau de problèmes de propriété.

Si vous souhaitez recevoir des informations sur les erreurs, transmettez un pointeur de structure SPropProblemArray valide dans le paramètre lppProblems . Lorsque CopyTo retourne S_OK, case activée d’éventuelles erreurs avec des propriétés individuelles dans la structure. Lorsque CopyTo renvoie une erreur, aucune information n’est retournée dans la structure SPropProblemArray . Au lieu de cela, appelez IMAPIProp ::GetLastError pour récupérer des informations d’erreur détaillées.

Si CopyTo renvoie S_OK, libérez la structure SPropProblemArray retournée en appelant la fonction MAPIFreeBuffer .

Si vous copiez des propriétés propres au type d’objet source, vous devez vous assurer que l’objet de destination est du même type. CopyTo ne vous empêche pas d’associer des propriétés qui appartiennent généralement à un type d’objet à un autre type d’objet. C’est à vous de copier les propriétés qui sont pertinentes pour l’objet de destination. Par exemple, vous ne devez pas copier les propriétés de message dans un conteneur de carnet d’adresses.

Pour vous assurer que vous copiez entre des objets du même type, case activée que l’objet source et l’objet de destination sont du même type, soit en comparant des pointeurs d’objet, soit en appelant IUnknown ::QueryInterface. Définissez l’identificateur d’interface vers lequel lpInterface pointe vers l’interface standard de l’objet source. Vérifiez également que le type d’objet ou la propriété PR_OBJECT_TYPE (PidTagObjectType) est identique pour les deux objets. Par exemple, si vous copiez à partir d’un message, définissez lpInterface sur IID_IMessage et le PR_OBJECT_TYPE pour les deux objets à MAPI_MESSAGE.

Si un pointeur non valide est passé dans le paramètre lpDestObj , les résultats sont imprévisibles.

L’exclusion de propriétés sur un appel CopyTo peut être utile. Par exemple, certains objets ont des propriétés spécifiques à un seul instance de l’objet, telles que la date et l’heure de remise du message. Pour éviter de copier l’heure de remise d’un message lorsque vous copiez le message dans un autre dossier, spécifiez PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) dans le tableau d’exclusion de balise de propriété. Pour exclure la liste des destinataires d’un message, ajoutez la propriété PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) au tableau d’exclusion. Pour exclure les pièces jointes d’un message, ajoutez la propriété PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) au tableau.

De même, empêchez la copie ou le déplacement de la hiérarchie ou de la table de contenu d’un conteneur de dossiers ou de carnets d’adresses en incluant PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) ou PR_CONTAINER_CONTENTS (PidTagContainerContents) dans le tableau d’exclusion de balise de propriété.

Pour exclure les propriétés de l’opération de copie ou de déplacement, incluez leurs balises de propriété dans le paramètre lpExcludeProps . Si vous transmettez les résultats de la macro PROP_TAG pour générer une balise de propriété à partir d’un identificateur spécifique dans le tableau de balises de propriété, toutes les propriétés avec cet identificateur seront exclues. Par exemple, l’entrée suivante dans le tableau de balises de propriétés entraîne l’exclusion de toutes les propriétés dont l’identificateur est 0x8002, quel que soit le type :

PROP_TAG(PT_LONG, 0x8002)

La balise de propriété PR_NULL (PidTagNull) ne peut pas être incluse dans le tableau lpExcludeProps .

L’utilité de la fonctionnalité CopyTo pour exclure des interfaces n’est peut-être pas aussi évidente que l’utilité d’exclure des propriétés. Vous pouvez exclure une interface lorsque vous copiez vers un objet qui n’a aucune connaissance d’un groupe de propriétés. Par exemple, si vous copiez des propriétés d’un dossier vers une pièce jointe, les seules propriétés que la pièce jointe peut utiliser sont les propriétés génériques disponibles avec toute implémentation IMAPIProp . En excluant IMAPIFolder de l’opération de copie, la pièce jointe ne recevra aucune des propriétés de dossier les plus spécifiques.

Lorsque vous utilisez le paramètre rgiidExclude pour exclure une interface, il exclut également toutes les interfaces dérivées de cette interface. Par exemple, l’exclusion d’IMAPIContainer entraîne l’exclusion des dossiers ou des conteneurs de carnets d’adresses, en fonction du type de fournisseur. N’excluez pas IMAPIProp ou IUnknown , car de nombreuses interfaces en dérivent.

Ignorez MAPI_E_COMPUTED erreurs retournées dans la structure SPropProblemArray dans le paramètre lppProblems .

Référence MFCMAPI

Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.

Fichier	Fonction	Commentaire
File.cpp	LoadFromMSG	MFCMAPI utilise la méthode IMAPIProp ::CopyTo pour copier les propriétés d’un fichier .msg vers un objet IMAPIMessageSite .
FolderDlg.cpp	CFolderDlg ::HandlePaste	MFCMAPI utilise la méthode IMAPIProp ::CopyTo pour copier les propriétés d’un message source vers un message cible pendant une opération de collage.