Observing the User Experience: A Practitioners Guide to User Research

Key Classes in Web Service Requests

In this section we briefly discuss some of the classes and methods that are core to an ATL Server Web service request. We begin with the classes and methods that are important on the client, and then we look at the classes and methods that are important on the server.

Key Web Service Client Classes

The following classes play key roles in your ATL Server Web service client:

• C ProjectName ServiceT : This class is the sproxy-generated class that handles all the client-side communication for you in a Web service application. It includes atlsoap.h in order to provide its functionality. All the functionality discussed here refers to atlsoap.h or this class. This class uses the Microsoft XML Parser (MSXML) Simple API for XML (SAX) parser to parse XML packets (which means that COM is required and must be initialized in your client).

• CSoapRootHandler (atlsoap.h): You ll notice that C ProjectName ServiceT derives from CSoapRootHandler . This class is used on both the server and the client in ATL Server Web services. This class handles most of the work in a SOAP request. It does the parsing and marshaling for a request. It understands how to call any remote functions and what parameters need to be provided.

  Note	Marshaling is the process through which types get converted. In the incoming request case, this is XML types being converted into real C++ types, and in the outgoing response case, this is C++ types being converted into XML.

• InitializeSOAP (atlsoap.h): This function initializes the per-request heap and queries for the ISAXXMLReader interface.

• GenerateResponse (atlsoap.h): As its name implies, this function is responsible for generating the SOAP response for the client.

• SendRequest (atlsoap.h): Depending on which client you instantiate C ProjectName ServiceT on ( CSoapSocketClientT by default) will decide which version of SendRequest gets called from the sproxy-generated file. This method is responsible for sending the request to the Web service and receiving the response. It s often useful to override SendRequest to provide custom functionality.

Key Web Service Server Classes

These classes play key roles in your ATL Server Web service:

• CSoapRootHandler (atlsoap.h): In case you missed it, this class is the work-horse in atlsoap.h. It s responsible for the majority of the SOAP work and is used in both the Web service client and server (see the CSoapRootHandler entry in the preceding section for more information).

• CSoapHandler (atlsoap.h): This class replaces the CRequestHandlerT class used in a normal ATL Server Web application request. This is done when you use the soap_handler attribute on your class. CSoapHandler derives from CSoapRootHandler and relies on this class to provide much of the SOAP- related functionality (parsing, marshaling, and so on). This class handles other functionality, such as initializing SOAP (SAX reader, per-request heap, and so on), initializing and setting SOAP headers correctly, receiving requests, and generating responses. It provides the required application logic around CSoapRootHandler .

These classes form the basis of an ATL Server Web service application (client or server). Figure 5-4 illustrates the Web service class flow.

Figure 5-4. Web service class flow

The Web service framework relies heavily on the existing ATL Server infrastructure for many services, including the ISAPI extension DLL, thread pool, session state, caching, and so on. Other functions make up the ATL Server Web service framework, particularly in relation to customizing Web service behavior. The classes mentioned in this section, however, define the core functionality required to send and receive Web service requests.