IMAPIContainer::OpenEntry

The IMAPIContainer::OpenEntry method opens an object within the container, returning an interface pointer for further access.

Quick Info

See IMAPIContainer : IMAPIProp.

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. If lpEntryID is set to NULL, the top-level container in the container's hierarchy is opened.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object. Passing NULL results in the identifier for the object's standard interface being returned. For messages, 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 opened object's type.

lppUnk

[out] Pointer to a pointer to the interface implemention to use to access the open object.

Return Values

S_OK

The object was successfully opened.

MAPI_E_NO_ACCESS

Either the user has insufficient permissions to open the object or an attempt was made to open a read-only object with read/write access.

MAPI_E_NOT_FOUND

The entry identifier specified by lpEntryID does not represent an object.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier in the lpEntryID parameter is not of a format recognized by the container.

Remarks

The IMAPIContainer::OpenEntry method opens an object within a container and returns a pointer to an interface implementation to use for further access.

Notes to Callers

Because service providers are not required to return an interface implementation of the type specified by the interface identifier in lpInterface, check the value pointed to by the lpulObjType parameter. If necessary, cast the pointer returned in lppUnk to a pointer of the appropriate type.

By default, service providers open objects with read-only access unless you set either the MAPI_MODIFY or MAPI_BEST_ACCESS flag. When one of these flags is set, service providers attempt to return a modifiable object. Do not assume that because you set the MAPI_MODIFY flag, for example, that the opened object has read/write access. Either plan for the possibility of a subsequent modification to fail or retrieve the object's PR_ACCESS_LEVEL property to determine the access level granted by OpenEntry.