IMAPIFolder::CreateFolder
Область применения: Outlook 2013 | Outlook 2016
Создает новую вложенную папку.
HRESULT CreateFolder(
ULONG ulFolderType,
LPSTR lpszFolderName,
LPSTR lpszFolderComment,
LPCIID lpInterface,
ULONG ulFlags,
LPMAPIFOLDER FAR * lppFolder
);
Параметры
ulFolderType
[в] Тип создаваемой папки. Можно задать следующие флаги:
FOLDER_GENERIC
Необходимо создать общую папку.
FOLDER_SEARCH
Необходимо создать папку результатов поиска.
lpszFolderName
[в] Указатель на строку, содержащую имя новой папки. Это имя является основой для свойства PR_DISPLAY_NAME новой папки (PidTagDisplayName).
lpszFolderComment
[в] Указатель на строку, содержащую комментарий, связанный с новой папкой. Эта строка становится значением свойства PR_COMMENT (PidTagComment) новой папки. Если передается значение NULL, в папке нет начального комментария.
lpInterface
[в] Указатель на идентификатор интерфейса (IID), представляющий интерфейс, используемый для доступа к новой папке. Передача NULL приводит к тому, что поставщик хранилища сообщений возвращает стандартный интерфейс папок IMAPIFolder : IMAPIContainer. Клиенты должны передавать значение NULL. Другие вызывающие могут задать для параметра lpInterface значение IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer или IID_IMAPIFolder.
ulFlags
[в] Битовая маска флагов, управляющая созданием папки. Можно задать следующие флаги:
MAPI_DEFERRED_ERRORS
Позволяет CreateFolder успешно вернуться, возможно, до того, как новая папка будет полностью доступна вызывающей папке. Если новая папка недоступна, последующий вызов может вызвать ошибку.
MAPI_UNICODE
Имя папки имеет формат Юникода. Если флаг MAPI_UNICODE не задан, имя папки будет в формате ANSI.
OPEN_IF_EXISTS
Позволяет методу успешно выполняться, даже если папка с именем в параметре lpszFolderName уже существует, открыв существующую папку с таким именем. Обратите внимание, что поставщики хранилища сообщений, разрешающие одноуровневым папкам иметь одно и то же имя, могут не открывать существующую папку, если существует несколько папок с указанными именами.
lppFolder
[out] Указатель на указатель на только что созданную папку.
Возвращаемое значение
S_OK
Новая папка успешно создана или открыта, если установлен флаг OPEN_IF_EXISTS.
MAPI_E_BAD_CHARWIDTH
Либо был установлен флаг MAPI_UNICODE и реализация не поддерживает Юникод, либо MAPI_UNICODE не задан и реализация поддерживает только Юникод.
MAPI_E_COLLISION
Папка с именем, указанным в параметре lpszFolderName , уже существует. Имена папок должны быть уникальными.
Замечания
Метод IMAPIFolder::CreateFolder создает вложенную папку в текущей папке и назначает идентификатор записи новой папке.
Примечания для вызывающих методов
Когда Функция CreateFolder возвращается, имейте в виду, что идентификатор записи для новой папки может быть недоступен. Некоторые поставщики хранилища сообщений не делают идентификаторы записей доступными до тех пор, пока вы не вызовете метод IMAPIProp::SaveChanges новой папки, чтобы окончательно сохранить его. Это особенно верно, если вы установили флаг MAPI_DEFERRED_ERRORS.
Имейте в виду, что некоторые поставщики хранилища сообщений всегда указывают параметр lppFolder на стандартный интерфейс папки, независимо от значения, передаваемого для параметра lpInterface . Так как возвращаемый указатель интерфейса может не иметь ожидаемого типа, вызовите метод IMAPIProp::GetProps новой папки, чтобы получить свойство PR_OBJECT_TYPE (PidTagObjectType). При необходимости приведите указатель к более подходящему типу, прежде чем выполнять другие вызовы.
Большинство поставщиков хранилища сообщений требуют, чтобы имя новой папки было уникальным по отношению к именам одноуровневых папок. Будьте в состоянии обрабатывать значение ошибки MAPI_E_COLLISION, которое возвращается, если это правило не соблюдается.
Чтобы определить идентификатор записи новой папки, вызовите метод IMAPIProp::GetProps новой папки, чтобы получить ее свойство PR_ENTRYID (PidTagEntryId).
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| MsgStoreDlg.cpp |
CMsgStoreDlg::OnCreateSubFolder |
MFCMAPI использует метод CMsgStoreDlg::OnCreateSubFolder для создания новых папок в MFCMAPI. |