IMAPIFolder::CreateFolder

Article
08/28/2006

The CreateFolder method creates a new subfolder in the current folder.

Syntax

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

Parameters

ulFolderType
[in] Ignored.
lpszFolderName
[in] Reference to a string containing the name for the new folder; cannot be NULL.
lpszFolderComment
[in] Ignored.
lpInterface
[in] Ignored.
ulFlags
[in] Bitmask of flags that controls how the folder is created. The following flags can be set:

MAPI_UNICODE

This flag is required. The passed-in strings are in Unicode 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. 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] Reference to the newly created folder object, implemented on IMAPIFolder.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
Indicates success.
MAPI_E_COLLISION
A folder with the name given in the lpszFolderName parameter already exists. Folder names must be unique.

Remarks

CreateFolder creates a subfolder in the current folder and assigns an entry identifier to the new folder. When CreateFolder returns, the entry identifier is available for the new folder.

Some message store providers always point lppFolder to the folder's standard interface. MAPI requires 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 GetProps method to retrieve its PR_ENTRYID property.

Requirements

Pocket PC: Windows Mobile 2002 and later
OS Versions: Windows CE 3.0 and later
Header: mapidefs.h
Library: cemapi.lib

Share via