IMAPIFolder::CopyFolder
S’applique à : Outlook 2013 | Outlook 2016
Copie ou déplace un sous-dossier.
HRESULT CopyFolder(
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
LPVOID lpDestFolder,
LPSTR lpszNewFolderName,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
Paramètres
cbEntryID
[in] Nombre d’octets dans l’identificateur d’entrée vers lequel pointe le paramètre lpEntryID .
lpEntryID
[in] Pointeur vers l’identificateur d’entrée du sous-dossier à copier ou déplacer.
lpInterface
[in] Pointeur vers l’identificateur d’interface (IID) qui représente l’interface à utiliser pour accéder au dossier vers lequel pointe le paramètre lpDestFolder . La transmission de la valeur NULL amène le fournisseur de services à retourner l’interface de dossier standard, IMAPIFolder : IMAPIContainer. Les valeurs valides pour lpInterface sont IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer et IID_IMAPIFolder.
lpDestFolder
[in] Pointeur vers le dossier ouvert pour recevoir le sous-dossier copié ou déplacé.
lpszNewFolderName
[in] Pointeur vers le nom du dossier copié ou déplacé dans sa nouvelle destination. Si lpszNewFolderName est défini sur NULL, le nom du sous-dossier source est utilisé pour le nom du dossier de destination.
ulUIParam
[in] Handle de la fenêtre parente de l’indicateur de progression. Le paramètre ulUIParam est ignoré, sauf si l’indicateur FOLDER_DIALOG dans le paramètre ulFlags est défini.
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 FOLDER_DIALOG est défini dans ulFlags.
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 :
COPY_SUBFOLDERS
Tous les sous-dossiers du sous-dossier à copier doivent également être copiés. Lorsque COPY_SUBFOLDERS n’est pas défini pour une opération de copie, seul le sous-dossier identifié par lpEntryID est copié. Avec une opération de déplacement, le comportement COPY_SUBFOLDERS est le comportement par défaut, que l’indicateur soit défini ou non.
FOLDER_DIALOG
Demande l’affichage d’un indicateur de progression.
FOLDER_MOVE
Le sous-dossier doit être déplacé au lieu d’être copié. Si FOLDER_MOVE n’est pas défini, le sous-dossier est copié.
MAPI_DECLINE_OK
Informe le fournisseur de magasin de messages que s’il implémente CopyFolder en appelant la méthode IMAPISupport ::D oCopyTo ou IMAPISupport ::D oCopyProps de son objet de support, CopyFolder doit retourner immédiatement MAPI_E_DECLINE_COPY.
MAPI_UNICODE
Le nom du dossier de destination est au format Unicode. Si l’indicateur MAPI_UNICODE n’est pas défini, le nom du dossier est au format ANSI.
Valeur renvoyée
S_OK
Le dossier spécifié a été correctement copié ou déplacé.
MAPI_E_BAD_CHARWIDTH
L’indicateur MAPI_UNICODE a été défini et le fournisseur de magasin de messages ne prend pas en charge Unicode, ou MAPI_UNICODE n’a pas été défini et le fournisseur de la banque de messages prend uniquement en charge Unicode.
MAPI_E_COLLISION
Le nom du dossier déplacé ou copié est le même que celui d’un sous-dossier dans le dossier de destination. Le fournisseur de magasin de messages nécessite des noms de dossiers uniques.
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_E_FOLDER_CYCLE
Le dossier source contient directement ou indirectement le dossier de destination. Un travail important peut avoir été effectué avant la découverte de cette condition, de sorte que le dossier source et de destination peut être partiellement modifié.
MAPI_W_PARTIAL_COMPLETION
L’appel a réussi, mais toutes les entrées n’ont pas été copiées avec succès. 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 ::CopyFolder copie ou déplace un sous-dossier d’un emplacement à un autre. Le sous-dossier copié ou déplacé est ajouté au dossier de destination en tant que sous-dossier.
Remarques pour les responsables de l’implémentation
Lorsque l’opération de copie ou de déplacement implique plusieurs dossiers, comme indiqué en définissant l’indicateur COPY_SUBFOLDERS, effectuez l’opération aussi complètement que possible pour chaque dossier. Parfois, l’un des dossiers à déplacer ou à copier n’existe pas ou a déjà été déplacé ou copié ailleurs. 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 tous les identificateurs d’entrée de message dans les messages copiés. Vous devez également essayer de conserver les identificateurs d’entrée, mais cela n’est pas obligatoire.
Remarques pour les appelants
Attendez-vous à ces valeurs de retour dans les conditions suivantes.
| Condition | Valeur renvoy�e |
|---|---|
| CopyFolder a correctement copié ou déplacé chaque message et sous-dossier. | S_OK |
| CopyFolder n’a pas pu copier ou déplacer correctement chaque message et sous-dossier. | MAPI_W_PARTIAL_COMPLETION ou MAPI_E_NOT_FOUND |
| CopyFolder n’a pas pu se terminer. | Toute valeur d’erreur à l’exception de MAPI_E_NOT_FOUND |
Lorsque CopyFolder ne peut pas se terminer, ne supposez pas qu’aucun travail n’a été effectué. CopyFolder a peut-être pu copier ou déplacer un ou plusieurs des messages et sous-dossiers avant de rencontrer l’erreur.
Si un identificateur d’entrée pour un dossier qui n’existe pas est passé dans lpEntryID, CopyFolder retourne MAPI_W_PARTIAL_COMPLETION ou MAPI_E_NOT_FOUND, en fonction de l’implémentation de la banque de messages.
Selon le fournisseur de magasin de messages, l’identificateur d’entrée du message d’origine peut ou non être conservé dans le message copié. Vous devez conserver les identificateurs d’entrée dans la mesure du possible, mais ce n’est pas obligatoire. Vous pouvez généralement dépendre des scénarios suivants :
Lorsque vous déplacez un dossier entre deux types différents de magasins de messages, il est garanti que l’identificateur d’entrée change.
Lorsque vous déplacez un dossier entre deux banques de messages du même type, l’identificateur d’entrée change presque toujours.
Lorsque vous déplacez un dossier vers un autre emplacement dans la même banque de messages, l’identificateur d’entrée peut ou non changer, en fonction du fournisseur de la banque de messages.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| MsgStoreDlg.cpp |
CMsgStoreDlg ::OnPasteFolder |
MFCMAPI utilise la méthode IMAPIFolder ::CopyFolder pour copier des dossiers d’un emplacement à un autre. MFCMAPI mémorise le dossier source pendant l’opération de copie et effectue la copie pendant l’opération de collage. |