Karen Worth
Microsoft Corporation
Additional contributions from Arsenio Locsin,
Bronwyn Calsyn, and Michael Reeves
November 1999
Summary: This article shows how to build, install, and configure the sample gateway source code in the September 1999 edition of the Platform SDK. This article should be used with Microsoft Exchange Development Kit (EDK) documentation. (22 printed pages)
Introduction
Sample Gateway Components
Using the Sample Gateway
Troubleshooting the Sample Gateway
Answers to Frequently Asked Questions About the Sample Gateway
Additional References
The Microsoft® Exchange Development Kit (EDK) Sample Gateway (SGW) is a group of source code files that compile into an application that transfers incoming and outgoing mail messages. The sample gateway demonstrates common gateway features, such as mail transfer from a foreign mail system into a Microsoft Exchange Server and mail transfer from an Exchange Server to another mail system. You can use the sample gateway to send messages between two servers using a shared file system as the underlying transport mechanism.
The gateway receives inbound messages as files. The gateway then opens these files and calls a message conversion dynamic-link library (DLL) to create messages from the information contained in the files. The gateway then writes these message files to an inbound Folder in the Exchange Server Private Information Store.
The gateway receives outbound messages as Messaging Application Programming Interface (MAPI) messages in the outbound folder in the Exchange Server Private Information Store. The gateway then converts and writes these message files to the out directory.
The sample gateway performs message translation and transfer functions, and generates notification messages as requested.
The source code files for the EDK sample gateway are available from the September 1999 edition of the Platform SDK.
Note The Platform SDK available for download from the Microsoft Web site does not contain the source code files for the sample gateway.
After installing the Platform SDK, you can find the sample code files in the Platform SDK\samples\DbMsg\Exchange folder.
This article assumes you have the following:
The sample gateway has the following minimum requirements:
Domain Name: DomainTest
You are logged on as the Exchange Service Account.
Program Directory: C:\Exchsrvr
Server Name: LPEverett5
Organization Name: Organization
Site Name: Site
Service Account Name: Service-Account
Password: Password
The sample gateway contains the following components:
MTS-IN and MTS-OUT folders—A mailbox with these two Message Transfer System (MTS) folders is created in the Information Store when the gateway is installed on an Exchange server. Incoming messages are placed in the MTS-IN folder for the Exchange server to process. The Exchange server, in turn, places outgoing messages in the MTS-OUT folder for the gateway to process. You can view the files in these folders using the Message Store Viewer (mdbvu32.exe) or the Queue Viewer utilities. The Message Store Viewer is an executable file in the mssdk\bin folder. The Queue Viewer source code is in the \mssdk\samples\DbMsg\Exchange\QueView folder. You have to build the source files into an executable file.
Administrator Extension (sgwadmin.dll)—Adds a property sheet to the Exchange Administrator so you can manage the gateway directory object. To configure the gateway, you must install an Admin-Extension object in the Exchange directory and copy the administrator extension DLL file (sgwadmin.dll) to a specific location on the server by using the installation program, extninst.exe.
You can use the Exchange Administrator to determine what administrator extension DLL is installed. Under the Configuration object, select Add-ins; an object is installed for the extension DLL. The properties for this object show the name of the DLL file. The location of the file is similar to:
<install point of the exchange server>\Add-ins\<gateway name>\<platform>
For example:
c:\exchsrvr\Add-ins\SGW\i386
Proxy Generator (proxygen.dll)—Each Microsoft Exchange Server recipient object has several proxy addresses, at least one for each foreign address type known to the system. A proxy generator DLL creates the proxy addresses for an addresses type, such as EDK. The EDK provides a proxy generator DLL file (proxygen.dll) and an installation program (addrinst.exe).
You can use the Exchange Administrator to see what proxy generators are installed. Under the Configuration object, select the Addressing object, select the E-mail Address Generator object, and then observe the objects for all the installed proxy generators. The properties of the object reveal the name of the DLL file. To find the file location, run the Exchange Administrator program in raw mode (Admin.exe /r) and select the proxy generator object. From the File menu, select Raw Properties. The Directory Name property contains the file location. The file is at the following location:
<install point of the exchange server>\Address\<contents of Directory Name>
For example:
c:\exchsrvr\Address\EDK\i386
Message Translator (ipm_in.dll and ipm_out.dll)—Converts incoming and outgoing messages to the MAPI message format and the message format of the foreign system. This conversion is done based on the message class of incoming and outgoing messages. RFC-822 messages are converted to MAPI messages using the file IPM_IN.DLL. The IPM_OUT.DLL is used to convert MAPI messages into RFC-822 messages.
These two message translator DLL files should be in a directory in the path, such as the winnt\system32 directory. These DLLs are also registered in the registry under the following key:
Hklm\software\classes\MAPI Conversions\ipm_in.dll\GetTrivialVector
and
Hklm\software\classes\MAPI Conversions\ipm_out.dll\GetTrivialVector.
To install the message translator files, use the installation program, Xlatinst.exe.
Gateway Service (gwsample.exe)—Monitors, translates, and transfers incoming and outgoing messages. When the Microsoft Exchange Server receives a message bound for a foreign server, the Exchange server puts this message into the gateway's MTS-OUT folder. The gateway then maps the addresses of the message recipients to the format of the foreign system using the proxy generator. The gateway also translates the message content to a format that can be processed by the foreign system using the message translator. After this translation, the gateway writes the message out to the \out directory for the foreign system to pick up.
For messages from a foreign system, the gateway receives the message and maps the message addresses to the corresponding Exchange Server address using name resolution. The gateway translates the message content using the message translator and then delivers the message to the gateway's MTS-IN folder of the Exchange Server.
The Gateway Service is installed using the Gateway Service Installer program servinst.exe.
OUT directory—The gateway writes messages to be delivered to the foreign system into this directory.
IN directory—The gateway picks up messages from a foreign system in this directory. An incoming message folder is a place for the gateway to hold incoming messages prior to processing. Without an incoming message folder, the gateway must process all incoming messages immediately, causing performance or memory subsystem problems.
One-off Address Template—creates the following:
Using this template is not required, but is highly recommended. The EDK provides a utility (tmplinst.exe) to install a one-off address template.
You can use the Exchange Administrator to determine which one-off address templates are installed, as shown below in Figure 1.
Figure 1. The One-Off Address Template object in the Microsoft Exchange Administrator displays the One-Off Address Templates installed in the gateway.
This section demonstrates how to install and configure the sample gateway. To use the sample gateway, you need to do the following:
This section shows you how to:
You can build the sample gateway source code into DLL and executable files through the command line. You cannot build these files using the Visual C++ Integrated Design Environment.
This section assumes that you installed the Platform SDK files in the C:\Platform SDK folder. If you installed the Platform SDK in another folder, make the appropriate changes to the commands.
C:\> vcvars32
C:\> setenv c:\Platform SDK
| File | Description | Source Code Folder |
| Addrinst.exe | Proxy Generator Installer | \Edkinstu\AddrInst |
| Extninst.exe | Administrator Extension Installer | \Edkinstu\ExtnInst |
| Gwinst.exe | Gateway Object Installer | \Edkinstu\GWInst |
| Gwsample.exe | Gateway Executable | \GWSample |
| Ipm_in.dll | RFC-822 to MAPI Message Translator | \IPM_In |
This section shows you how to manually install the gateway sample. The sample gateway documentation in the Platform SDK says you can install the sample gateway by building and running the sample gateway installation program gwsetup.exe. However, the source code is not included in the Exchange Development kit, so you can only install the sample gateway using the manual method.
| Folder | File |
| C:\Exchsrvr\Address\EDK\i386 | Proxygen.dll |
| C:\Exchsrvr\Add-ins\SGW\i386 | Sgwadmin.dll |
| C:\Sgw\ | Gwsample.exe |
| C:\Sgw\In | No files |
| C:\Sgw\Out | No files |
Tip Create a batch file that executes these commands. You can modify this batch file to remove the gateway.
C:\>Xlatinst.exe /dll=IPM_IN.DLL /CLASSES=ENVELOPE.IPM%REPORT.IPM /POINT=SAMPLEGW.INBOUND
Note If you use this command in a batch file, insert an additional % symbol when defining the CLASSES; that is,
/CLASSES=ENVELOPE.IPM%%REPORT.IPM
C:\>Xlatinst.exe /dll=IPM_OUT.DLL /CLASSES=ENVELOPE.IPM%REPORT.IPM /POINT=SAMPLEGW.OUTBOUND
Note If you use this command in a batch file, insert an additional % symbol when defining the CLASSES; that is,
/CLASSES=ENVELOPE.IPM%%REPORT.IPM
C:\>Addrinst.exe /sitedn=/o=Organization/ou=Site /name=edk /machine=i386 /type=edk /proxydll=\\lpeverett5\address\edk\i386\proxygen.dll /server=LPEverett5 /gwproxy=EDK:@Site.Organization.com
C:\>Extninst.exe /sitedn=/o=Organization/ou=Site /display_name="SGW EDK SAMPLE GATEWAY EXTENSION" /machine=i386 /name=SGW /extdll=\\LPEverett5\ADD-INS\SGW\i386\sgwadmin.dll /server=Server
C:\>Gwinst.exe /sitedn=/o=Organization/ou=Site /display_name=SGW /name=SGW:i386 /addrtype=edk /server= LPEverett5 /extname=sgw
C:\>Servinst.exe /sitedn=/o=Organization/ou=Site /display_name=SGW /service=SGW /exe=c:\SGW\Gwsample.exe /server= LPEverett5 /objname=SGW:i386 /objtype=gateway /account=Domain\Service-Account /password=Password
The sample gateway is configured in the Options tab of the Exchange Administrator. Configure the following properties:
Address Type: EDK
Display Name: System Administrator
E-mail Address: SysAdmin
Messages to Process: Check both Inbound and Outbound.
| Inbound | Outbound | |
| Threads | 4 | 4 |
| Messages Per Thread | 1 | 1 |
| Sleep per Message: | 0 | 0 |
| Polling Interval: | NOTIFICATION | NOTIFICATION |
| Directory | C:\Sgw\In | C:\Sgw\Out |
| Converter | Samplegw.inbound | Samplegw.outbound |
Figure 2. The Options tab of the Exchange Administrator displays the configuration of the sample gateway.
Address Type—Refers to address type of messages passing through the gateway. This should be set to EDK. This determines what encapsulation and what address type will be used when address resolution is performed on a Custom Recipient and when assigning return addresses on messages sent through the gateway. Changing this may cause adverse message routing.
System Administrator—Display name and e-mail address of the system administrator.
Messages to Process—Indicates whether the gateway will process inbound and outbound messages. A checked box indicates that the gateway will process that type of message. The remaining fields in the dialog box have two columns of values, one for inbound messages and one for outbound messages.
Threads—Number of threads used to process messages.
Messages Per Thread—Number of messages processed in each thread.
Sleep Per Message—The length of time it takes to process one message. If the gateway finishes processing a message before this interval has elapsed, it waits until the end of the interval before starting to process the next message.
Polling Interval—If this is set to NOTIFICATION, the gateway uses notifications to determine when to process the next message. For incoming messages, it uses the first change notification; Windows NT Server tells the gateway when there is a change in the incoming message directory. For output messages, it uses the MAPI notification mechanism to determine when messages arrive in the MTS-OUT folder. If this is set to a value greater than –1, the gateway waits that many milliseconds before trying to process another message.
Directory—Name of the directory from which the gateway reads incoming messages or to which it writes outgoing messages. The directory name must be preceded by a backslash (\) and include the full path. You can use universal naming convention (UNC) names here.
Converter—Pointers to the conversion DLLs for the inbound and outbound messages. This will be the Point value for the registry key for the converters. For example, the value for the Inbound Converter is as follows:
HKEY_LOCAL_MACHINE\Software\Classes\Conversions\ipm_in.dll\GetTrivialVector
After configuring the sample gateway, you can start the sample Gateway Service.
This section shows you different ways to troubleshoot your sample gateway.
The gateway will now process the mail and send it to the original sender's mailbox.
To run the sample gateway under the debugger, you need to artificially run the gateway program as a console application rather than an NT service. You can run the sample gateway as a console application by linking the sample gateway to the library file, Winwrap.lib:
Please see the article "XLATDRIV: Translating Messages" in the Platform SDK documentation for more information about this program.
The TRACK sample console application demonstrates how to use three functions to log tracking information to the file. The source code to this sample application is in the :\mssdk\samples\DbMsg\Exchange\LibSrc\EDKTrack folder.
For more information about this sample application, see the article "TRACK: Tracking and Auditing Messages" in MSDN.
The Track Message tool is part of the Microsoft Exchange Server Administrator program. You can use it to debug applications that track the flow of messages. This utility determines the origin and destination of messages as the messages are processed by your application.
Figure 3. The Track Message Tool tracks the flow of messages.
Log on to the gateway mailbox and look at the MTS-IN and MTS-OUT folders using an Administrator Extension DLL, QUEVIEW DLL, which you install using EXTINST.EXE. Please see the article "QUEVIEW: Listing Gateway Folders" on MSDN for a discussion on this topic.
The message store viewer (MDBVU32.EXE) is a MAPI client application that helps you debug your application by providing a view of information in a mailbox or any other object in an information store. This application displays the following information:
The message store viewer can be used to view, set, and change properties of a mailbox or information store. The message store viewer shows what properties are available on each message, the format of the properties, and how you can use these properties. You can use this information to customize your gateway application.
You can also use the message store viewer to debug messages. If submitting a message causes a failure, save the message and look at all the message properties with the message store viewer, instead of writing code to dump the message's properties. See Figure 4.
Figure 4. The Message Store Viewer displays the properties of a message.
The debug version of the Exchange SDK library, called ExchSDKd.LIB, includes a collection of macros and asserts that can be very useful when debugging a server application. Many calls, such as the ASSERTERROR and DEBUGPUBLIC macros, can be inserted in the code as it is written. They then provide debugging information as well as future data. The best way to become familiar with available calls is to study the ExchSDKd library and header file source code.
Proxy generation DLLs are used to generate proxy addresses, which are addresses of foreign system users as expressed on Microsoft Exchange Server. Debugging proxy generation DLLs requires a few extra steps because the library is loaded dynamically only when needed. To trace a proxy generation DLL in the Microsoft Visual C++ debugger, you must load the calling program into Visual C++. All calls into the proxy generation DLL are made from the System Attendant service of Microsoft Exchange Server, which is implemented by MAD.EXE.
The Administrator program calls MAD.EXE. This loads your DLL and calls its initialization routines, as well as any routines relevant to the action you just performed.
After your proxy generation DLL is loaded, open its source and set the breakpoints.
Using the Administrator program, perform additional actions that will call your proxy generation DLL. Now the debugger will stop at your breakpoints.
If you must begin tracing at your initialization code, set a hard-coded breakpoint in that code. After your proxy generation DLL is loaded by performing one of the previously described actions, the hard-coded breakpoint will be hit. You can trace your code in the debugger from that point.
The following steps show how to debug and set a breakpoint in an Administrator extension DLL in Visual C++ Version 6.0.
The Administrator program calls your DLL. The debugger will now stop at any breakpoints you have set.
The following are some of the error messages that might appear when using the sample gateway. This section shows you how to prevent these error messages from displaying:
Pop-up 2140 "internal inconsistency"—Caused by the gateway not being completely configured. Make sure that directory paths for the directories are complete and that all fields have data in the Options tab of the gateway properties. This error usually appears when you start the Gateway Service.
Event ID 7023 "The SGW service terminated with the following error: The security account database contains an internal inconsistency."—Caused by the service not being configured completely. Make sure the gateway is completely configured in the Options tab of the gateway properties.
Event ID 7023 "The SGW Service terminated with the following error: The service did not start due to a logon failure."—Caused by duplicate keys in the registry for the message converter files or if the converter files are not available.
Start Regedit, and go to the HKey_Local_Machine\Software\Classes\Mapi Conversions key.
Make sure there are only two entries in MAPI Conversions key, as shown in Figure 5.
Figure 5. The MAPI Conversions key should only contain the ipm_in.dll and the ipm_out.dll keys.
In the Ipm_in.dll key, there should be one key called GetTrivialVector. The GetTrivialVector key should contain the following three values:
Classes: REG_MUTI_SZ: MESSAGE.IPM REPORT.IPM
OPTIONS: REG_SZ:
Point:REG_SZ:SAMPLEGW.INBOUND
In the Ipm_out.dll key, there should be one key called GetTrivialVector. The GetTrivialVector key should contain the following three values:
Classes: REG_MUTI_SZ: MESSAGE.IPM REPORT.IPM
OPTIONS: REG_SZ:
Point:REG_SZ:SAMPLEGW.OUTBOUND
Event ID: 9 "The description for Event ID ( 9 ) in Source ( GWSAMPLE ) could not be found. It contains the following insertion string(s): SAMPLEGW.OUTBOUND, REPORT.IPM.NOTE.NDR."—This occurs because the MAPI Conversion registry setting is set to envelope.ipm only, and a report needs to be processed. To resolve this error, modify the Classes key of the IPM_IN and IPM_out .dll to key in the registry to be: Message.IPM REPORT.IPM.
Event ID: 9 "The description for Event ID ( 9 ) in Source ( GWSAMPLE ) could not be found. It contains the following insertion string(s): SAMPLE.INBOUND, ENVELOPE.IPM."—This is caused by the connector with a blank Converter field in the Options tab of the gateway properties. Enter the appropriate text in the Converter field. See Configuring and Starting the Sample Gateway for more information.
Pop-up box 1069 "the service did not start due to a logon failure"—caused by one or more of the following conditions:
Make sure that the startup account has the correct password and the appropriate rights. Using Regedit, verify that the HKey_Local_Machine\Software\Classes\Mapi Conversions registry key has only two entries.
Event ID: 1026 "An error occurred with the following call stack: ..."—caused by the PR_MESSAGE_SUBMISSION_ID or MTSID property containing a slash (/), semi-colon (;), or quotation marks("). Make sure the gateway does not add these characters to the PR_MESSAGE_SUBMISSION_ID or MTSID property.
This section shows you how to remove the sample gateway from your Exchange Server. The section assumes you have installed and configured the sample gateway according to Installing the Sample Gateway.
addrinst.exe /sitedn=/o=Organization/ou=Site /name=edk /machine=i386 /type=edk/proxydll=\\LPEverett5\address\edk\i386\proxygen.dll /server=LPEverett5/gwproxy=EDK:@Site.Organization.com /delete
extnist.exe /sitedn=/o=Organization/ou=Site /display_name="SGW SAMPLE GATEWAY EXTENSION" /machine=i386 /name=SGW /extdll=\\ LPEverett5\ADD-INS\SGW\i386\sgwadmin.dll /server=LPEverett5 /delete
gwinst.exe /sitedn=/o=Organization/ou=Site /display_name=SGW /name=SGW:i386 /addrtype=edk /server= LPEverett5 /extname=SGW /delete
servinst.exe /sitedn=/o=Organization/ou=Site /display_name=SGW /service=SGW /exe=c:\SGW\gwsample.exe /server= LPEverett5 /objname=SGW:i386 /objtype=gateway /account=Domain\ Service-Account /password=Password /delete
Note Third-party gateways installed in your Exchange Server may also use these keys. If you have other gateways installed on this machine, leave these keys intact.
You can modify the sample gateway to transfer mail from a foreign system to the Internet using the Exchange IMS. The sample translator DLL, IPM_IN.DLL, addresses the mail messages with EDK-encapsulated addresses. For mail—sent from a client on the foreign mail system addressed to an Internet user—to be routed out to the Internet, the IPM_IN.DLL must be modified to strip the EDK encapsulation for Internet bound messages and to use Simple Mail Transfer Protocol (SMTP) encapsulation instead.
The following illustration in Figure 6 shows how the IMS interacts with the gateway.
Figure 6. You can use the Exchange Intersite Messaging Service (IMS) to transfer mail from a foreign system to the Internet.
Yes, the sample gateway wraps the message incoming from a foreign system in an MTE before writing the message to the MTS-IN folder. The message that the gateway picks up from the MTS-OUT folder is also wrapped in an MTE.
Currently, the sample does not allow you to pre-configure the gateway.
All gateways must be able to handle the following message classes:
Make sure the MTE information exists and is complete, and the message has an PR_MTS_ID MAPI property.
Your Gateway Service can post messages to Public folders that are not replicated to the Exchange server by implementing one of the following options:
To gain a better understanding of the technologies presented here, please consult the following resources found on MSDN:
--------------------------------------------
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This article is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.
Microsoft is a registered trademark of Microsoft Corporation.
Other product or company names mentioned herein may be the trademarks of their respective owners.
Microsoft Corporation · One Microsoft Way · Redmond, WA 98052-6399 · USA