IAddrBook::OpenEntry

The IAddrBook::OpenEntry method opens an address book entry and returns a pointer to an interface that can be used to access the entry.

Quick Info

See IAddrBook : IMAPIProp.

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

Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier representing the address book entry to open.

lpInterface

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

ulFlags

[in] 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 allowable network and client permissions. For example, if the client has read/write access, the address book provider should attempt to open the entry with read/write access.

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

MAPI_DEFERRED_ERRORS

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

MAPI_MODIFY

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

lpulObjType

[out] Pointer to the type of the opened entry.

lppUnk

[out] Pointer to a pointer to the opened entry.

Return Values

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