Writing Web Services Using ATL Server

team lib

A Web application is designed to talk to users, typically by sending HTML back to a browser in response to a user request. A Web service , on the other hand, is designed to talk to programs rather than clients . In other words, Web services provide a way for a Web server to expose methods that can be called by client code. This means that, unlike Web applications, Web services dont use SRF files because they dont need to merge dynamic content with static HTML and text.

You can implement Web services in two ways:

  • Using ASP.NET with .NET programming languages such as Visual C# and Visual Basic .NET, and

  • Using C++ and the ATL Server library

Both of these approaches create Web services that have the same functionality, but its often possible to get much greater efficiency from C++ code.

ATL Server Web Service Architecture

This section is going to look at how Web services are implemented in ATL Server, and then go on to show a sample application.

SOAP and Web Services

Youll hear a lot about SOAP (Simple Object Access Protocol) when people talk about Web services. This section provides an introduction for readers who might not be familiar with the technology.

Web services need to be accessible to as many different types of clients as possible, such as Visual Basic applications, Java applets, or even Unix shell scripts. Existing distributed application technologieswhich include DCOM, CORBA, and Java RMIwill connect clients to servers, but they all suffer from drawbacks:

  • Some are platform or vendor specific. Think of Microsofts DCOM, which is pretty much limited to the Windows world.

  • Some are language-specific, such as Javas Remote Method Invocation.

  • Many are hard to program, requiring considerable investment on the part of the programmer. For example, getting to grips with the details of DCOM and CORBA is not for the faint-hearted!

  • Many are hard to administer and debug. DCOM, for example, uses a proprietary binary protocol, and it can be hard to figure out whats happening when something goes wrong.

  • Some, such as DCOM, dont work very well over the Internet, where firewalls tend to get in the way of binary communication through particular ports.

SOAP provides a solution to many of these problems. A client using SOAP can invoke a method on a remote host by encoding the details of the method call as a packet of XML , and sending it over HTTP .

Using HTTP as the protocol has several advantages: it is widely supported, it works well with firewalls, and it makes it easy to host client code on Web pages. Using XML also has advantagesin particular, it is simple to produce and consume XML from almost any language. Using SOAP, it is possible to interact with an ATL Server Web service from a Visual Basic application, a Java applet, or a mainframe application. There is now a SOAP standard from the World Wide Web Consortium (W3C), and SOAP toolkits are available for many languages, including Java, C, and Visual Basic 6.

Using SOAP does have some disadvantages. The main one has to do with the a lack of efficiency: encoding details of a method call in XML might result in several hundred characters being generated, which then have to be sent to the Web service. However, it has been pointed out that for many applications simplicity is preferable to efficiency, and its always possible to use a more efficient binary protocol, such as DCOM, should the need arise.

The security of XML data has also been perceived to be a problem, but it is quite possible to create secure SOAP communication. One way to approach the problem is to apply security at the HTTP levelusing Secure Sockets Layer (SSL), for instance. The problem here is that SOAP is designed so that it can work over different protocols: although most SOAP uses HTTP, theres nothing to stop developers from implementing SOAP-based applications that use other transport mechanisms to shift the XML payload.

You can now secure SOAP communication using two technologies that have been standardized by the W3C: XML Signatures and XML Encryption. Using these, the recipient of a SOAP packet can authenticate the sender and know that the packet hasnt been read or tampered with en route.

The SOAP encoding and decoding is generally invisible to the programmer: it is done as part of the marshaling process that always occurs when data is sent (or method calls are made) across process or machine boundaries. When you are using a Web service from a client such as Visual Basic .NET application, you see nothing of the SOAP communication.

How does a client find out what services Web servers expose? WSDL (Web Services Description Language) is an XML format that is used to describe the services offered by a server. A client can request WSDL from a server, and the XML returned will identify the services provided by the server and the set of operations that each service supports. For each operation, the WSDL file describes the format of the request that the client must send for each operation.

WSDL is not designed to be used by humans , but it enables tools such as Visual Studio .NET to construct proxy classes that will talk to Web services on behalf of a client. You will see how to do this in the example later in the chapter.

Implementing Web Services

Now lets look at how Web services can be implemented using ATL Server.

The first step is to create a custom COM interface that defines the methods that the Web service class wants to make available to clients. Heres an example:

 [uuid("5DA24F49-9FF5-44B3-A638-C0B3EDBB28D2"),object] __interfaceIMyService { [id(1)]HRESULTSquare([in]shortnVal, [out,retval]long*pResult); }; 

Remember that the __interface keyword is a Microsoft extension used to define interfaces, and that the object attribute marks this as being a COM interface. The Web service will expose one method, Square , which takes a short as an input parameter, and returns a long .


service methods are defined using a COM interface because COM interface definitions contain all the marshaling details that are necessary to construct the SOAP marshaling code.

The Web service itself is a class that implements the interface. Theres nothing special about the implementation, but there are a number of attributes added to the class and its methods that identify it as a Web service. The first attribute to be added is the request_handler attribute, which labels that class as being an ATL Server class that can handle external requests .

The soap_handler attribute is applied to a class to add the methods necessary for handling SOAP requests, and to expose information about the service via WSDL. The attribute takes a number of parameters, all of which are optional. They are listed in Table 7-14.

Table 7-14: Parameters Used with the soap_handler Attribute




Specifies the name of the Web service. If it is omitted, "Service" is appended to the name of the class, and this is used as the Web service name.


Specifies an XML namespace to which the service class belongs. If it is omitted, the name of the class is used.


Specifies the protocol used to access this Web service. The only supported value is "soap" , which is assumed if the parameter is omitted.


Specifies the style of the Web service. The only supported values are "document" and "rpc" . If omitted, "rpc" is assumed.


Specifies whether WSDL message parts are encoded or define a concrete schema. If the "document" style is used, this parameter must have the value "literal"; if the "rpc" style is used, this parameter must have the value "encoded" .

The style parameter of the soap_handler attribute determines the type of operation: The document style means that the request and response messages contain XML documents. For example, an operation could be sent an Order XML document, and return an Invoice document; you will typically use XML processing APIs to parse the data sent in document requests. The rpc style means that the request message contains details of a method and its parameters, and the response method contains results or error notifications.


Note that WSDL is generated on request by a compiler-generated handler, which creates an instance of the handler class to obtain information about SOAP methods and SOAP headers. For this reason, do not assume that the handler class will be instantiated only to handle SOAP requests, and do not perform any lengthy or resource- consuming operations in the constructor.

The soap_method attribute is applied to methods within the handler class that are to be exposed to clients. This attribute injects code for parsing SOAP requests. When a SOAP request calls this method, the injected code will do the following:

  • Unpack the parameters from the XML request.

  • Convert any parameters to appropriate C++ types.

  • Call the method.

  • Pack the return types into an XML response.

  • Return the response packet to the client.

The attribute adds information about the decorated method to the WSDL generated for the Web service.

The soap_method attribute can take an optional parameter that specifies the name by which the method will be known to clients; if it is omitted, the method name will be used. You can use the name parameter to hide C++ naming conventions from clients, as shown in the following code:

 [soap_method("MyMethod")] HRESULTXyzMethod1() { ... } 

Example: Creating a Web Service

This section will demonstrate how to create a Web service using ATL Server.

Open the Visual Studio .NET New Project dialog box, and select the ATL Server Web Service project from the Visual C++ Projects folder, giving it a suitable location and name, as shown in Figure 7-6.

click to expand
Figure 7-6: Creating an ATL Server Web Service project

ATL Server Web Service applications support many of the same options as ATL Web applications, but if you look at the Application Options page, youll see that stencil support is grayed out when you elect to create a Web service. Once again, you also have the possibility of merging the ISAPI and ATL Server DLLs into one, if you so choose.

The default code produced to implement the service defines a single test HelloWorld method, just like the Web application. When you examine the code, though, youll find that its implemented very differently.

 //Interfacedefiningthemethodsexposedtoclients [uuid("5DA24F49-9FF5-44B3-A638-C0B3EDBB28D2"),object] __interfaceIMyService { [id(1)]HRESULTHelloWorld([in]BSTRbstrInput, [out,retval]BSTR*bstrOutput); }; //Webserviceclass [request_handler(name="Default",sdl="GenAtlWebSrvWSDL"), soap_handler(name="AtlWebSrvService", namespace="urn:AtlWebSrvService", protocol="soap") ] classCAtlWebSrvService: publicIAtlWebSrvService { public: [soap_method] HRESULTHelloWorld(/*[in]*/BSTRbstrInput, /*[out,retval]*/BSTR*bstrOutput) { CComBSTRbstrOut(L"Hello "); bstrOut+=bstrInput; bstrOut+=L"!"; *bstrOutput=bstrOut.Detach(); returnS_OK; } }; 

The method is defined in the IMyService interface, and implemented in the CAtlWebSrvService class. The class uses the soap_handler attribute to provide a name , namespace , and protocol for the Web service.

To add new SOAP methods to the class, you need to manually edit the code because there is currently no wizard support for modifying Web service classes.

team lib

COM Programming with Microsoft .NET
COM Programming with Microsoft .NET
ISBN: 0735618755
EAN: 2147483647
Year: 2006
Pages: 140

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net