Developing a simple SOAP client

June 17, 2001

Delphi 6 Enterprise

If you've been following the latest news, you've probably heard of SOAP, Simple Object Access Protocol. This protocol allows you to call a remote method using HTTP and other similar well-known protocols. If you are using Delphi 6 Enterprise, you have a build in support for SOAP.

To develop a SOAP client application using Delphi, you first need to know which SOAP service you want to call. One good starting point is the XMethods.org web site. It lists many interesting SOAP services, some of which are developed using Delphi.

For example, one of the services is the Numbers to Words service by Tom Chamberlain. This service is implemented using Delphi, and it takes a floating-point number (dollar value) and converts it to a string presenting the number in words as in checks. For example, 123 would be "one hundred twenty three dollars and 00 cents".

To call this service from your Delphi client, you first need to know the address of its WSDL file (Web Services Description Language), which happens to be the following:

http://powerofzen.com/cgi-bin/wordsforchecks.exe/wsdl/IWordsForCheck

With this information, start a new Delphi application and the open the New Items dialog box using the File | New | Other menu command. Click onto the WebServices tab, and you should see three icons. Pick the Web Services Importer icon and click OK.

Now, the Web Services Import dialog box opens.

Paste in the previous URL, and click Generate. Delphi should generate a new unit, which contains an interface definition. Save this file to for example WordsIntf.pas. The file should look like the following:

Unit WordsIntf;

interface

uses Types, XSBuiltIns;
type
  IWordsForCheck = interface(IInvokable)
    ['{E9300524-6C2F-4863-86DA-5A43DF5E5359}']
    function GetWordsForCheck(const Value: Double)
             : WideString;  stdcall;
  end;

implementation

uses InvokeRegistry;

initialization
  InvRegistry.RegisterInterface(TypeInfo(IWordsForCheck),
    'urn:UIWordsForChecks-IWordsForCheck', '');
end.

Using the THTTPRIO component

After having generated the interface for the SOAP service you wish to call, return to the main form of your Delphi application. Drop down a TLabeledEdit component, a button and a THTTPRIO component from the WerServices component palette page. Align the control to you liking. The main form should now look like this:

Click the HTTPRIO1 component and check the Object Inspector. There are three properties you must set. It is easiest to start from the bottom and work upwards. First, set the WSDLLocation property to the URL of the WSDL file. This must be the same URL that you used in the Web Service Import dialog box.

Once the URL is set, set the Service property. Note that clicking the down arrows freezes Delphi for a moment because it is communicating with the SOAP server. After setting this property, do the same for the Port property. The values should now be like this:

object HTTPRIO1: THTTPRIO
  WSDLLocation = 
    'http://powerofzen.com/cgi-bin/wordsforchecks.exe/wsdl/' +    
    'IWordsForCheck'
  Service = 'IWordsForCheckservice'
  Port = 'IWordsForCheckPort'
  HTTPWebNode.Agent = 'Borland SOAP 1.1'
  HTTPWebNode.UseUTF8InHeader = False
  Converter.Options = [soSendMultiRefObj, soTryAllSchema]
  Left = 128
  Top = 8
end

The Object Inspector should reflect the settings, as in the following:

Next, return to the code editor by double-clicking the button on the form. Write the following code:

procedure TSOAPMainForm.GetAsWordsClick(Sender: TObject);
Var I : IWordsForCheck;
begin
  Screen.Cursor := crHourGlass;
  Try
    I := HTTPRIO1 as IWordsForCheck;
    ShowMessage(I.GetWordsForCheck(StrToFloat(Number.Text)));
  Finally
    Screen.Cursor := crDefault;
  End;
end;

Before compiling, make sure the interface unit (WordsIntf.pas) is included in the Uses clause of the main form. In the above code, an instance of the THTTPRIO component is used to get an interface to the SOAP service. With this interface, it is really easy to call the GetWordsForCheck method which is implemented in the remote server.

As you can see, it is really easy to call a SOAP service from Delphi! Naturally, the process is the same for any conforming SOAP service; you just need to replace the WSDL URL!

If you test the application, the results could look like this:

For more details about creating SOAP client applications, please consult Chapter 31 in the Delphi Developer's Guide.

Download the example code

Download developingasimplesoapclient.zip (351 kB) which contains the sample SOAP client application developed in this article. Please note that the sample application will require Delphi 6 Enterprise as well as an internet connection.

Note: since the "Numbers to Words" service is not hosted by WhirlWater, we cannot guarantee its performance or existence after this article has been published.

* * *

Need help developing SOAP applications with Delphi? Contact us!