IMAPISupport::Address

The IMAPISupport::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 DIALOG_SDI flag is set in the ADRPARM structure pointed to by the lpAdrParms parameter, 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 address list. On input, this list is either the current list of recipients in a message or NULL, if no such list exists. On output, lppAdrList points to an updated list of message recipients.

Return Values

S_OK: The address dialog box was successfully displayed.

Remarks

The IMAPISupport::Address method is implemented for address book provider support objects. Address book providers call Address to create or update a list of message recipients.

Each recipient is described in an ADRENTRY structure that is included in the ADRLIST structure pointed to by lppAdrList. The ADRENTRY structure contains an array of recipient property values, one of which is the recipient's type, or PR_RECIPIENT_TYPE property. This ADRLIST structure can be passed to a client to use as the lpMods parameter in a call to IMessage::ModifyRecipients.

Each recipient in the ADRLIST structure can either be resolved, indicating that one of its property values is its PR_ENTRYID property, or unresolved, indicating that the PR_ENTRYID property is missing.

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

Unresolved recipients typically include only PR_DISPLAY_NAME and PR_RECIPIENT_TYPE.

Notes to Callers

The ADRLIST structure that the caller passes in might be a different size from the structure that MAPI returns. When allocating memory for the ADRLIST structure, allocate the memory for each SPropValue structure separately.

Use the pointers to the MAPI memory allocation functions passed in to your ABProviderInit function to allocate memory. Allocate memory for the ADRLIST structure and each property value structure within the ADRENTRY structures in the ADRLIST structure with the MAPIAllocateBuffer function.

If Address must return a larger ADRLIST structure, or if you have passed NULL for lppAdrList, it frees the original structure and allocates a new one. Address also allocates additional property value structures in the ADRLIST structure and frees old ones as appropriate. For more information about how memory is managed for ADRLIST structures, see Managing Memory for ADRLIST and SRowSet Structures.

Address returns immediately if the DIALOG_SDI flag was set in the ADRPARM structure in the lpAdrParms parameter.