IAddrBook::RecipOptions
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Displays a dialog box that shows the recipient option properties.
HRESULT RecipOptions(
ULONG_PTR ulUIParam,
ULONG ulFlags,
LPADRENTRY lpRecip
);
Parameters
ulUIParam
[in] The handle of the parent window of the dialog box.ulFlags
[in] A bitmask of flags that controls how the entry is opened. The following flag can be set:- MAPI_UNICODE
The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.
- MAPI_UNICODE
lpRecip
[in] A pointer to the ADRENTRY structure that describes the recipient whose options are to be displayed.
Return Value
S_OK
The options for the specified recipient were successfully displayed.MAPI_W_ERRORS_RETURNED
There are no recipient options for this recipient. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information about how to use the HR_FAILED macro, see Using Macros for Error Handling.
Remarks
Clients and service providers call the RecipOptions method to display a dialog box that allows a user to set properties that control the sending and receiving of messages for a particular recipient and address type.
To locate the appropriate properties to be displayed, MAPI first scans through the SPropValue structure array in the ADRENTRY structure to find the PR_ENTRYID (PidTagEntryId) and PR_ADDRTYPE (PidTagAddressType) properties. MAPI then determines the transport provider, if any, that has registered options for the particular address type. If there is an appropriate transport provider, MAPI calls the provider's function that is based on the OPTIONCALLBACK prototype to retrieve the properties.
To retrieve the set of default recipient options without presenting a dialog box to the user, clients or service providers should call the IAddrBook::QueryDefaultRecipOpt method.
If any recipient options are changed on a RecipOptions call, MAPI frees the old SPropValue structures for those options in the recipient's ADRENTRY structure and allocates new ones.
If there are no recipient options available for the address type indicated in the lpRecip parameter, the warning MAPI_W_ERRORS_RETURNED is returned, which indicates there was an error returned for the RecipOptions call. Calling the IMAPIProp::GetLastError method returns a text string that describes the warning.
Transport providers can also register message options that apply to all recipients. For more information about registering options, see Implementing Message and Recipient Options.
MFCMAPI Reference
For MFCMAPI sample code, see the following table.
File |
Function |
Comment |
|---|---|---|
RecipientsDlg.cpp |
CrecipientsDlg::OnRecipOptions |
MFCMAPI uses the RecipOptions method to show the user the default recipient options for the specified object. |
See Also
Reference
IAddrBook::QueryDefaultRecipOpt
IMAPISession::QueryDefaultMessageOpt