IMAPIContainer::OpenEntry

  • Article

Applies to: Office 2010 | Outlook 2010 | Visual Studio

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
);

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

Return Value

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

Remarks

The IMAPIContainer::OpenEntry method opens an object throughout 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 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.

See Also

Reference

IMAPIContainer : IMAPIProp