Partager via

IABLogon::OpenEntry

  • Article

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 a container, messaging user, or distribution list, and returns a pointer to an interface implementation to provide 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 container, messaging user, or distribution list to open.

  • lpInterface
    [in] A pointer to the interface identifier (IID) that represents the interface to be used to access the open object. Passing NULL returns the identifier for the object's standard interface. For containers, the standard interface is IABContainer : 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 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 permission, the object should be opened with read-only permission.

    • MAPI_DEFERRED_ERRORS
      Allows the OpenEntry method to return successfully, possibly before the calling client has fully accessed the object. If the object is not accessed, 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 assume that read/write permission has been granted.

  • lpulObjType
    [out] A pointer to the type of the opened object.

  • lppUnk
    [out] A pointer to a pointer to the opened object.

Remarks

  • 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 address book provider.

Remarks

MAPI calls the OpenEntry method to open a container, messaging user, or distribution list.

Notes to Implementers

Before MAPI calls your OpenEntry method, it determines that the entry identifier in the lpEntryID parameter belongs to you and not to another provider. MAPI does this by matching the MAPIUID structure in the entry identifier with the MAPIUID that you registered by calling the IMAPISupport::SetProviderUID method at startup.

Open the object as read-only, unless the MAPI_MODIFY or MAPI_BEST_ACCESS flag is set in the ulFlags parameter. If you do not allow modification for the requested object, do not open the object at all and return MAPI_E_NO_ACCESS.

If MAPI passes NULL for lpEntryID, open the root container in your container hierarchy.

The object that you are being asked to open might be an object copied from another provider. In this case, it will support the PR_TEMPLATEID (PidTagTemplateid) property. If the object does support this property, call the IMAPISupport::OpenTemplateID method to bind to code for this entry in the foreign provider, passing PR_TEMPLATEID in the lpTemplateID parameter and 0 in the ulTemplateFlags parameter. IMAPISupport::OpenTemplateID passes this information to the foreign provider in a call to the foreign provider's IABLogon::OpenTemplateID method. If IMAPISupport::OpenTemplateID raises an error, usually because the foreign provider is unavailable or not included in the profile, try to continue by treating the unbound entry as read-only. For more information about opening foreign address book entries, see Acting as a Host Address Book Provider.

See Also

Reference

IABLogon : IUnknown