IMAPISupport::DoCopyProps

Article
08/18/2023

S’applique à : Outlook 2013 | Outlook 2016

Copie ou déplace une ou plusieurs propriétés d’un objet vers un autre objet.

HRESULT DoCopyProps(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  LPSPropTagArray lpIncludeProps,
  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 avec les propriétés à copier ou à déplacer.

lpSrcObj

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

lpIncludeProps

[in] Pointeur vers une structure SPropTagArray qui contient un tableau compté de balises de propriété qui indiquent les propriétés à copier ou déplacer. Le paramètre lpIncludeProps ne peut pas être NULL.

ulUIParam

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

lpProgress

[in] Pointeur vers une implémentation d’un indicateur de progression. Si NULL est passé dans le paramètre lpProgress , l’indicateur de progression s’affiche à l’aide de l’implémentation MAPI. 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 qui sont 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 la façon dont l’opération de copie ou de déplacement est effectuée. Les indicateurs suivants peuvent être définis :

MAPI_DIALOG

Affiche un indicateur de progression.

MAPI_MOVE

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

lppProblems

[in, 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, DoCopyProps retourne des informations détaillées sur les erreurs lors de la 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 source, ou l’interface identifiée par le paramètre lpDestInterface 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 DoCopyProps. Ces erreurs s’appliquent à une seule propriété.

MAPI_E_BAD_CHARWIDTH

Soit l’indicateur MAPI_UNICODE a été défini et DoCopyProps ne prend pas en charge Unicode, soit MAPI_UNICODE n’a pas été défini et DoCopyProps 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 oCopyProps 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 DoCopyProps pour implémenter la méthode IMAPIProp ::CopyProps pour leurs dossiers et messages. DoCopyProps copie ou déplace les propriétés identifiées dans le tableau de balises de propriétés pointées par lpIncludeProps et présentes dans l’objet pointé par lpSrcObj.

Remarques pour les appelants

Lorsque vous copiez des propriétés entre des objets du même type, tels que deux messages, les paramètres lpSrcInterface et lpDestInterface doivent contenir le même identificateur d’interface, et les paramètres lpSrcObj et lpDestObj doivent pointer vers des objets du même type. Si lpDestInterface est défini sur NULL, DoCopyProps renvoie MAPI_E_INVALID_PARAMETER. Si vous définissez lpDestInterface sur un identificateur d’interface acceptable, mais que vous définissez lpDestObj sur un pointeur non valide, les résultats sont imprévisibles. Il est fort probable que votre fournisseur échoue.

Définissez l’indicateur MAPI_NOREPLACE si vous ne souhaitez pas remplacer l’une des propriétés de l’objet de destination. Les propriétés de l’objet de destination qui existent dans l’objet source et qui ne sont pas remplacées ne sont pas supprimées ou modifiées.

Pour copier la liste des destinataires d’un message, incluez la propriété PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) dans le tableau de balises de propriété vers lequel pointe le paramètre lpIncludeProps . Pour copier les pièces jointes du message, incluez la propriété PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments).

Pour copier la hiérarchie ou 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 de balises de propriétés. Pour inclure la table de contenu associée à un dossier, incluez la propriété PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) dans le tableau.

Si des sous-dossiers sont copiés ou déplacés, leur contenu est copié ou déplacé dans leur intégralité, quelle que soit l’utilisation des propriétés indiquées par la structure SPropTagArray .

DoCopyProps signale les erreurs globales qui se produisent avec l’opération dans son ensemble et les erreurs individuelles 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 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 DoCopyProps retourne S_OK, case activée d’erreurs possibles avec des propriétés individuelles dans la structure. Lorsque DoCopyProps 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 DoCopyProps renvoie S_OK, libérez la structure SPropProblemArray retournée en appelant la fonction MAPIFreeBuffer .