IMAPISession::OpenAddressBook
The IMAPISession::OpenAddressBook
method opens MAPI s integrated address book, returning an IAddrBook
pointer for further access.
Quick Info
See IMAPISession
: IUnknown.
HRESULT OpenAddressBook(
|
ULONG ulUIParam,
|
|
|
LPCIID lpInterface, |
|
|
ULONG ulFlags,
|
|
|
LPADRBOOK FAR * lppAdrBook |
|
|
) |
|
Parameters
ulUIParam
[in] Handle
of the parent window for the common address dialog box and other related
displays.
lpInterface
[in] Pointer
to the interface identifier (IID) representing the interface to be used to
access the address book. Passing NULL results in a pointer to the address
book s standard interface, or IAddrBook, being returned.
ulFlags
[in] Bitmask
of flags that the opening of the address book. The following flag can be set:
AB_NO_DIALOG
Suppresses
the display of dialog boxes. If the AB_NO_DIALOG flag is not set, the address
book providers contributing to the integrated address book can prompt the user
for any necessary information.
lppAdrBook
[out] Pointer
to a pointer to the address book.
Return Values
S_OK
The address
book was successfully opened.
MAPI_E_UNKNOWN_CPID
The server is
not configured to support the client's code page.
MAPI_E_UNKNOWN_LCID
The server is
not configured to support the client's locale information.
MAPI_W_ERRORS_RETURNED
The call
succeeded, but the containers of one or more address book providers could not
opened. When this warning is returned, the call should be handled as
successful. To test for this warning, use the HR_FAILED macro. See Using
Macros for Error Handling.
Remarks
The IMAPISession::OpenAddressBook
method opens the MAPI integrated address book a collection of the top-level containers of all of
the address book providers in the profile. The pointer that is returned in the lppAdrBook
parameter provides further access to the contents of the address book, allowing
the caller to perform tasks such as opening individual containers, finding
messaging users, and displaying common address dialog boxes.
Notes to Callers
OpenAddressBook returns MAPI_W_ERRORS_RETURNED if it cannot load one
or more of the address book providers in the profile. This value is a warning,
not an error value; handle it as you would S_OK. OpenAddressBook always
returns a valid pointer in the lppAdrBook parameter, regardless of how
many of the address book providers failed to load. Therefore, you must always
call the address book s IUnknown::Release method at some point before
logging off.
When OpenAddressBook
returns MAPI_W_ERRORS_RETURNED, call IMAPISession::GetLastError to obtain a MAPIERROR structure containing
information about the failing providers. A single MAPIERROR structure is
returned that contains information supplied by all of the providers.
See Also