IABLogon::OpenEntry
The IABLogon::OpenEntry
method opens a container, messaging user, or distribution list and returns a
pointer to an interface implementation to provide further access.
Quick Info
See IABLogon
: IUnknown.
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 of the container, messaging user, or distribution list
to open.
lpInterface
[in] Pointer
to the interface identifier (IID) representing the interface to be used to
access the open object. Passing NULL results in the identifier for the object s
standard interface being returned. For containers, the standard interface is IABContainer.
The standard interfaces for address book objects are IDistList for a
distribution list and IMailUser for a messaging user.
ulFlags
[in] 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 access, the object should be opened with read/write access; 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 accessible to the
calling client. If the object is not accessible, making a subsequent object
call can result in an error.
MAPI_MODIFY
Requests
read/write access. By default, objects are opened with read-only access, and
clients should not work on the assumption that read/write access has been
granted.
lpulObjType
[out] Pointer
to the type of the opened object.
lppUnk
[out] Pointer
to a pointer to the opened object.
Return Values
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 access.
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 IABLogon::OpenEntry method to open a container, messaging user, or
distribution list.
Notes to Implementers
Before MAPI
calls your IABLogon::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 IMAPISupport::SetProviderUID at start up.
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 object
requested, 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 property. If the object does
support this property, call IMAPISupport::OpenTemplateID to bind to code for this
entry in the foreign provider. Pass PR_TEMPLATEID in the lpTemplateID
parameter and zero 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 returns
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 Implementing
a Host Address Book Provider.