IAddrBook::OpenEntry
Published: July 16, 2012
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 );
- 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
-
Opens an address book entry and accesses it only from the cache. 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 later 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.
Note
The ulFlags MAPI_GAL_ONLY might not be defined in the downloadable header file you currently have, in which case you can add it to your code using the following value:
#define MAPI_GAL_ONLY (0x00000080)
- 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 was 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.
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 whether 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.
