IAddrBook::Address

The IAddrBook::Address method displays the common address dialog box.

Quick Info

See IAddrBook : IMAPIPropG38_SD.

HRESULT Address(

ULONG FAR * lpulUIParam,
LPADRPARM lpAdrParms,
LPADRLIST FAR * lppAdrList
)

Parameters

lpulUIParam

[in, out] 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, then the window handle of the modeless dialog box is returned.

lpAdrParms

[in, out] Pointer to an ADRPARM2EIR215 structure that controls the presentation and behavior of the address dialog box.

lppAdrList

[in, out] Pointer to a pointer to an ADRLIST16760YG structure containing 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 Values

S_OK

The common address dialog box was successfully displayed.

Remarks

The ADRLIST16760YG structure passed back by MAPI to the caller via the lppAdrList parameter contains an array of ADRENTRYWLHOWG structures, one structure for each recipient. When passed to an outgoing message s IMessage::ModifyRecipientsBTAS42 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 SPropValue81C9._8 structures, one structure for every property set for the recipient. There can be zero SPropValue structures when the dialog box presented by IAddrBook::Address 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 either be resolved, indicating that one of the SPropValue structures describes the recipient s PR_ENTRYID2JH9H8T property, or unresolved, indicating that the PR_ENTRYID property is missing.

In addition to PR_ENTRYID, resolved recipients include the following properties:

PR_RECIPIENT_TYPE1VRJ4HY

PR_DISPLAY_NAME1KS30YA

PR_ADDRTYPE7C7E4S

PR_DISPLAY_TYPEYIXSE1

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 allocating 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 StructuresJEZ06_

Address returns immediately if the DIALOG_SDI flag is set in the ulFlags member of the ADRPARM structure in the lpAdrParms parameter.

Address supports Unicode character strings in the ADRPARM and ADRLIST parameters for Windows NT platforms only. The Unicode strings are converted to the multi-byte character string (MBCS) format before they are displayed in the common dialog box.