IAddrBook::Address
Applies to: Outlook 2013 | Outlook 2016
Displays the Outlook address book dialog box.
HRESULT Address(
ULONG_PTR FAR * lpulUIParam,
LPADRPARM lpAdrParms,
LPADRLIST FAR * lppAdrList
);
Parameters
lpulUIParam
[in, out] A pointer to a handle of the parent window of the dialog box. On input, a window handle must always be passed. On output, if the ulFlags member of the lpAdrParms parameter is set to DIALOG_SDI, the window handle of the modeless dialog box is returned. See Remarks.
lpAdrParms
[in, out] A pointer to an ADRPARM structure that controls the presentation and behavior of the address dialog box.
lppAdrList
[in, out] A pointer to a pointer to an ADRLIST structure that contains recipient information. On input, this parameter can be NULL or point to a valid pointer. On output, this parameter points to a pointer to valid recipient information.
Return value
S_OK
The common address dialog box was successfully displayed.
Remarks
If the ulFlags member of the lpAdrParms parameter is set to DIALOG_SDI anticipating the return of the window handle of the modeless dialog box on output, it is ignored in Outlook; the modal version of the dialog is always shown in non-Outlook clients.
The ADRLIST structure passed back by MAPI to the caller through the lppAdrList parameter contains an array of ADRENTRY structures, one structure for each recipient. When passed to an outgoing message's IMessage::ModifyRecipients method in the lpMods parameter, the ADRLIST structure can be used to update its recipient list.
Each ADRENTRY structure in the ADRLIST structure contains zero or more SPropValue structures, one structure for every property set for the recipient. There can be zero SPropValue structures when the dialog box presented by the Address method is used to remove a recipient. When there are one or more SPropValue structures, the corresponding ADRENTRY structure is used to add or update a recipient. The recipient can be resolved, which indicates that one of the SPropValue structures describes the recipient's PR_ENTRYID (PidTagEntryId) property, or unresolved, which indicates that the PR_ENTRYID property is missing.
In addition to PR_ENTRYID, resolved recipients include the following properties:
PR_RECIPIENT_TYPE (PidTagRecipientType)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_ADDRTYPE (PidTagAddressType)
PR_DISPLAY_TYPE (PidTagDisplayType)
The ADRLIST structure that the caller passes in might be a different size from the structure that MAPI returns. If MAPI must return a larger ADRLIST structure, it frees the original structure and allocates a new one. When you allocate memory for the ADRLIST structure, allocate the memory for each SPropValue structure separately. For more information about how to allocate and free ADRLIST structures, see Managing Memory for ADRLIST and SRowSet Structures
Address returns immediately if the DIALOG_SDI flag is set in the ulFlags member of the ADRPARM structure in the lpAdrParms parameter. The DIALOG_SDI flag is ignored for non-Outlook clients. If DIALOG_SDI is ignored, the modal version of the dialog will be displayed and a pointer to a handle should not be expected in lpulUIParam.
Address supports Unicode character strings in the ADRPARM structure if AB_UNICODEUI was specified in the ulFlags member of ADRPARM in the lpAdrParms parameter, and it supports Unicode character strings in ADRLIST. The Unicode strings are converted to the multibyte character string (MBCS) format before they are displayed in the Outlook address book dialog box.
MFCMAPI reference
For MFCMAPI sample code, see the following table.
| File | Function | Comment |
|---|---|---|
| MAPIStoreFunctions.cpp |
OpenOtherUsersMailboxFromGal |
MFCMAPI uses the Address method to allow the user to select which mailbox to open. |