IMAPISession::OpenEntry

The IMAPISession::OpenEntry method opens an object and returns an interface pointer for further access.

Quick Info

HRESULT OpenEntry(
  ULONG cbEntryID,       
  LPENTRYID lpEntryID,   
  LPCIID lpInterface,    
  ULONG ulFlags,         
  ULONG FAR * lpulObjType,   
  LPUNKNOWN FAR * lppUnk 
);

Parameters

cbEntryID

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

lpEntryID

[in] Pointer to the entry identifier of the object to open.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the opened object. Passing NULL results in the object's standard interface being returned. For example, if the object to be opened is a message, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.

ulFlags

[in] 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 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 object should be opened with read/write access; if the client has read-only access, the object should be opened with read-only access.
MAPI_DEFERRED_ERRORS: Allows OpenEntry to return successfully, possibly before the object is fully accessible to the calling client. If the object is not accessible, making a subsequent object call can result in an error.
MAPI_MODIFY: Requests read/write access. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppUnk

[out] Pointer to a pointer to the opened object.

Return Values

S_OK: The object was opened successfully.
MAPI_E_NO_ACCESS: An attempt was made to modify a read-only object or an attempt was made to access an object for which the user has insufficient permissions.
MAPI_E_NOT_FOUND: There is not an object associated with the entry identifier passed in lpEntryID.
MAPI_E_UNKNOWN_ENTRYID: The entry identifier passed in the lpEntryID parameter is in an unrecognizable format. This value is typically returned if the service provider that contains the object is not open.

Remarks

The IMAPISession::OpenEntry method opens a message store or address book object, returning a pointer to an interface that can be used to access the object.

Notes to Callers

Call IMAPISession::OpenEntry only when you do not know what kind of object you are opening. If you know you are opening a folder or a message, call IMsgStore::OpenEntry. If you know you are opening an address book container, a messaging user, or a distribution list, call IAddrBook::OpenEntry. These more specific methods are faster than IMAPISession::OpenEntry.

MAPI opens all objects with read-only access, 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 access; the permissions that you are granted depends on the service provider, your access level, and the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL property.

Calling OpenEntry and setting lpEntryID to point to the entry identifier of a message store is equivalent to calling the IMAPISession::OpenMsgStore method with the MDB_NO_DIALOG flag set. The flag settings are also equivalent, with the exception that to request read/write access with OpenMsgStore, you must set the MDB_WRITE flag rather than MAPI_MODIFY.

Check the value returned in the lpulObjType parameter to determine that the object type returned is what you expected. If the object type is not the type you expected, 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.