IMsgStore::OpenEntry
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Opens a folder or message and returns an interface pointer for further access.
HRESULT OpenEntry(
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
);
Parameters
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 object to open, or NULL. If lpEntryID is set to NULL, OpenEntry opens the root folder for the message store.lpInterface
[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the opened object. Passing NULL results in the object's standard interface (IMAPIFolder for folders and IMessage for messages) being returned.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 object be opened by using the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write permission, the object should be opened by using read/write permission; if the client has read-only permission, the object should be opened by using read-only permission.MAPI_DEFERRED_ERRORS
Allows OpenEntry to return successfully, possibly before the object is fully available to the calling client. If the object is not available, making a subsequent object call can raise an error.MAPI_MODIFY
Requests read/write permission. By default, objects are opened with read-only permission, and clients should not work on the assumption that read/write permission is granted.
lpulObjType
[out] A pointer to the type of the opened object.lppUnk
[out] A pointer to a pointer to the opened object.
Return Value
S_OK
The call succeeded and has returned the expected value or values.MAPI_E_NO_ACCESS
An attempt was made to modify a read-only object or to access an object for which the user has insufficient permissions.MAPI_NO_CACHE
When a store is opened in cached mode, a client or service provider can call IMsgStore::OpenEntry, setting the MAPI_NO_CACHE flag to open an item or a folder on the remote store. If you open the message store with the MDB_ONLINE flag on the remote server, you do not have to use the MAPI_NO_CACHE flag.
Remarks
The IMsgStore::OpenEntry method opens a folder or message and returns a pointer to an interface that can be used for further access.
Important
When opening folder entries on a public store, such as folders and messages, use IMsgStore::OpenEntry instead of IMAPISession::OpenEntry. This ensures that public folders function correctly when multiple Exchange accounts are defined in a profile.
Notes to Callers
Folders and messages are automatically opened with read-only permission, unless you set the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter. Setting one of these flags does not guarantee a particular type of permission; the permissions that you are granted depend on the message store provider, your access level, and the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL (PidTagAccessLevel) property.
Although IMsgStore::OpenEntry can be used to open any folder or message, it is usually faster to use the IMAPIContainer::OpenEntry method if you have access to the parent folder of the folder or message to be opened.
Check the value returned in the lpulObjType parameter to determine whether the returned object type is what you expected. If the object type is not the expected type, cast the pointer from the lppUnk parameter to a pointer of the appropriate type. For example, if you are opening a folder, cast lppUnk to a pointer of type LPMAPIFOLDER.
MFCMAPI Reference
For MFCMAPI sample code, see the following table.
File |
Function |
Comment |
|---|---|---|
MAPIFunctions.cpp |
CallOpenEntry |
MFCMAPI uses the IMsgStore::OpenEntry method to open the object associated with an entry ID. |