| Platform SDK: Exchange Server |
Gateway developers are not restricted to using the HrGWResolveProxy and HrGWResolveAddress functions to look up addresses. You can implement your own versions of these functions if necessary because the provided implementations simply use MAPI methods to find address information. The ADDRLKUP sample code does this. The ADDRLKUP sample code is in the \BKOFFICE\SAMPLES\EXCHANGE\LIBSRC\ADDRLKUP directory.
For simplicity, the provided implementations of HrGWResolveAddress and HrGWResolveProxy have been written to act on a single address at a time. However, the underlying MAPI methods IABContainer::ResolveNames and IAddrBook::PrepareRecipients can act on several addresses at a time, with better overall performance. The MAPI Programmer’s Reference gives detailed information about MAPI methods. If your gateway is often used to send or receive messages with large numbers of recipients, it may be necessary for you to implement your own versions of these functions to achieve better performance.
HrGWResolveProxy uses the IAddrBook::PrepareRecipients method to look up addressing information for outgoing recipients. Calls to IAddrBook::PrepareRecipients can return any specified set of recipient properties. If you are implementing your own version of HrGWResolveProxy you can optimize your IAddrBook::PrepareRecipients calls to return all recipient properties that you might need, not just address properties. This will avoid later GetProps calls to retrieve information like display names, and cut down on remote procedure calls generated by your gateway.
The following recipient properties are of particular interest to gateways, so you should request them all. For information about the following properties, see the MAPI Programmer’s Reference:
PR_ENTRYID
PR_DISPLAY_NAME
PR_OBJECT_TYPE
PR_ADDRTYPE
PR_DISPLAY_TYPE
PR_SEARCH_KEY
PR_EMAIL_ADDRESS
PR_TRANSMITTABLE_DISPLAY_NAME
PR_SEND_RICH_INFO
In addition, PR_EMS_AB_PROXY_ADDRESSES is useful to gateways.
HrGWResolveAddress uses the IABContainer::ResolveNames method to match foreign addresses on incoming mail with proxy addresses on Microsoft Exchange Server users. Like IAddrBook::PrepareRecipients, IABContainer::ResolveNames can return any set of properties for the recipients that it finds. If you are implementing your own version of HrGWResolveAddress, you should consider returning all of the following properties with each call to IABContainer::ResolveNames. (For information about specific properties, see the MAPI Programmer’s Reference.)
PR_ENTRYID
PR_DISPLAY_NAME
PR_OBJECT_TYPE
PR_ADDRTYPE
PR_SEARCH_KEY
PR_EMAIL_ADDRESS
PR_TRANSMITTABLE_DISPLAY_NAME
PR_SEND_RICH_INFO
The EMS_AB_ADDRESS_LOOKUP flag should be set when IABContainer::ResolveNames is used to match incoming foreign addresses with proxy address. When the EMS_AB_ADDRESS_LOOKUP flag is set, IABContainer::ResolveNames will only find exact matches on proxy addresses. Partial matches are ignored, as are any other search attributes. Any Microsoft Exchange Server directory object with defined proxy addresses can be found this way, including objects marked as hidden from the address book.
Most of these optimizations are used by the sample gateway provided with this SDK. The sample gateway source code is in the \BKOFFICE\SAMPLES\EXCHANGE\GWSAMPLE directory.
Finally, note that looking up proxy addresses is only one of several possible ways to associate foreign addresses on incoming mail with a Microsoft Exchange Server recipient. The two most common alternatives are algorithmic mapping and address encapsulation.
Algorithmic mapping can be used when there is a well-defined, fixed relationship between the format of an incoming foreign address and some equally well-defined, and preferably unique, attribute of the Microsoft Exchange Server user’s address. For example, if an organization’s Internet addresses are based on users’ mail aliases, the SMTP address “PatParkes@trager.com” can be mapped to the Microsoft Exchange Server user whose alias is “PatParkes.”
Address encapsulation is a more extreme version of algorithmic mapping in which an entire address is encapsulated within another address format. For example, an SMTP gateway might understand the address [PROFS:NODE1/PATP]@microsoft.com as an instruction to redirect the message to a PROFS gateway, addressed to NODE1/PATP. Microsoft Exchange Server gateways can use the IAddrBook::CreateOneOff method to implement support for address encapsulation.