IXPLogon::AddressTypes

The IXPLogon::AddressTypes method indicates to the MAPI spooler what types of recipients a transport provider can handle.

Quick Info

See IXPLogon : IUnknownHVE6L8.

HRESULT AddressTypes(

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.

lpcAdrType

[out] Pointer to the number of entries in the array pointed to by the lpppAdrTypeArray parameter.

lpppszAdrTypeArray

[out] Pointer to a variable where the transport provider places an array of pointers to strings that identify recipient types.

lpcMAPIUID

[out] Pointer to the number of entries in the array pointed to by the lpppUIDArray parameter.

lpppUIDArray

[out] Pointer to a variable where the transport provider places an array of pointers to MAPIUIDT02NXD structures that identify recipient types.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::AddressTypes method immediately after a transport provider returns from a call to the IXPProvider::TransportLogonAGE6K0 method so the transport provider can indicate what types of recipients it can handle. To indicate this, the transport provider should pass in the lpppszAdrTypeArray parameter a pointer to an array of pointers to strings, or pass in the lpppUIDArray parameter a pointer to an array of pointers to MAPIUID structures, or pass values in both parameters.

These two arrays are used for different identification processes. MAPI and the MAPI spooler use the MAPIUIDT02NXD structures in the lpppUIDArray array to identify those recipient entry identifiers that are directly handled by the transport provider or by the messaging system to which the transport provider connects. Neither MAPI nor the MAPI spooler performs expansion of addresses with entry identifiers containing any of these MAPIUID structures; these structures are only used for recipient type identification.

The MAPI spooler uses each of the strings in the lpppszAdrTypeArray parameter for a comparison test when deciding which transport provider should handle which recipients for an outbound message. If a message recipient s PR_ADDRTYPE7C7E4S property exactly matches a string identifying one of the messaging address types supplied by the transport provider, the provider can handle that recipient.

In the event multiple transport providers can handle the same type of recipient, MAPI selects a transport provider based on the transport priority order indicated in the client application s profile. To determine which transport provider to use, the MAPI spooler scans all provider-specified MAPIUID structures in priority order, then all provider-specified address type values in priority order. The first transport provider to match a particular recipient in this scan gets the first opportunity to handle this recipient. If that provider does not handle the recipient, the MAPI spooler continues the scan so as to find a transport provider for any recipient not yet handled. The scan continues until no further matches are found, at which point a nondelivery report is generated for any recipient that was not handled.

If the provider always supports a particular set of recipient types, the address type and MAPIUID arrays passed by the transport provider can be static. If the transport provider dynamically constructs these arrays, it can use the support object that was passed in the call to TransportLogon directly previous to allocate memory, although this is not strictly necessary.

The memory used for the address type and MAPIUID arrays should remain allocated until the final call to the IXPLogon::TransportLogoff4O9K9RH method is performed, at which time the transport provider can free the memory if necessary. The contents of these arrays should not be altered by the transport provider after returning from the TransportLogoff call.

A transport provider that can handle any type of recipient can return NULL in lpppszAdrTypeArray. LAN-based messaging systems that support a variety of gateways commonly do this. Such a transport provider should be installed last in the MAPI and MAPI spooler priority order of transport providers within the profile.

A transport provider that does not support outbound messages dispatched to it based on address type should return a single zero-length string in lpppAdrTypeArray. If a transport provider supports no recipient types, it should pass NULL for the MAPIUID structure and an empty string for the address type.

For more information on working with address types, see Displaying and Editing Addresses with Simple MAPI3IO50A.

See Also