IMAPIFolder::CreateMessage

The IMAPIFolder::CreateMessage method creates a new message.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT CreateMessage(
  LPCIID lpInterface,         
  ULONG ulFlags,              
  LPMESSAGE FAR * lppMessage  
);
 

Parameters

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the new message. Valid interface identifiers include IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, and IID_IMAPIFolder. Passing NULL results in the message store provider returning the standard message interface, IMessage.

ulFlags

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

MAPI_ASSOCIATED

The message to be created should be included in the associated contents table rather than the standard contents table. Associated messages typically contain invisible data, such as view descriptors.

MAPI_DEFERRED_ERRORS

CreateMessage is allowed to succeed even if the create operation has not fully completed. This implies that the new message might not be immediately accessible to the caller.

lppMessage

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

Return Values

S_OK

The message was successfully created.

Remarks

The IMAPIFolder::CreateMessage method creates a new message with generic or associated content and assigns an entry identifier. The entry identifier is made up of a part that represents the message store provider and a part that represents the individual message.

Notes to Implementers

You can choose whether to set all of the required message properties in CreateMessage or in the message's IMAPIProp::SaveChanges method. You do not need to make these properties available until a successful save has occurred.

For more information on working with associated information, see Folder Associated Information Tables and Contents Tables.

Notes to Callers

Some message store providers allow the entry identifier of the new message to be available immediately after CreateMessage returns; others delay its availability until the message has been saved. Because not all message store providers generate an entry identifier for a new message until you have called the message's IMAPIProp::SaveChanges method, you may not be able to access the entry identifier when CreateMessage returns. Also, the new message may not be included in the folder's contents table until the save occurs.

Expect the entry identifier assigned to the new message to be unique not only within the current message store, but most likely across all of the message stores that are open concurrently. One exception to this general rule occurs when multiple entries for a message store appear in the profile, causing the message store to be opened multiple times and entry identifiers to be duplicated.

To create an outgoing message, call the Outbox folder's IMAPIFolder::CreateMessage method.

If you delete a folder containing a new message before the message is saved, the results are undefined.

See Also

IMAPIProp::SaveChanges