IMsgStore::GetReceiveFolder

The IMsgStore::GetReceiveFolder method obtains the folder that was established as the destination for incoming messages of a specified message class or the default receive folder for the message store.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT GetReceiveFolder(
  LPTSTR lpszMessageClass,      
  ULONG ulFlags,                
  ULONG FAR * lpcbEntryID,      
  LPENTRYID FAR * lppEntryID,   
  LPTSTR FAR * lppszExplicitClass  
);

Parameters

lpszMessageClass

[in] Pointer to a message class that is associated with a receive folder. If the lpszMessageClass parameter is set to NULL or an empty string, GetReceiveFolder returns the default receive folder for the message store.

ulFlags

[in] Bitmask of flags that controls the type of the passed-in and returned strings. The following flag can be set:

MAPI_UNICODE: The message class string is in Unicode format. If the MAPI_UNICODE flag is not set, the message class string is in ANSI format.

lpcbEntryID

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] Pointer to a pointer to the entry identifier for the requested receive folder.

lppszExplicitClass

[out] Pointer to a pointer to the message class that explicitly sets as its receive folder the folder pointed to by lppEntryID. This message class should either be the same as the class in the lpszMessageClass parameter or of a superclass of that class. Passing NULL indicates that the folder pointed to by lppEntryID is the default receive folder for the message store.

Return Value

S_OK: The receive folder was successfully returned.

Remarks

The IMsgStore::GetReceiveFolder method obtains the entry identifier of a receive folder, a folder designated to receive incoming messages of a particular message class. Callers can specify a message class or NULL in the lpszMessageClass parameter. If lpszMessageClass is NULL, GetReceiveFolder returns:

In lppszExplicitClass, the name of the first superclass of the message class pointed to by lpszMessageClass that does explicitly set a receive folder.
In lppEntryID, the entry identifier of the receive folder for the superclass pointed to by the lppszExplicitClass parameter.

For example, suppose the receive folder of the message class IPM.Note has been set to the entry identifier of the Inbox and GetReceiveFolder is called with the contents of lpszMessageClass set to IPM.Note.Phone. If IPM.Note.Phone does not have an explicit receive folder set, GetReceiveFolder returns the entry identifier of the Inbox in lppEntryID and IPM.Note in lppszExplicitClass.

If the client calls GetReceiveFolder for a message class and has not set a receive folder for that message class, lppszExplicitClass is either a zero-length string, a string in Unicode format, or a string in ANSI format depending on whether the client set the MAPI_UNICODE flag in the ulFlags parameter.

A default receive folder, obtained by passing NULL in the lpszMessageClass parameter, always exists for every message store.

A client should call the MAPIFreeBuffer function when it is done with the entry identifier returned in lppEntryID to free the memory that holds that entry identifier. It should also call MAPIFreeBuffer when it is done with the message class string returned in lppszExplicitClass to free the memory that holds that string.