IMsgStore::GetReceiveFolder

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Obtains the folder that was established as the destination for incoming messages of a specified message class or as the default receive folder for the message store.

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

Parameters

  • lpszMessageClass
    [in] A 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] A 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] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.

  • lppEntryID
    [out] A pointer to a pointer to the entry identifier for the requested receive folder.

  • lppszExplicitClass
    [out] A 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 a base class 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 the following values:

  • In lppszExplicitClass, the name of the first base class 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 base class 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.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

MAPIFunctions.cpp

GetInbox

MFCMAPI uses the IMsgStore::GetReceiveFolder method to locate the Inbox folder.

See Also

Reference

MAPIFreeBuffer

IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample