IMAPISession::OpenAddressBook

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Opens the MAPI integrated address book, returning an IAddrBook pointer for further access.

HRESULT OpenAddressBook(
  ULONG_PTR ulUIParam,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPADRBOOK FAR * lppAdrBook
);

Parameters

• ulUIParam
  [in] A handle to the parent window of the common address dialog box and other related displays.

• lpInterface
  [in] A pointer to the interface identifier (IID) that represents the interface to be used to access the address book. Passing null returns a pointer to the address book's standard interface, IAddrBook : IMAPIProp.

• ulFlags
  [in] A bitmask of flags that controls 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 that contribute to the integrated address book can prompt the user for any necessary information.

• lppAdrBook
  [out] A pointer to a pointer to the address book.

Return Value

• S_OK
  The address book was successfully opened.

• MAPI_W_ERRORS_RETURNED
  The call succeeded, but the containers of one or more address book providers could not be opened. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, 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. This allows 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 that contains information about the failing providers. A single MAPIERROR structure is returned that contains information supplied by all of the providers.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

See Also

Reference

IAddrBook : IMAPIProp

IMAPISession::GetLastError

MAPIERROR

IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample