IAddrBook::RecipOptions
The IAddrBook::RecipOptions
method displays a dialog box showing the recipient option properties.
Quick Info
See IAddrBook
: IMAPIProp.
HRESULT RecipOptions(
|
ULONG ulUIParam,
|
|
|
ULONG ulFlags,
|
|
|
LPADRENTRY lpRecip |
|
|
) |
|
Parameters
ulUIParam
[in] Handle
of the parent window for the dialog box.
ulFlags
Reserved;
must be zero.
lpRecip
[in] Pointer
to the ADRENTRY
structure that describes the recipient whose options are to be displayed.
Return Values
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 on using the HR_FAILED macro, see Using
Macros for Error Handling.
Remarks
Clients and
service providers call the IAddrBook::RecipOptions method to display a
dialog box to allow 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 and PR_ADDRTYPE 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 within 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, indicating there was an error returned for
the RecipOptions call. Calling the IMAPIProp::GetLastError method returns a text
string describing the warning.
Transport
providers can also register message options that apply to all of recipients.
For more information on registering options, see Implementing Message and
Recipient Options with Transport Providers.
See Also