IMAPISupport::Address

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Displays the common address dialog box.

HRESULT Address(
  ULONG_PTR FAR * lpulUIParam,
  LPADRPARM lpAdrParms,
  LPADRLIST FAR * lppAdrList
);

Parameters

  • lpulUIParam
    [in, out] A pointer to the 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, the window handle of the modeless dialog box is returned.

  • 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 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 Value

  • 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 the lppAdrList parameter. The ADRENTRY structure contains an array of recipient property values, one of which is the recipient's type, or PR_RECIPIENT_TYPE (PidTagRecipientType) 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 be either resolved, which indicates that one of its property values is its 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:

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 you allocate 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 with the MAPIAllocateBuffer function for ADRLIST and each property value structure in the ADRENTRY structures in ADRLIST.

If Address must return a larger ADRLIST structure, or if you have passed NULL for lppAdrList, Address 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.

See Also

Reference

ABProviderInit

ADRENTRY

ADRLIST

ADRPARM

FreePadrlist

FreeProws

IMAPISupport::GetMemAllocRoutines

IMAPITable::QueryRows

IMessage::ModifyRecipients

MAPIAllocateBuffer

MAPIAllocateMore

MAPIFreeBuffer

PidTagAddressType Canonical Property

PidTagDisplayName Canonical Property

PidTagDisplayType Canonical Property

PidTagEntryId Canonical Property

PidTagRecipientType Canonical Property

SPropValue

SRowSet

IMAPISupport : IUnknown

Concepts

Managing Memory for ADRLIST and SRowSet Structures