IXPLogon::RegisterOptions
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.
Returns to the MAPI spooler the options that the transport provider supports for an address type.
HRESULT RegisterOptions(
ULONG FAR * lpulFlags,
ULONG FAR * lpcOptions,
LPOPTIONDATA FAR * lppOptions
);
Parameters
lpulFlags
[out] A bitmask of flags that controls the type of strings returned. The following flag can be set:- MAPI_UNICODE
The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.
- MAPI_UNICODE
lpcOptions
[out] A pointer to the number of options contained in the structure returned in the lppOptions parameter.lppOptions
[out] A pointer to a pointer to the returned OPTIONDATA structure. The OPTIONDATA structure contains information for a particular messaging address type.
Return Value
- S_OK
The call succeeded and has returned the expected value or values. If anything other than S_OK is returned, the provider is logged off.
Remarks
The MAPI spooler calls the IXPLogon::RegisterOptions method to get the options for messages and recipients that a transport provider supports for a particular messaging address type. These options are then registered with MAPI so they can be displayed in option dialog boxes.
RegisterOptions returns in the lppOptions parameter pointers to one or two OPTIONDATA structures for each supported messaging address type, depending on whether the provider is registered for both recipient and message options, only recipient options, or only message options. If a provider is registered for both option types, RegisterOptions writes one structure that contains option information for recipients and one that contains option information for messages. For each structure, the ulFlags member indicates whether the options apply to a recipient or a message.
For example, a transport provider might handle recipients for two different mail servers on different platforms. If the provider is registered for both recipient and message options, it provides two pairs of OPTIONDATA structures, one pair for each platform. The MAPI spooler can use these structures to determine what options are valid for each platform and to enable users to change settings for those options.
MAPI also uses the options registered on the RegisterOptions call to resolve message and recipient options. MAPI does so by using a callback function that the transport provider supplies. This callback function, declared with the OPTIONCALLBACK function prototype defined in the Mapidefs.h file, receives a wrapped IMAPIProp interface that manages the provider's message and recipient properties.
The transport provider is responsible for memory allocated for any OPTIONDATA structures during this call. The provider should free the memory on logoff.