Uncovering the ATL Web Service Implementation

---

At this point in the project, the wizard has generated a functional ATL Web Service. The Web Service is similar to the one created in the last hour's lesson in that it simply exposes a HelloWorld() interface. However, the implementation is totally different from the Web Service created with the .NET Framework.

As with the .NET implementation, the result from building the project is a DLL file and a discovery file (.disco). The project also places a basic HTML file on the Web server for testing the Web Service.

Defining an ATL Web Service Interface

Instead of being class based, where all you have to do is mark a method as a Webmethod, the ATL implementation of a Web Service works by declaring interfaces for which you then create a class that implements them. These interfaces are the exposed Web Service interfaces a user of the Web Service is able to work with. For example, look at the default project file, ATLWebService.h, the wizard built and you will see an interface, as shown in Listing 12.1, for HelloWorld.

Listing 12.1 ATLWebService.h Interface Declaration in ATL Web Service

 1: namespace ATLWebServiceService  2: {  3: // all struct, enum, and typedefs for your webservice should  4: //  go inside the namespace  5: // IATLWebServiceService - web service interface declaration  6: //  7: [  8:    uuid("B81B30EC-7C78-48A2-856E-7C4A756611CE"),  9:    object 10: ] 11: __interface IATLWebServiceService 12: { 13:    // HelloWorld is a sample ATL Server web service method. 14:       // It shows how to declare a web service method and its 15:       // in-parameters and out-parameters 16:    [id(1)] HRESULT HelloWorld([in] BSTR bstrInput, [out, retval] BSTR *bstrOutput); 17:    // TODO: Add additional web service methods here 18: }; 

Looking at the HelloWorld interface declaration, you can see the parameters for the interface. The first parameter is for input and is marked [in] to designate it as input only. The second parameter is actually not a parameter that you need to pass to the interface; it is the return value. Because all interfaces return an HRESULT, the return value for the interface is declared as a parameter with [out, retval]. An interface declaration can only have one parameter declared this way, and it is the last parameter defined.

Declaring new interfaces is done by simply adding additional statements to the __interface section. For example, to add the two interfaces that were implemented in the last hour's lesson, you would add the following statements after the HelloWorld interface declaration:

 [id(2)] HRESULT CurrentDateTime([out, retval] BSTR* bstrOutput); [id(3)] HRESULT RectangleArea([in] double dWidth,                               [in] double dHeight,                               [out, retval] double* dResult); 

As you declare more interfaces to the Web Service, you simply give them new IDs and declare them using the same type of syntax. One issue you should be aware of when declaring your interfaces is this: All return value parameters must be declared as pointers.

Implementing the Interfaces

You implement the interfaces with the CATLWebServiceService class the wizard generated for you when it created the project. The implementation of the HelloWorld interface is shown in Listing 12.2.

Listing 12.2 ATLWebService.h A CATLWebServiceService Class Declaration That Implements the IATLWebServiceService Interface

 1: class CATLWebServiceService :    public IATLWebServiceService  2: {  3: public:  4:    // This is a sample web service method that shows how to use the  5:    // soap_method attribute to expose a method as a web method  6:    [ soap_method ]  7:    HRESULT HelloWorld(/*[in]*/ BSTR bstrInput,  8:                       /*[out, retval]*/ BSTR *bstrOutput)  9:    { 10:       CComBSTR bstrOut(L"Hello "); 11:       bstrOut += bstrInput; 12:       bstrOut += L"!"; 13:       *bstrOutput = bstrOut.Detach(); 14: 15:       return S_OK; 16:    } 17: }; // class CATLWebServiceService 

As you can see, the implementation is somewhat more complex than the implementation in the .NET example. However, this HelloWorld implementation actually builds a message based on a value passed as a parameter. If the implementation is successful, the method should return S_OK; otherwise, an error should be returned.

Another aspect of the implementation to notice is the [soap_method] attribute. This indicates that the method is called using the Simple Object Access Protocol (SOAP), which is required for a Web Service.

Implementing the other two interfaces, CurrentDateTime and RectangleArea, is done in a similar manner as the HelloWorld implementation, as shown in Listing 12.3.

Listing 12.3 ATLWebService.h The CurrentDateTime and RectangleArea Implementations

 1: class CATLWebServiceService :    public IATLWebServiceService  2: {  3: public:  4:    ...  5:    [ soap_method ]  6:    HRESULT CurrentDateTime(/*[out, retval]*/ BSTR *bstrOutput)  7:    {  8:       CComBSTR bstrOut( L"Today");  9: 10:       CTime time = CTime::GetCurrentTime(); 11: 12:       bstrOut = time.Format("%A %B %d, %Y  %I:%M:%S %p" ); 13: 14:       *bstrOutput = bstrOut.Detach(); 15:       return S_OK; 16:    } 17: 18:    [ soap_method ] 19:    HRESULT RectangleArea(/*[in]*/ double dWidth, 20:                          /*[in]*/ double dHeight, 21:                          /*[out, retval]*/ double* dResult) 22:    { 23:       *dResult = dWidth*dHeight; 24: 25:       return S_OK; 26:    } 27: }; // class CATLWebServiceService 

This is the final step necessary before the ATL Web Service can be compiled, which will deploy the Web Service to your local Web Service. When it is deployed, the DLL, the discovery file (.disco), and an HTML file that serves as the description of the Web Service are copied to your Web server.

Unlike the .NET Web Service, which has an ASP.NET test wrapper generated to test the Web Service, the ATL Web Service doesn't have a built-in way to test itself. Therefore, you have to build a test application that uses the Web Service.

---

Top