IMAPIFolder::CreateFolder
S’applique à : Outlook 2013 | Outlook 2016
Crée un sous-dossier.
HRESULT CreateFolder(
ULONG ulFolderType,
LPSTR lpszFolderName,
LPSTR lpszFolderComment,
LPCIID lpInterface,
ULONG ulFlags,
LPMAPIFOLDER FAR * lppFolder
);
Paramètres
ulFolderType
[in] Type de dossier à créer. Les indicateurs suivants peuvent être définis :
FOLDER_GENERIC
Un dossier générique doit être créé.
FOLDER_SEARCH
Un dossier search-results doit être créé.
lpszFolderName
[in] Pointeur vers une chaîne qui contient le nom du nouveau dossier. Ce nom est la base de la propriété PR_DISPLAY_NAME (PidTagDisplayName) du nouveau dossier.
lpszFolderComment
[in] Pointeur vers une chaîne qui contient un commentaire associé au nouveau dossier. Cette chaîne devient la valeur de la propriété PR_COMMENT (PidTagComment) du nouveau dossier. Si null est passé, le dossier n’a pas de commentaire initial.
lpInterface
[in] Pointeur vers l’identificateur d’interface (IID) qui représente l’interface à utiliser pour accéder au nouveau dossier. La transmission de la valeur NULL entraîne le retour 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.
ulFlags
[in] Masque de bits d’indicateurs qui contrôle la façon dont le dossier est créé. Les indicateurs suivants peuvent être définis :
MAPI_DEFERRED_ERRORS
Permet à CreateFolder de retourner correctement, éventuellement avant que le nouveau dossier ne soit entièrement disponible pour le client appelant. Si le nouveau dossier n’est pas disponible, un appel ultérieur peut entraîner une erreur.
MAPI_UNICODE
Le nom du dossier est au format Unicode. Si l’indicateur MAPI_UNICODE n’est pas défini, le nom du dossier est au format ANSI.
OPEN_IF_EXISTS
Permet à la méthode de réussir même si le dossier nommé dans le paramètre lpszFolderName existe déjà en ouvrant le dossier existant portant ce nom. Notez que les fournisseurs de magasins de messages qui autorisent les dossiers frères à avoir le même nom peuvent ne pas ouvrir un dossier existant s’il en existe plusieurs avec le nom fourni.
lppFolder
[out] Pointeur vers un pointeur vers le dossier nouvellement créé.
Valeur renvoyée
S_OK
Le nouveau dossier a été créé ou ouvert si l’indicateur OPEN_IF_EXISTS est défini.
MAPI_E_BAD_CHARWIDTH
Soit l’indicateur MAPI_UNICODE a été défini et l’implémentation ne prend pas en charge Unicode, soit MAPI_UNICODE n’a pas été défini et l’implémentation prend uniquement en charge Unicode.
MAPI_E_COLLISION
Un dossier dont le nom est donné dans le paramètre lpszFolderName existe déjà. Les noms de dossiers doivent être uniques.
Remarques
La méthode IMAPIFolder ::CreateFolder crée un sous-dossier dans le dossier actif et affecte un identificateur d’entrée au nouveau dossier.
Remarques pour les appelants
Lorsque CreateFolder est retourné, n’oubliez pas que l’identificateur d’entrée du nouveau dossier n’est peut-être pas disponible. Certains fournisseurs de magasins de messages ne rendent pas les identificateurs d’entrée disponibles tant que vous n’avez pas appelé la méthode IMAPIProp ::SaveChanges du nouveau dossier pour l’enregistrer définitivement. Cela est particulièrement vrai si vous avez défini l’indicateur MAPI_DEFERRED_ERRORS.
N’oubliez pas que certains fournisseurs de magasins de messages pointent toujours le paramètre lppFolder vers l’interface standard du dossier, quelle que soit la valeur que vous transmettez pour le paramètre lpInterface . Étant donné que le pointeur d’interface retourné n’est peut-être pas du type attendu, appelez la méthode IMAPIProp ::GetProps du nouveau dossier pour récupérer la propriété PR_OBJECT_TYPE (PidTagObjectType). Si nécessaire, convertissez le pointeur vers un type plus approprié avant d’effectuer d’autres appels.
La plupart des fournisseurs de magasins de messages exigent que le nom du nouveau dossier soit unique par rapport aux noms de ses dossiers frères. Être en mesure de gérer la valeur d’erreur MAPI_E_COLLISION, qui est retournée si cette règle n’est pas suivie.
Pour déterminer l’identificateur d’entrée du dossier nouvellement créé, appelez la méthode IMAPIProp ::GetProps du nouveau dossier pour récupérer sa propriété PR_ENTRYID (PidTagEntryId).
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| MsgStoreDlg.cpp |
CMsgStoreDlg ::OnCreateSubFolder |
MFCMAPI utilise la méthode CMsgStoreDlg ::OnCreateSubFolder pour créer des dossiers dans MFCMAPI. |