IMAPIFolder::CreateFolder

The IMAPIFolder::CreateFolder method creates a new subfolder.

Quick Info

See IMAPIFolder : IMAPIContainer161AJWS.

HRESULT CreateFolder(

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_NAME1KS30YA 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_COMMENT1ZSL3AY 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::SaveChanges21IFXQ 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::GetPropsK06IXU method to retrieve the PR_OBJECT_TYPE4YLDI0 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::GetPropsK06IXU method to retrieve its PR_ENTRYID2JH9H8T property.

See Also