IAddrBook::RecipOptions

The IAddrBook::RecipOptions method displays a dialog box showing the recipient option properties.

Quick Info

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 recipients. For more information on registering options, see Implementing Message and Recipient Options with Transport Providers.