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.

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

See Also

Reference

ADRENTRY

IAddrBook::QueryDefaultRecipOpt

IMAPISession::MessageOptions

IMAPISession::QueryDefaultMessageOpt

SPropValue

IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample