Export (0) Print
Expand All

IMAPIContainer::OpenEntry

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Opens an object in the container, returning an interface pointer for further access.

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

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

lpInterface

[in] A pointer to the interface identifier (IID) that represents 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 IMAPIMessageSite : IUnknown; for folders, it is IMAPIFolder : IMAPIContainer. The standard interfaces for address book objects are IDistList : IMAPIContainer for a distribution list and IMailUser : IMAPIProp for a messaging user.

ulFlags

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

MAPI_BEST_ACCESS

Requests that the object will 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 permission, the object should be opened with read/write permission; 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 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 access, and clients should not work on the assumption that read/write permission has been granted.

SHOW_SOFT_DELETES

Shows items that are currently marked as soft deleted—that is, they are in the deleted item retention time phase.

lpulObjType

[out] A pointer to the opened object's type.

lppUnk

[out] A pointer to a pointer to the interface implementation to use to access the open object.

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 permission.

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.

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

Because service providers are not required to return an interface implementation of the type specified by the interface identifier in the lpInterface parameter, 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. However, do not assume that because you requested a modifiable object that the opened object has read/write permission. Either plan for the chance of a subsequent modification to fail or retrieve the object's PR_ACCESS_LEVEL property to determine the access level granted by OpenEntry.

Show:
© 2014 Microsoft