IMAPIFolder::CopyMessages
S’applique à : Outlook 2013 | Outlook 2016
Copie ou déplace un ou plusieurs messages.
HRESULT CopyMessages(
LPENTRYLIST lpMsgList,
LPCIID lpInterface,
LPVOID lpDestFolder,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
Paramètres
lpMsgList
[in] Pointeur vers un tableau de structures ENTRYLIST qui identifient le ou les messages à copier ou déplacer.
lpInterface
[in] Pointeur vers l’identificateur d’interface (IID) qui représente l’interface à utiliser pour accéder au dossier de destination vers lequel pointe le paramètre lpDestFolder . La transmission de la valeur NULL entraîne le retour par le fournisseur de services de l’interface de dossier standard, IMAPIFolder : IMAPIContainer. Les clients doivent passer la valeur NULL. D’autres appelants peuvent définir le paramètre lpInterface sur IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer ou IID_IMAPIFolder.
lpDestFolder
[in] Pointeur vers le dossier ouvert pour recevoir les messages copiés ou déplacés.
ulUIParam
[in] Handle de la fenêtre parente de toutes les boîtes de dialogue ou fenêtres affichées par cette méthode. Le paramètre ulUIParam est ignoré, sauf si le client définit l’indicateur MESSAGE_DIALOG dans le paramètre ulFlags et passe NULL dans le paramètre lpProgress .
lpProgress
[in] Pointeur vers un objet progress qui affiche un indicateur de progression. Si NULL est passé dans lpProgress, le fournisseur de magasin de messages affiche un indicateur de progression à l’aide de l’implémentation de l’objet de progression MAPI. Le paramètre lpProgress est ignoré, sauf si l’indicateur MESSAGE_DIALOG est défini dans ulFlags.
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_DECLINE_OK
Indique au fournisseur de magasin de messages de retourner immédiatement MAPI_E_DECLINE_COPY s’il implémente IMAPIFolder ::CopyMessages en appelant la méthode IMAPISupport ::D oCopyTo ou IMAPISupport ::D oCopyProps de l’objet de support.
MESSAGE_DIALOG
Affiche un indicateur de progression à mesure que l’opération se poursuit.
MESSAGE_MOVE
Le ou les messages doivent être déplacés au lieu d’être copiés. Si MESSAGE_MOVE n’est pas défini, les messages sont copiés.
Valeur renvoyée
S_OK
Le ou les messages ont été correctement copiés ou déplacés.
MAPI_E_DECLINE_COPY
Le fournisseur implémente cette méthode en appelant une méthode d’objet de support, et l’appelant a passé l’indicateur MAPI_DECLINE_OK.
MAPI_W_PARTIAL_COMPLETION
L’appel a réussi, mais toutes les entrées n’ont pas été correctement copiées ou déplacées. Lorsque cet avertissement est retourné, l’appel doit être géré comme ayant réussi. Pour tester cet avertissement, utilisez la macro HR_FAILED . Pour plus d’informations, consultez Utilisation de macros pour la gestion des erreurs.
Remarques
La méthode IMAPIFolder ::CopyMessages copie ou déplace les messages vers un autre dossier.
Les messages ouverts avec l’autorisation de lecture/écriture peuvent être déplacés ou copiés.
Remarques pour les responsables de l’implémentation
Si vous copiez des messages vers une autre banque de messages sans utiliser la méthode IMAPISupport ::CopyMessages , vous devez d’abord appeler IMAPIFolder ::SetReadFlags avec l’indicateur GENERATE_RECEIPT_ONLY défini. La banque de messages de réception n’est pas responsable de la génération de rapports de lecture pour les messages copiés ou déplacés. Si vous appelez IMAPISupport ::CopyMessages pour implémenter IMAPIFolder ::CopyMessages, n’appelez pas SetReadFlags ; MAPI l’appellera.
Votre implémentation peut déplacer ou copier les messages dans n’importe quel ordre et générer des rapports de lecture status dans n’importe quel ordre. Autrement dit, vous pouvez terminer la copie des messages avant de générer l’un des rapports de status en lecture ou envoyer les rapports avant que votre implémentation commence l’opération de copie. Toutefois, des rapports de lecture doivent être envoyés pour que tous les messages soient copiés, que la copie soit réussie ou non.
Lorsque l’opération de copie ou de déplacement implique plusieurs messages, effectuez l’opération aussi complètement que possible. N’arrêtez pas l’opération prématurément, sauf si une défaillance indépendante de votre contrôle se produit, telle qu’une insuffisance de mémoire, un manque d’espace disque ou une altération dans la banque de messages.
Essayez de conserver les identificateurs d’entrée dans les opérations de déplacement ou de copie. Vous devez également conserver les identificateurs d’entrée, bien que cela ne soit pas obligatoire.
Envoyez des notifications lorsque vous déplacez ou copiez des messages afin que les clients soient avertis que leurs appels aux méthodes IMAPIProp ::SaveChanges des messages peuvent échouer.
N’incluez pas les status d’un message dans l’opération de copie ou de déplacement. Le déplacement ou la copie d’un message status affecte considérablement les performances.
Remarques pour les appelants
Utilisez IMAPIFolder ::CopyMessages pour remplir les dossiers de résultats de recherche, où les messages sont souvent regroupés par dossier parent.
Attendez-vous à ces valeurs de retour dans les conditions suivantes.
| Condition | Valeur renvoy�e |
|---|---|
| IMAPIFolder ::CopyMessages a correctement copié ou déplacé chaque message. | S_OK |
| IMAPIFolder ::CopyMessages n’a pas pu copier ou déplacer correctement chaque message. | MAPI_W_PARTIAL_COMPLETION |
| IMAPIFolder ::CopyMessages n’a pas pu se terminer. | Toute valeur d’erreur |
Lorsque IMAPIFolder ::CopyMessages ne peut pas se terminer, ne supposez pas qu’aucun travail n’a été effectué. IMAPIFolder ::CopyMessages a peut-être pu copier ou déplacer un ou plusieurs messages avant de rencontrer l’erreur.