IMAPISession::OpenMsgStore

The IMAPISession::OpenMsgStore method opens a message store and returns an IMsgStore pointer for further access.

Quick Info

See IMAPISession : IUnknown.

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

Parameters

ulUIParam

[in] Handle of the parent window for the common address dialog box and other related displays.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

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

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the message store. Passing NULL results in a pointer to its standard interface being returned in the lppMDB parameter. The standard interface for a message store is IMsgStore.

ulFlags

[in] 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 access. For example, if the client has read/write access, the message store should be opened with read/write access; if the client has read-only access, the message store should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenMsgStore to return successfully, possibly before the message store is fully accessible to the calling client. If the message store is not accessible, making a subsequent object call can result in an error.

MDB_NO_DIALOG

Prevents the display of logon dialog boxes. If this flag is set, and OpenMsgStore does not have enough 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, to insert a disk, or to perform other actions necessary to establish 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_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 the message store so that information can be retrieved programmatically from the profile section.

MDB_WRITE

Requests read/write access to the message store.

lppMDB

[out] Pointer to a pointer to the message store.

Return Values

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. See Using Macros for Error Handling.

Remarks

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

Notes to Callers

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

If you call OpenMsgStore to open a message store with read-only access:

• The store's PR_STORE_SUPPORT_MASK property will not have its STORE_MODIFY_OK and STORE_CREATE_OK bits set.
• Calls to open one of the message store's messages or folders using IMAPISession::OpenEntry with the MAPI_MODIFY flag set will fail.
• Calls to open one of the properties of the message store's messages or folders using IMAPIProp::OpenProperty and the MAPI_MODIFY will fail.
• Calls to any of the following methods will fail:

  IMAPIFolder::CreateMessage

  IMAPIFolder::DeleteMessages

  IMAPIFolder::CreateFolder

  IMAPIFolder::DeleteFolder

  IMAPIFolder::SetMessageStatus

  IMAPIProp::SetProps

  IMAPIProp::DeleteProps

• Calls to the following methods fail if the destination for the copied message is read-only, whether it be the same as the source message store or another read-only store:

  IMAPIFolder::CopyMessages

  IMAPIFolder::CopyFolder

  IMAPIProp::CopyTo