Test Ride with Microsoft Sample Gateway

Perhaps the first and the most logical step in learning how to implement your own gateway would be testing Microsoft sample gateway.
 

Installing Sample Gateway

Sample gateway consists of a number of components, such as the service executable file, message converters, and proxy generation DLL. You need to run Microsoft original setup program to install all of them properly. Installing only a Windows NT service as I describe in "Installing Gateway as a Windows NT Service" topic is not enough. If you have full Platform SDK installation the original setup program (Setup.exe) should be located in bin/samplegw subdirectory of your build environment (for example, C:/Mssdk/bin/samplegw). However, you may find this directory missing even if you have installed the latest and greatest Platform SDK. If this is the case - try to locate disk 5 of Development Platform U.S. (Platform SDK, March 1997) and install it from there.

If you run the setup program it will display a dialog to collect the following configuration details about gateway:

• Directory Display Name - display name for your Mail-Gateway object that will be displayed in SiteName/Configuration/Connections sub tree of Exchange Server directory (as observed via Microsoft Exchange Administrator).
• Service Display Name - Setup program will install sample gateway as a Windows NT service. This string is the name of this service that will be displayed in Control Panel/Services dialog.
• Service Account and Password.
• Service Directory - physical location on the hard disk where gateway will process files.

• If you run Exchange Administrator and navigate to SiteName/Configuration/Connections sub tree (or refresh its view if it's already running) - you'll see a new object with the name you specified before. You can double-click on this object and observe its properties.
• Control Panel/Services dialog will show a new Windows NT service with corresponding name. The service will appear in stopped state.
• A directory will be created on the hard disk (if it was not already there) with two sub folders called In and Out and gwsample.exe file. This file is in fact the service executable file.

To see all functionality of the sample gateway Microsoft recommends installing it on two Exchange servers, sharing its folders, creating custom recipients on both servers and sending test messages from one to another. I found this setup inconvenient and a little unrealistic because I do not have two NT servers with Exchange around. Perhaps better way of seeing whether gateway does anything would be testing it on one NT server. Here is how you do it:

• Start sample gateway through Control Panel/Services dialog.
• With Microsoft Exchange or Outlook client create a new recipient with EDK e-mail address type (explained below). Send a message to this recipient and observe gateway to process it. It will create a new message file in its Out folder which you could examine with notepad.

I must mention again that the above algorithm does not allow you to see all features of the gateway. However, it does show that gateway obviously does something in cooperation with Exchange server - and this would be just enough for now. One important nice feature of sample gateway installation program is that, among other things, it creates a new custom template for creating EDK address entries. You may notice that when creating new address entries you are presented with one more template in the list called EDK Address. And this is available to all clients on the site. I am describing creating custom address templates later in this chapter.
 

Modifications of Sample Gateway

Perhaps one of the first exercises that you can do with the this gateway would be slight modification of the code to see whether we can ask it to do specific tasks. Let us try to modify code so that it simply outputs some data to the debug screen, say, e-mail address of the recipient or its address type. Here is how you do it:

• First, compile sample code without any modifications. To do this create a new directory and copy all files found in Mssdk/samples/Exchange/gwsample to it. Then run nmake in context of this new directory (in Command Prompt change to new directory, then type "nmake" without quotes). Alternatively, you can do this in Visual C++ Developer studio by wrapping the makefile into project. This will be more convenient because you'll be able to modify files and compile them right away in the same environment. You may encounter two problems when compiling and linking. This may happen if you are using incorrect or incomplete version of Platform SDK. First, the BaseMake environment variable may be missing (set it up to point to bkoffice.mak file in the Include subdirectory of your build environment, for example: C:\BuildEnv\Include\bkoffice.mak). Second, ExchSdkD.lib library may be missing. You can build it yourself from source files that Microsoft provides as I describe in Building Debug Version of Exchange SDK Library topic.
• If everything goes smoothly, you'll see GwSample.exe file of about 1 MB in size created in its Win32/Debug sub folder. Replace gateway executable file with this one and see whether it functions normally (you'll need to stop gateway in order to do this).
• Second, open gwsample.c file, locate the ProcessMtsOut function and add the following line after local variable declarations:

• Third, recompile and replace the gateway. In order to see debug output start debug monitor at Command Prompt (type dbmon and press Enter). Send a message to EDK addressee and observe how gateway outputs your custom string.
• Finally, to see whether we can obtain and output e-mail address type from within sample gateway introduce two new variables and add the following code into HrConvertMtsOut function before the "// Divide recipient list into MAPI and non-MAPI recipients" comment:

 // BEGINNING of injected code
iValues = lpRows->aRow[0].cValues;
for ( iCounter = 0; iCounter < iValues; iCounter++ ) {

    if ( lpRows->aRow[0].lpProps[iCounter].ulPropTag == PR_EMAIL_ADDRESS ) {
 
        OutputDebugString( " E-mail address: " );
        OutputDebugString( lpRows->aRow[0].lpProps[iCounter].Value.lpszA );
   } else if ( lpRows->aRow[0].lpProps[iCounter].ulPropTag == PR_ADDRTYPE ) {
 
        OutputDebugString( " E-mail type: " );
        OutputDebugString( lpRows->aRow[0].lpProps[iCounter].Value.lpszA );
  }
}
// END of injected code

//
// Divide recipient list into MAPI and non-MAPI recipients
//
 
I have included the following two samples for your convenience: gwsample and GwSample_modified in the set of samples coming with this book. They are located in the "Gw/Sgw" subdirectory. The first one is unmodified gateway sample as it comes from Microsoft, and the second contains the fragment listed above. If you see unfamiliar expressions in the above fragment - perhaps you should familiarize yourself with MAPI. "Inside MAPI" book would be a good place to start. When you run such gateway it'll output e-mail type and address information to debug monitor window.
 

Running Sample Gateway from Command Prompt

To run gateway at command prompt type:

START GWSAMPLE NOTSERV <GUID>

where GUID is the gateway's GUID from the registry. For example, for my recent installation I type:

START GWSAMPLE NOTSERV "43804AB1-6533-11D1-8E6F-00608C21FEA2"

Obviously, GUID in your case will be different. How can I test whether gateway was actually started with this command? First - make sure that your gateway service is not running before you do this (use Control Panel). Second, check whether gwsample.exe is in your task list. Finally, send a message to the gateway and see whether it is being normally delivered. In addition, you can use modified version of the gateway as I have explained above, run it together with debug monitor (dbmon at command prompt), and see whether it actually outputs information as you requested.
 
 

Running Sample Gateway under Debugger

NOTSERV "43804AB1-6533-11D1-8E6F-00608C21FEA2"

As an experiment put a breakpoint on a modified section of the code and observe it break there when you send a message through gateway.

The above easy exercises showed how you could install, modify and use sample gateway. The next logical step would be determining whether we could customize it to process our own address type, say "YYY" instead of "EDK". This is the subject of the following discussion.