IXPLogon::RegisterOptions

The IXPLogon::RegisterOptions method returns the options that are supported by the transport provider for an address type to the MAPI spooler.

Quick Info

See IXPLogon : IUnknown.

HRESULT RegisterOptions(
  ULONG FAR * lpulFlags,         
  ULONG FAR * lpcOptions,        
  LPOPTIONDATA FAR * lppOptions  
);
 

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 OPTIONDATA 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 OPTIONDATA 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 and to allow 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 MAPIDEFS.H, 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 upon logoff.

See Also

IXPLogon::RegisterOptions, OPTIONCALLBACK, OPTIONDATA