Share via

Implementing Address Lookup Functions

  • Article

Implementing Address Lookup Functions

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release. Gateway developers are not restricted to using the HrGWResolveProxy and HrGWResolveAddress functions to look up addresses. Because the provided functions use MAPI methods to find address information, you can implement your own versions of these functions if necessary. The ADDRLKUP sample code performs this task. The ADDRLKUP sample code is in the \\EXCHANGE SDK\SDK\SAMPLES\DBMSG\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. This improves overall performance. 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.

For more information about MAPI methods, see the MAPI Programmer's Reference Online link.

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 avoids later GetProps calls to retrieve information such as display names. It also cuts down on remote procedure calls generated by your gateway.

The following recipient properties are particularly important for gateways, so you should request them all. For more information about these properties, see the MAPI Programmer's Reference Online link.

  • PR_ENTRYID
  • PR_DISPLAY_NAME
  • PR_OBJECT_TYPE
  • PR_ADDRTYPEPR_DISPLAY_TYPE
  • PR_SEARCH_KEYPR_EMAIL_ADDRESS
  • PR_TRANSMITTABLE_DISPLAY_NAME
  • PR_SEND_RICH_INFO

The PR_EMS_AB_PROXY_ADDRESSES property, which is not a recipient property, is also important for gateways.

HrGWResolveAddress uses the IABContainer::ResolveNames method to match foreign addresses on incoming messages with proxy addresses of 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 Online link.

  • 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. Any other search attributes are ignored, as well. Any recipient 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 the Exchange Software Development Kit (SDK). The Sample Gateway source code is in the \\EXCHANGE SDK\SDK\SAMPLES\DBMSG\EXCHANGE\E2K SGW\GWSAMPLE directory.

Alternatives to Proxy Address Lookup

Looking up proxy addresses is only one of several possible ways to associate foreign addresses on incoming e-mail with an 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 Exchange address. For example, if the Internet addresses of an organization are based on the e-mail aliases of users, the SMTP address JonathanMollerup@microsoft.com can be mapped to the Exchange user whose alias is JonathanMollerup.

Address encapsulation is a more extreme version of algorithmic mapping. In address encapsulation, an entire address is encapsulated within another address format. For example, an SMTP gateway might understand the address [MS Mail:microsoft/sales/JonathanMollerup]@microsoft.com as an instruction to redirect the message to an MS Mail gateway, which supports an alternative address format for Jonathan Mollerup. Exchange gateways can use the IAddrBook::CreateOneOff method to implement support for address encapsulation.

Send us your feedback about the Microsoft Exchange Server 2003 SDK.

Build: June 2007 (2007.618.1)

© 2003-2006 Microsoft Corporation. All rights reserved. Terms of use.