IXPLogon::RegisterOptions

The IXPLogon::RegisterOptions method informs the messaging system about the options provided by a transport provider for a messaging address type.

Quick Info

See IXPLogon : IUnknownHVE6L8.

HRESULT RegisterOptions(

Parameters

lpulFlags

[out] Bitmask of flags that controls the type of the returned strings. 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.

lpcOptions

[out] Pointer to the number of options contained in the structure returned in the lppOptions parameter.

lppOptions

[out] Pointer to a pointer to the returned OPTIONDATACXJHRW structure. The OPTIONDATA structure contains information for a particular messaging address type.

Return Values

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 supported by a transport provider for a particular messaging address type. These options are then registered with MAPI so they can be displayed in options dialog boxes.

RegisterOptions returns in the lppOptions parameter pointers to one or two OPTIONDATACXJHRW structures for each supported messaging address type, depending on whether the provider is registered for both recipient and message options, recipient options only, or message options only. If a provider is registered for both option types, RegisterOptions writes one structure containing option information for recipients and one containing option information for messages. For each structure, the ulFlags member indicates whether the options apply to a recipient or a message.

For an example of the use of OPTIONDATA, consider a transport provider that handles recipients for both Microsoft Mail Server and Microsoft Mail Server for the Macintosh. 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. Once it has this option information, the MAPI spooler prompts the user with a dialog box to retrieve the setting the user wants for each option.

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 OPTIONCALLBACK1OPVZTA function prototype defined in MAPIDEFS.H, receives a wrapped IMAPIPropHP08HX interface that manages the provider s message and recipient properties.

The provider is responsible for memory management. If memory is allocated for one or more OPTIONDATA structures during this call, the provider should free the memory upon logoff.

See Also