Logo WHITE MESA SOFTWARE
Home   Download   Links   Documentation
 

An Email/HTTP Gateway Service for SOAP

Version 1.0

Summary

The White Mesa Email/HTTP Gateway Service implementation consists of:

  • The Gateway server, implemented as a Windows NT Service.
  • A GUI Configuration Tool used to configure the server.

This application allows a loosely coupled mode of accessing a SOAP service node, without the need for directly connecting to the service via HTTP as usual. SOAP request messages are pulled down from a POP3 mailbox periodically and then forwarded to the associated SOAP service node for processing. In this way:

  • Intermittently connected/available SOAP service nodes can be accommodated.
  • SOAP service nodes behind a firewall can still receive requests.
The request/response flow is as follows:
  • The SOAP request message is sent by the client as a MIME message via SMTP to a destination email address corresponding to a POP3 mailbox. The convention for encapsulating the SOAP envelope in a MIME email message is specified in the proposed SMTP Transport Binding for SOAP.
  • The MIME message is pulled from the POP3 mailbox by the Gateway Server.
  • The Gateway Server extracts the SOAP request message envelope from the MIME message.
  • The SOAP request message is optionally processed by an input "filter" to effect any desired transformations.
  • The SOAP request message is forwarded by the Gateway Server to the proper SOAP service node via HTTP.
  • In turn, the Gateway Server receives the SOAP response message from the SOAP service node over the HTTP connection.
  • The SOAP response message is optionally processed by an output "filter" to effect any desired transformations.
  • The Gateway Server packages the SOAP response message envelope into a MIME message and returns it to the client via SMTP, using the return email address found in the request message.
 

What's new in Version 1.0?

This is the initial release.

 

Download Email/HTTP Gateway Package

 

Details...

The White Mesa Email/HTTP Gateway for SOAP server functions as a POP3 client which periodically polls a list of one or more POP3 mailboxes (on one or more hosts) for messages. It expects these to be MIME messages wrapping SOAP Request message envelopes per the proposed SMTP Transport Binding for SOAP. The MIME messages are expected to be of Content-Type "text/xml" with character encodings "utf-8", "utf-16", and "us-ascii" accepted. These messages are also expected to be encoded for email transport with Content-Transfer-Encoding mechanisms "base64" or "quoted-printable" (only). After each mailbox is polled, a worker thread is created to process the messages that have been retrieved from it, while the POP3 client moves on to the next mailbox in the list. The worker thread proceeds to process the messages retrieved from the mailbox in the background.

The SOAP request message envelope is extracted from the MIME wrapper, and the Content-Transfer-Encoding of the message (e.g. "base64") is reversed to obtain the original message content. Other relevant information is stored, e.g. the message ID and the return address to which the response message needs to be sent.

If the mailbox is configured to submit received messages to a "filter" component for processing, the message is converted to a BSTR (UTF-16) and passed along to the filter. The filter component serves to apply any transformations that may be needed, e.g. applying an XSLT transformation to the XML document contained in the SOAP request. The output of the filter is received as a BSTR (UTF-16) and is then converted to UTF-8 encoding. If no filter is configured for input message processing, the message retains its original character encoding.

An HTTP connection is then opened and the SOAP request message sent to the service node associated with the mailbox (the URL of the node is a configuration item).

The SOAP response message from the service node is received, and if the mailbox is configured to submit the message to a "filter" component for processing, the message is converted to a BSTR (UTF-16) and passed along to the filter. The filter component serves to apply any transformations that may be needed, e.g. parsing the SOAP response message envelope and generating a non-XML prose message expressing the information received in the SOAP response (for human readers). The output of the filter is received as A BSTR (UTF-16) and is then converted to UTF-8 encoding. If no filter is configured for output message processing, the message retains its original character encoding (as indicated by the "Content-Type" HTTP header found in the HTTP response).

The response message is packaged in a MIME message, and the Content-Transfer-Encoding used in the request message is applied to it. The proper "Content-Type" and "Content-Transfer-Encoding" headers are inserted. A "Message-Id" header is generated for the response message, and the "Message-Id" value of the request message is referenced in the "In-Reply-To" header. Also, the value of the "Subject" header received in the request message is echoed back as the value of the "Subject" header in the response message.

An SMTP session is then initiated with the SMTP host associated with the mailbox (the host name and port nbr are configuration items). The response message is then sent to the return address contained in the request message.

Finally, an entry recording information about the message is written to the log file if logging has been enabled. Enabling the "verbose" mode causes the contents of the request and response messages to be written to the log as well. Here is an example of a non-verbose log entry:

2001-11-15T07:09:31Z FROM: <cunnings@whitemesa.com> TO: <soap@whitemesa.com> SERVICE: <http://delta.whitemesa.net/interop> ERROR: FAILED TO PROCESS MESSAGE BODY

Message Filters

The Gateway Server supports the use of COM Automation Servers as message "filters" to allow user defined processing to be applied to:

Automation Servers are specified by their "ProgId" in the configuration data for a mailbox/SOAP service pair. Two filters may be specified, the "input" and "output" filters. These servers must support a Dispatch method named "OnProcessMsg" with return type BSTR, and two input parameters, "Message" (BSTR), and "IsInputMsg" (VARIANT_BOOL). A declaration in IDL (for C++ implementations) looks like this:

[id(1), helpstring("method OnProcessMsg")] HRESULT OnProcessMsg([in] BSTR Message, [in] VARIANT_BOOL IsInputMsg, [out, retval] BSTR *returnMsg);

A VB implementation (in an ActiveX Dll project) might look like this:

Public Function OnProcessMsg(Message As String, IsInputMsg As Boolean) As String
If IsInputMsg = True Then
OnProcessMsg = ProcessRequest(Message)
Else
OnProcessMsg = ProcessResponse(Message)
End If
End Function

The "Message" parameter contains the SOAP message envelope, and the "IsInputMsg" parameter is used to distinguish between a call to process an input message and a call to process an output message. This is useful if a single Automation Server is specified as both the input and output filter. It is the duty of the filter component to return a BSTR value containing the transformed SOAP message. In the case of the input filter, this message is immediately forwarded to the SOAP service node over HTTP, and must represent a proper SOAP request message envelope. In the case of the output filter, this message is sent back to the client as a MIME message over SMTP. It may be desirable in some cases for the output filter to transform the SOAP response message into a non-XML message suitable for human readers.

Configuration

Configuration of the Gateway Server is accomplished with a GUI tool, "wmsmscp.exe". This is a standalone application which is used to:

When first launched, it looks like this:

Service Descriptions may be added, edited, or deleted, and the general settings maintained.

Here is a view of the Service Description Editor:

A Service Description consists of the following information:

  • Service Description Name... This is the name used to refer to the service description.
  • Enabled... If checked, the entry is active, and normal processing will occur at the interval specified by the "Polling Interval" setting mentioned above. If not checked, the entry is inactive, and is skipped over when processing occurs.
  • SOAP Service URL... The URL of the SOAP service node to which request messages are forwarded via HTTP.
  • SOAPAction...The SOAPAction value to be used when the request message is forwarded. This is determined by the SOAP node itself. If the SOAP service is described in a WSDL document, the SOAPAction value should be specified there.
  • POP3 Server Host Name... The host name for the POP3 server from which request messages will be obtained.
  • Port Nbr... The number of the port on which the POP3 server is listening for connection requests (usually 110).
  • Mailbox Name... The name of the mailbox on the POP3 server from which the messages are to be downloaded.
  • Password... The password for the mailbox.
  • SMTP Server Host Name... The host name for the SMTP server which will be used to send the response message back to the client.
  • Port Nbr... The number of the port on which the SMTP server is listening for connection requests (usually 25).
  • SMTP Client Host Name... The host or domain name that is to be used when connecting to the SMTP server, as the argument for the "HELO" command sent to the SMTP server ("domain" argument).
  • SMTP Client Address... The email address associated with the Gateway Server. When acting as an SMTP client, this is passed in as the value of the "From:" argument for the "MAIL" command sent to the SMTP server ("reverse-path" argument).
  • Input Filter ProgID... The ProgId of the Automation server component serving as the input message filter. If this field is empty, then no filter is called.
  • Output Filter ProgID... The ProgId of the Automation server component serving as the output message filter. If this field is empty, then no filter is called.
  • Log File Path... The full path of the log file to be used with this Service Description. A "browse" button is provided to launch a file selection dialog box if desired.
  • Logging Enabled... If checked, logging is enabled.
  • Verbose Mode... If checked, the contents of the request and response messages are written to the log file.

Implementation details

The Gateway Server at one time or another acts as a POP3 client, an HTTP client, and an SMTP client. This functionality is implemented by classes WMPOPSocket, WMHTTPRequestSock, and WMSMTPSocket respectively. These inherit from class WMWinSocket2, a Winsock2 client socket implementation. Additional details may be learned by looking at the source.

Platform and Compiler

Win32, using Winsock2. Developed using Visual C++ 6.0 and tested on Win2000. The standalone GUI configuration tool for the service is an MFC app.

Send questions, comments, etc. to:

cunnings@whitemesa.com

 
 

Download Email/HTTP Gateway Package

Home   Download   Links   Documentation

Copyright © 2000, 2001 by Robert Cunnings.   cunnings@whitemesa.com  Last modified: Dec 31, 2001