IAddrBook::Address

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

Quick Info

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 ADRPARM structure that controls the presentation and behavior of the address dialog box.
lppAdrList: [in, out] Pointer to a pointer to an ADRLIST 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 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 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_ENTRYID property, or unresolved, indicating that the PR_ENTRYID property is missing.

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

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 Structures

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 multibyte character string (MBCS) format before they are displayed in the common dialog box.