OPTIONDATA

The OPTIONDATA structure describes properties supported by a transport provider.

Quick Info

typedef struct _OPTIONDATA 
{ 
     ULONG           ulFlags;      
     LPGUID          lpRecipGUID;      
     LPTSTR          lpszAdrType;      
     LPTSTR          lpszDLLName;      
     ULONG           ulOrdinal; 
     ULONG           cbOptionsData; 
     LPBYTE          lpbOptionsData;      
     ULONG           cOptionsProps;      
     LPSPropValue    lpOptionsProps;      
} OPTIONDATA, FAR *LPOPTIONDATA; 
 

Members

ulFlags

Flags used to specify the type of option properties. One of the following flags must be set:

MAPI_MESSAGE

The properties are message-specific options.

MAPI_RECIPIENT

The properties are recipient-specific options.

lpRecipGUID

Pointer to a GUID structure identifying the message recipient, if the ulFlags member is set to MAPI_RECIPIENT. When lpRecipGUID points to a valid GUID structure, recipient options are restricted to only those recipients that have in their entry identifiers the value of lpRecipGUID.

lpszAdrType

Pointer to an e-mail address type, if the ulFlags member is set to MAPI_RECIPIENT. When lpszAdrType points to a valid address type, recipient options are restricted to only those recipients with this address type.

lpszDLLName

Pointer to the name of the DLL to be loaded. This is the DLL containing the transport provider's option callback function — the function that is called to manage the option properties.

ulOrdinal

Specifies which ordinal MAPI uses to find the option callback function.

cbOptionsData

Count of bytes in the data pointed to by the lpbOptionsData member.

lpbOptionsData

Pointer to transport provider option data that is specific to the recipient or message and is passed to the option callback function.

cOptionsProps

Count of properties in the array pointed to by the lpOptionsProps member.

lpOptionsProps

Pointer to an array of SPropValue structures, each containing the default values for the recipient or message options.

Remarks

Option properties can apply to a recipient or to a message. They often relate to an address type or GUID supported by a transport provider. Transport providers register to support option properties when MAPI calls their IXPLogon::RegisterOptions method.

RegisterOptions writes one or two OPTIONDATA structures for each supported address type, depending on whether the provider registers 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 message option properties and one structure containing recipient option properties.

Clients can retrieve the current settings for these options either interactively with a property sheet or programmatically with a property value array. To display option properties to the user, clients call IMAPISession::MessageOptions or IAddrBook::RecipOptions. To retrieve option properties without user intervention, clients call IMAPISession::QueryDefaultMessageOpt or IAddrBook::QueryDefaultRecipOpt.

When a client calls MessageOptions or RecipOptions, MAPI invokes a callback function created by the transport provider that conforms to the OPTIONCALLBACK prototype. This function typically resides in the same DLL as the transport provider and is called to retrieve an IMAPIProp implementation to use with a display table for showing the message and recipient options described in the OPTIONDATA structures.

The DLL name in the lpszDLLname member should not indicate the platform when included in an OPTIONDATA structure that is passed in the lppOptions parameter to IXPLogon::RegisterOptions.

For more information, see Implementing Message and Recipient Options with Transport Providers and Message and Recipient Options.

See Also

IXPLogon::AddressTypes, IXPLogon::RegisterOptions, SPropValue