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:
PR_RECIPIENT_TYPE
PR_DISPLAY_NAME (PidTagDisplayName)
PR_ADDRTYPE (PidTagAddressType)
PR_DISPLAY_TYPE (PidTagDisplayType)
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
IMAPISupport::GetMemAllocRoutines
PidTagAddressType Canonical Property
PidTagDisplayName Canonical Property
PidTagDisplayType Canonical Property
PidTagEntryId Canonical Property
PidTagRecipientType Canonical Property