IMAPISession::OpenMsgStore

  • Article

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Opens a message store and returns an IMsgStore pointer for further access.

HRESULT OpenMsgStore(
  ULONG_PTR ulUIParam,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPMDB FAR * lppMDB
);

Parameters

  • ulUIParam
    [in] A handle to the parent window of the common address dialog box and other related displays.

  • cbEntryID
    [in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

  • lpEntryID
    [in] A pointer to the entry identifier of the message store to be opened. The lpEntryID parameter must not be NULL.

  • lpInterface
    [in] A pointer to the interface identifier (IID) that represents the interface to be used to access the message store. Passing NULL causes the lppMDB parameter to return a pointer to the standard interface for a message store (IMsgStore).

  • ulFlags
    [in] A bitmask of flags that controls how the object is opened. The following flags can be used:

    • MAPI_BEST_ACCESS
      Requests that the message store be opened with the maximum network permissions allowed for the user and the maximum client application permissions. For example, if the client has read/write permission, the message store should be opened with read/write permission; if the client has read-only permission, the message store should be opened with read-only permission.

    • MAPI_DEFERRED_ERRORS
      Allows OpenMsgStore to return successfully, possibly before the message store is fully available to the calling client. If the message store is not available, making a subsequent object call can raise an error.

    • MDB_NO_DIALOG
      Prevents the display of logon dialog boxes. If this flag is set, and OpenMsgStore has insufficient configuration information to open the message store without the user's help, it returns MAPI_E_LOGON_FAILED. If this flag is not set, the message store provider can prompt the user to correct a name or password or to perform other actions that are needed to establish a connection to the message store.

    • MDB_NO_MAIL
      The message store should not be used for sending or receiving mail. When this flag is set, MAPI does not notify the MAPI spooler that this message store is being opened.

    • MDB_ONLINE
      In Cached Exchange Mode, a client or service provider can call this method with MDB_ONLINE to override the connection to the local message store and open the store on the remote server. You cannot open an Exchange store in cached mode and in non-cached mode at the same time in the same MAPI session. If you have already opened the cached message store, you must either close the store before you open it with this flag, or open a new MAPI session where you can open the Exchange store on the remote server by using this flag.

    • MDB_TEMPORARY
      Instructs MAPI that the message store is not permanent and should not be added to the message store table. This flag is used to log on to the message store so information can be retrieved programmatically from the profile section.

    • MDB_WRITE
      Requests read/write permission to the message store.

  • lppMDB
    [out] Pointer to a pointer of the message store.

Return Value

  • S_OK
    The message store was successfully opened.

  • MAPI_E_NO_ACCESS
    An attempt was made to access a message store for which the user has insufficient permissions.

  • MAPI_E_NOT_FOUND
    The message store indicated by lpEntryID does not exist.

  • MAPI_E_UNKNOWN_CPID
    The server is not configured to support the client's code page.

  • MAPI_E_UNKNOWN_LCID
    The server is not configured to support the client's locale information.

  • MAPI_W_ERRORS_RETURNED
    The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To get the error information from the provider, call the IMAPISession::GetLastError method. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISession::OpenMsgStore method opens a particular message store.

Notes to Callers

The default permission level for message stores is read-only. If you set the MDB_WRITE flag, you still might not be granted read/write permission. The final level of access that MAPI assigns to the message store depends on your permission level, the message store itself, and the message store provider.

If you call OpenMsgStore to open a message store with read-only permission, the following will occur:

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

MAPIStoreFunctions.cpp

CallOpenMsgStore

MFCMAPI uses the IMAPISession::OpenMsgStore method to open a message store.

See Also

Reference

IMsgStore : IMAPIProp

IMAPISession::GetLastError

IMAPISession::OpenEntry

IMAPIProp::OpenProperty

IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample

Using Macros for Error Handling