IMAPISupport::DoCopyTo

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

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

HRESULT DoCopyTo(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  ULONG ciidExclude,
  LPCIID rgiidExclude,
  LPSPropTagArray lpExcludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Paramètres

lpSrcInterface

[in] Pointeur vers l’identificateur d’interface (IID) qui représente l’interface à utiliser pour accéder à l’objet qui a les propriétés à copier ou déplacer.

lpSrcObj

[in] Pointeur vers l’objet qui a les propriétés à copier ou déplacer.

ciidExclude

[in] Nombre d’interfaces à exclure lorsque vous copiez ou déplacez des propriétés.

rgiidExclude

[in] Tableau d’identificateurs d’interface qui indique les interfaces qui ne doivent pas être utilisées lorsque vous copiez ou déplacez des informations supplémentaires 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. La transmission de la valeur NULL dans le paramètre lpExcludeProps indique que toutes les propriétés de l’objet doivent être copiées ou déplacées. DoCopyTo renvoie MAPI_E_INVALID_PARAMETER lorsque le membre cValues de la structure SPropTagArray 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 .

lpDestInterface

[in] Pointeur vers l’identificateur d’interface qui représente l’interface à utiliser pour accéder à l’objet afin de recevoir les propriétés copiées ou déplacées.

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_DIALOG

Affiche un indicateur de progression.

MAPI_MOVE

DoCopyTo doit effectuer une opération de déplacement au lieu d’une opération de copie. Lorsque cet indicateur n’est pas défini, DoCopyTo 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, DoCopyTo remplace les propriétés existantes.

lppProblems

[out] En entrée, pointeur vers un pointeur vers une structure SPropProblemArray ; sinon, NULL, ce qui indique qu’aucune information d’erreur n’est nécessaire. Si lppProblems est un pointeur valide en entrée, DoCopyTo retourne 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

Une propriété à copier ou déplacer existe déjà dans l’objet de destination et l’indicateur MAPI_NOREPLACE est défini.

MAPI_E_FOLDER_CYCLE

L’objet source 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 lpSrcInterface n’est pas prise en charge par l’objet pointé par lpSrcObj, ou l’interface identifiée par le paramètre lpDestInterface n’est pas prise en charge par l’objet pointé par lpDestObj.

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.

MAPI_E_INVALID_PARAMETER

Le paramètre lpSrcInterface est NULL.

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

MAPI_E_BAD_CHARWIDTH

L’indicateur MAPI_UNICODE a été défini et DoCopyTo ne prend pas en charge Unicode, ou MAPI_UNICODE n’a pas été défini et DoCopyTo 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

La méthode IMAPISupport ::D oCopyTo est implémentée pour les objets de prise en charge du fournisseur de magasins de messages. Les fournisseurs de magasins de messages peuvent appeler DoCopyTo pour implémenter la méthode IMAPIProp ::CopyTo pour leurs dossiers et messages.

Par défaut, DoCopyTo copie ou déplace toutes les propriétés d’un objet vers un autre objet. Tous les sous-objets de l’objet source sont automatiquement inclus dans l’opération et copiés ou déplacés dans leur intégralité.

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 appelants

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 l’utilisation 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)

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, pour empêcher la copie ou le déplacement de la hiérarchie ou de la table de contenu d’un conteneur de dossier ou de carnet d’adresses, incluez PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) ou PR_CONTAINER_CONTENTS (PidTagContainerContents) dans le tableau d’exclusion de balise de propriété.

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

L’identificateur d’interface vers lequel pointe lpSrcInterface est généralement le même que l’identificateur d’interface vers lequel pointe lpDestInterface .

Si vous passez un identificateur d’interface acceptable dans lpDestInterface mais un pointeur non valide dans lpDestObj, les résultats sont imprévisibles. Il est fort probable que cela entraîne l’échec de votre fournisseur.

À l’inverse, si vous connaissez des informations supplémentaires qui ne doivent pas être copiées ou déplacées, ajoutez les identificateurs d’interface pour les interfaces à exclure dans le tableau passé dans le paramètre rgiidExclude . Par exemple, si vous copiez des messages, mais pas l’une de leurs pièces jointes, passez IID_IMessage dans le tableau rgiidExclude . DoCopyTo ignore toutes les interfaces répertoriées dans rgiidExclude qu’il ne reconnaît pas.

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 de l’interface 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.

DoCopyTo signale les erreurs globales qui s’appliquent à l’opération dans son ensemble et les erreurs individuelles qui s’appliquent aux propriétés individuelles. Ces erreurs individuelles sont placées dans une structure SPropProblemArray . Vous pouvez supprimer le rapport d’erreurs au niveau de la propriété en transmettant NULL, plutôt qu’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 DoCopyTo retourne S_OK, case activée d’éventuelles erreurs avec des propriétés individuelles dans la structure. Lorsque DoCopyTo retourne une erreur, aucune information n’est retournée dans la structure SPropProblemArray . Au lieu de cela, appelez la méthode IMAPISupport ::GetLastError pour récupérer des informations d’erreur détaillées.

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

Si une erreur globale se produit sur l’appel DoCopyTo , n’utilisez pas ou ne libérez pas la structure SPropProblemArray . Les fournisseurs doivent ignorer le membre ulIndex dans les structures SPropProblemArray retournées par DoCopyTo.