ATL Server SOAP Request Processing Model

To get the most out of this chapter, you need a good understanding of ATL Server and the Simple API for XML (SAX) parsing model. Changing the transport channel and performing custom parsing of the SOAP methods parameters are based on a black-box approach. These changes don t require you to make modifications to the ATL Server files. The custom types handling, however, does require you to make some modifications to the ATL Server files ( specifically , atlsoap.h). Such modifications aren t supported by Microsoft, but they may be very useful, and for advanced developers they often make a lot of sense.

In this section we perform a brief analysis of the ATL Server processing model for a SOAP request. Each Web service is represented on the server side by a class that s implemented using the soap_handler and request_handler attributes. These attributes make the class behave as a request handler (the working module in the ATL Server architecture) and also as a SOAP handler (i.e., a dedicated parser for SOAP payloads).

Once a SOAP request is received by the ISAPI module of an ATL Server application, the request handler is filtered by the ISAPI DLL out of the request URL. Then, this is mapped to an internal class (the class implemented using the request_handler attribute) and the generic HandleRequest method is invoked for that class.

The soap_handler attribute generates code that makes the class inherit from the CSoapHandler class. CSoapHandler s implementation for HandleRequest will identify the SOAP method that was invoked (based on the SOAPAction header of the HTTP request) and then launch the SOAP payload parser.

The parser is based on SAX, which is an event-driven parser (and is a part of MSXML). Whenever a parsing event occurs, event handlers contained in the parser class (in this case, CSoapHandler ) are invoked. The most important handlers in parsing an XML payload are as follows :

• HRESULT __stdcall startElement(...) : This is called when a new XML element (tag) is encountered .

• HRESULT __stdcall endElement(...) : This is called whenever an XML element (tag) is closed.

• HRESULT __stdcall characters (...) : This is called when the text content of a tag is encountered by the parser.

Here s the high-level structure of a standard SOAP payload:

 ->SOAP Envelope:    ->SOAP Body      ->Method to be invoked  ->Parameters 

CSoapHandler behaves as a state machine, moving from the state where it expects the Envelope to the state where it expects the Body and so on. It takes care of identifying and validating the Envelope and Body sections of the request. Then once it moves into the Body of the request, it calls the following virtual function of the CSoapHandler :

 virtual HRESULT DispatchSoapCall(   ) 

DispatchSoapCall takes care of identifying the method that the request should be mapped to. In parsing/rendering the parameters, the pair of functions AtlGetSAXValue and AtlGenXMLValue are used for retrieving from and rendering to the actual values to XML, respectively. Keeping this model in mind, we can now move forward and look at hooking into the processing.

As we mentioned earlier, the HandleRequest function is the entry point for the SOAP request processing. In the next section we show how you can use this function for processing SOAP requests arriving via a different (non-HTTP) transport protocol.

Later in the chapter, we show you how to use the virtual DispatchSoapCall to hook into the parsing and handle more flexible payloads (such as those that pass XML nodes as method parameters). Finally, you ll analyze the details of the serialization mechanism and examine one possible solution for marshaling custom data types.