IMAPIFolder::CreateFolder

The IMAPIFolder::CreateFolder method creates a new subfolder.

Quick Info

HRESULT CreateFolder(
  ULONG ulFolderType,         
  LPTSTR lpszFolderName,      
  LPTSTR lpszFolderComment,   
  LPCIID lpInterface,         
  ULONG ulFlags,              
  LPMAPIFOLDER FAR * lppFolder  
);

Parameters

ulFolderType

[in] The type of folder to create. One of the following values can be passed:

FOLDER_GENERIC: A generic folder should be created.
FOLDER_SEARCH: A search-results folder should be created.

lpszFolderName

[in] Pointer to a string containing the name for the new folder. This name is the basis for the new folder's PR_DISPLAY_NAME property.

lpszFolderComment

[in] Pointer to a string containing a comment associated with the new folder. This string becomes the value of the new folder's PR_COMMENT property. If NULL is passed, the folder has no initial comment.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the new folder. Passing NULL results in the message store provider returning the standard folder interface, IMAPIFolder. Clients must pass NULL. Other callers can set the lpInterface parameter to IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

ulFlags

[in] Bitmask of flags that controls how the folder is created. The following flags can be set:

MAPI_DEFERRED_ERRORS: Allows CreateFolder to return successfully, possibly before the new folder is fully accessible to the calling client. If the new folder is not accessible, making a subsequent call to it can result in an error.
MAPI_UNICODE: The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.
OPEN_IF_EXISTS: Allows the method to succeed — even if the folder named in the lpszFolderName parameter already exists — by opening the existing folder with that name. Note that message store providers that allow sibling folders to have the same name might fail to open an existing folder if more than one exists with the supplied name.

lppFolder

[out] Pointer to a pointer to the newly created folder.

Return Values

S_OK: The new folder has been successfully created or opened, if the OPEN_IF_EXISTS flag is set.
MAPI_E_BAD_CHARWIDTH: Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
MAPI_E_COLLISION: A folder with the name given in the lpszFolderName parameter already exists. Folder names must be unique.

Remarks

The IMAPIFolder::CreateFolder method creates a subfolder in the current folder and assigns an entry identifier to the new folder.

Notes to Callers

When CreateFolder returns, be aware that the entry identifier for the new folder might not be available. Some message store providers do not make entry identifiers available until after you have called the new folder's IMAPIProp::SaveChanges method to permanently save it. This is especially true if you have set the MAPI_DEFERRED_ERRORS flag.

Be aware that some message store providers always point lppFolder to the folder's standard interface, regardless of the value that you pass in for the lpInterface parameter. Because the interface pointer that is returned might not be of the type that you expect, call the new folder's IMAPIProp::GetProps method to retrieve the PR_OBJECT_TYPE property. If necessary, cast the pointer to a more appropriate type before making other calls.

Most message store providers require the name of the new folder to be unique with respect to the names of its sibling folders. Be able to handle the MAPI_E_COLLISION error value, which is returned if this rule is not followed.

To determine the entry identifier of the newly created folder, call the new folder's IMAPIProp::GetProps method to retrieve its PR_ENTRYID property.