IAddrBook::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 an address book entry and returns a pointer to an interface that can be used to access the entry.

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 that represents the address book entry to open.

  • lpInterface
    [in] A pointer to the interface identifier (IID) of the interface to be used to access the open entry. Passing NULL returns the object's standard interface. For messaging users, the standard interface is IMailUser : IMAPIProp. For distribution lists, it is IDistList : IMAPIContainer and for containers, it is IABContainer : IMAPIContainer. Callers can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

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

    • MAPI_BEST_ACCESS
      Requests that the entry be opened with the maximum allowed network and client permissions. For example, if the client has read/write permission, the address book provider should attempt to open the entry with read/write permission. The client can retrieve the access level that was granted by calling the open entry's IMAPIProp::GetProps method and retrieving the PR_ACCESS_LEVEL (PidTagAccessLevel) property.

    • MAPI_CACHE_ONLY
      Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

    • MAPI_DEFERRED_ERRORS
      Allows the call to succeed, potentially before the entry is fully open and available, implying that subsequent calls to the entry might return an error.

    • MAPI_GAL_ONLY
      Use only the GAL to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

    • MAPI_MODIFY
      Requests that the entry be opened with read/write permission. Because entries are opened with read-only access by default, clients should not assume that read/write permission has been granted regardless of whether MAPI_MODIFY is set.

    • MAPI_NO_CACHE
      Do not use the offline address book to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

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

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

Return Value

  • S_OK
    The entry was successfully opened.

  • MAPI_E_NO_ACCESS
    An attempt was made to open an entry for which the user has insufficient permissions.

  • MAPI_E_NOT_FOUND
    The entry represented by lpEntryID does not exist.

  • MAPI_E_UNKNOWN_ENTRYID
    The entry identifier specified in lpEntryID is not recognized. This value is typically returned if the address book provider responsible for the corresponding entry is not open.

Remarks

Clients and service providers call the IAddrBook::OpenEntry method to open an address book entry. MAPI forwards the call to the appropriate address book provider, based on the MAPIUID structure included in the entry identifier passed in the lpEntryID parameter. The address book provider opens the entry as read-only unless the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter is set. However, these flags are suggestions. If the address book provider does not allow modification for the entry requested, it returns MAPI_E_NO_ACCESS.

The lpInterface parameter indicates which interface should be used to access the opened entry. Passing NULL in lpInterface indicates the standard MAPI interface for that type of entry should be used. Because the address book provider might return a different interface than the one suggested by the lpInterface parameter, the caller should check the value returned in the lpulObjType parameter to determine that the object type returned is what was expected. If the object type is not of the type expected, the caller can cast the lppUnk parameter to a type that is more appropriate.

See Also

Reference

IAddrBook : IMAPIProp