EXECUTIVE SUMMARY
This article covers the basics of using the SOAP Client software included with Microsoft Windows XP Professional to access Web Services using SOAP. It begins with a brief introduction to SOAP and WSDL standards and then discusses how to implement a client that can communicate with a SOAP-enabled Web service.
INTRODUCTION
Microsoft Windows XP Professional includes the client portion of the Microsoft SOAP Toolkit 2.0, making it possible to build SOAP client applications or to distribute them to Windows XP Professional clients without distributing the client portions of the SOAP Toolkit 2.0. This paper covers the basics of using the SOAP client software included with Windows XP to access Web services using SOAP. It begins with a brief introduction to SOAP and Web Services Description Language (WSDL) standards, and then discusses how to implement a client that can communicate with a SOAP-enabled Web service.
What Is SOAP?
SOAP, which stands for Simple Object Access Protocol, is defined by the SOAP standard available at http://www.w3.org/TR/SOAP. The SOAP protocol defines the format of standard XML messages that are used to communicate among systems. Because the message format is standardized and based on the XML standard, SOAP can be used to communicate among multiple computer architectures, languages, and operating systems. SOAP enables a new class of applications called Web services, which expose services in a standard way so that application developers can create new applications by putting together services from many different sources on the Web.
There are four main areas covered by the SOAP specification: a required SOAP Envelope format that defines what the envelope that surrounds the XML content of a SOAP message must look like; an optional set of encoding rules that defines how language types are mapped to XML in a SOAP message (since this is defined in section 5 of the specification, it is referred to as "section 5 encoding"); an optional RPC format that defines how function calls are expressed in SOAP messages; and an HTTP binding that defines how SOAP messages may be exchanged through HTTP. HTTP is the only communications protocol binding defined by the standard; thus almost all SOAP implementations include an HTTP binding. Note that SOAP doesn't impose limitations on what other communications protocols can be used to transport SOAP messages.
Here's a simple SOAP message:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAPSDK1:Add xmlns:SOAPSDK1="http://tempuri.org/message/">
<a>333</a>
<b>888</b>
</SOAPSDK1:Add>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Let's go through this in detail to understand the format of a SOAP message. The first line is the XML declaration that defines the character set used in the SOAP document. The Envelope element is a required element that is always the root of a SOAP message, and is always in the "http://schemas.xmlsoap.org/soap/envelope/" namespace.
The SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" attribute defines the encoding style used in the message. In this case, standard section 5 encoding is used. The Body sub element of the Envelope element contains the SOAP Message. As defined in section 7 of the SOAP specification, the Add element represents a call on an operation named Add. The sub elements of Add are the parameters of the Add method call.
The response to this message would look like this:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAPSDK1:AddResponse xmlns:SOAPSDK1="http://tempuri.org/message/">
<Result>1221</Result>
</SOAPSDK1:AddResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
What Is WSDL?
WSDL stands for Web Service Definition Language. In order to successfully call a Web service you will need to know how to get to the service, what operations the service supports, what parameters the service expects, and what the service returns. WSDL provides all of this information in an XML document that can be read or machine-processed.
To understand the format of a WSDL file, let's examine the following WSDL file:
<?xml version="1.0" encoding="UTF-8" ?>
<definitions name="net.xmethods.services.currencyexchange.CurrencyExchange"
targetNamespace="http://www.themindelectric.com/wsdl/
net.xmethods.services.currencyexchange.CurrencyExchange/"
xmlns:tns="http://www.themindelectric.com/wsdl/
net.xmethods.services.currencyexchange.CurrencyExchange/"
xmlns:electric=http://www.themindelectric.com/
xmlns:soap=http://schemas.xmlsoap.org/wsdl/soap/
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:soapenc=http://schemas.xmlsoap.org/soap/encoding/
xmlns:wsdl=http://schemas.xmlsoap.org/wsdl/
xmlns="http://schemas.xmlsoap.org/wsdl/">
<message name="getRateRequest1">
<part name="country1" type="xsd:string" />
<part name="country2" type="xsd:string" />
</message>
<message name="getRateResponse1">
<part name="Result" type="xsd:float" />
</message>
<portType name="net.xmethods.services.
currencyexchange.CurrencyExchangePortType">
<operation name="getRate" parameterOrder="country1 country2">
<input message="tns:getRateRequest1" />
<output message="tns:getRateResponse1" />
</operation>
</portType>
<binding
name="net.xmethods.services.currencyexchange.CurrencyExchangeBinding"
type="tns:net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="getRate">
<soap:operation soapAction="urn:xmethods-CurrencyExchange#getRate" />
<input>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding>
<service name="net.xmethods.services.currencyexchange.CurrencyExchangeService">
<documentation>
net.xmethods.services.currencyexchange.CurrencyExchange web service
</documentation>
<port name="net.xmethods.services.currencyexchange.CurrencyExchangePort"
binding="tns:net.xmethods.services.currencyexchange.CurrencyExchangeBinding">
<soap:address location="http://206.135.115.109:9090/soap" />
</port>
</service>
</definitions>
This is the WSDL file for an exchange rate service implemented in Glue from The Mind Electric. Therefore, the format is not identical to a Microsoft SOAP Toolkit WSDL file, but it is compatible. The first element of the WSDL file is the definitions element, which is the root element of the file and normally contains several namespace declarations:
<
definitions name="net.xmethods.services.currencyexchange.CurrencyExchange"
targetNamespace="http://www.themindelectric.com/wsdl/
net.xmethods.services.currencyexchange.CurrencyExchange/"
xmlns:tns="http://www.themindelectric.com/wsdl/
net.xmethods.services.currencyexchange.CurrencyExchange/"
xmlns:electric=http://www.themindelectric.com/
xmlns:soap=http://schemas.xmlsoap.org/wsdl/soap/
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:soapenc=http://schemas.xmlsoap.org/soap/encoding/
xmlns:wsdl=http://schemas.xmlsoap.org/wsdl/
xmlns="http://schemas.xmlsoap.org/wsdl/">
</definitions>
Note that the xsd namespace is the 2001 version. The SOAP Toolkit defaults to the 2001 Recommendation version of the XSD Schema namespace but it can understand WSDL files written with older namespace versions.
If the WSDL used any complex types, the XSD Schema definition for these types would be contained in a <types></types> element. Since this WSDL file doesn't use any complex types, that element is missing.
The next section defines the messages used by the service defined in this WSDL:
<message name="getRateRequest1">
<part name="country1" type="xsd:string" />
<part name="country2" type="xsd:string" />
</message>
<message name="getRateResponse1">
<part name="Result" type="xsd:float" />
</message>
The names and datatypes of the method parameters are defined here.
The portType element defines a mapping between the messages defined in the previous section and the operations that use them:
<portType name="net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<operation name="getRate" parameterOrder="country1 country2">
<input message="tns:getRateRequest1" />
<output message="tns:getRateResponse1" />
</operation>
</portType>
The binding element defines a binding between the abstract operations defined in the portType element and how they are implemented in SOAP. This is done is a separate element because WSDL is intended to define other non-SOAP protocols. A few thing to note here: the style="rpc" means that this message uses the rpc rules defined in section 7 of the SOAP standard. If style="document" was specified, the contents of the SOAP message would be an XML document. The transport attribute indicates that the SOAP messages will be sent in SOAP HTTP messages, the soapAction attribute defines the contents of the soapAction header in the HTTP packet, and the use="encoded" attribute indicates that SOAP section 5 encoding is used for parameter values.
<portType name="net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<operation name="getRate" parameterOrder="country1 country2">
<input message="tns:getRateRequest1" />
<output message="tns:getRateResponse1" />
</operation>
</portType>
<binding name="net.xmethods.services.currencyexchange.CurrencyExchangeBinding"
type="tns:net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="getRate">
<soap:operation soapAction="urn:xmethods-CurrencyExchange#getRate" />
<input>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding>
The service element ties a SOAP binding to a physical implementation of the service. This is where the URL of the service is defined. Notice that this service is found at port 9090—SOAP doesn't just work through port 80. (There is also a copy of the service running on port 80 if your firewall requires you to use port 80.)<service name="net.xmethods.services.currencyexchange.CurrencyExchangeService">
<documentation>
net.xmethods.services.currencyexchange.CurrencyExchange web service
</documentation>
<port name="net.xmethods.services.currencyexchange.CurrencyExchangePort"
binding="tns:net.xmethods.services.currencyexchange.CurrencyExchangeBinding">
<soap:address location="http://206.135.115.109:9090/soap" />
</port>
</service>
The SOAP Client Object
This section reviews the object model exposed by the SOAPClient object. Each method and property exposed by the SOAPClient is described.
Mssoapinit Method
The mssoapinit method initializes the SOAPClient object using the Web Services Description Language (WSDL) file as input. All of the operations in the identified service are bound to the SOAPClient object during initialization. Thus, you can call the operations defined in the service using the SOAPClient object.
Method definition
HRESULT mssoapinit(
[
in] BSTR bstrWSDLFile,
[in, optional, defaultvalue("")] BSTR bstrServiceName,
[in, optional, defaultvalue("")] BSTR bstrPort,
[in, optional, defaultvalue("")] BSTR bstrWSMLFile);
Parameters
bstrWSDLFile
bstrWSDLFile is the URL of the WSDL file that describes the services offered by the server.
bstrServiceName
bstrServiceName is the optional service in the WSDL file that contains the operation specified in the Simple Object Access Protocol (SOAP) request. If this parameter is missing, null, or an empty string, the mssoapinit method uses the first service in the specified WSDL file when initializing the SOAPClient object.
bstrPort
bstrPort, also optional, is the name of the port in the WSDL file that contains the operation specified in the SOAP request. If this parameter is missing, null, or an empty string, the mssoapinit method uses the first port in the specified service when initializing the SOAPClient object.
bstrWSMLFile, also optional, is the URL of the Web Services Meta Language (WSML) file. This is a required parameter only when using custom type mappers.
Visual Basic syntax
Sub mssoapinit(bstrWSDLFile As String,_
[bstrServiceName As String],_
[bstrPort As String],_
[bstrWSMLFile As String])
Visual Basic example
set soapclient = CreateObject("MSSOAP.SOAPClient")
call soapclient.mssoapinit("DocSample1.wsdl", "", "", "")
wscript.echo soapclient.AddNumbers(2,3)
wscript.echo soapclient.SubtractNumbers(3,2)
Remarks
The mssoapinit method is part of the high-level API on the client side. To use this method, you must first create a SOAPClient object on the client. Then, call the mssoapinit method using the WSDL file name, service name, and port name as parameters. Now the client can call any operations defined in the WSDL file for the requested service or port.
ClientProperty Property
The ClientProperty property sets and retrieves properties specific to the SOAPClient object.
Method definition
[propget] HRESULT ClientProperty(
[in] BSTR PropertyName,
[out, retval] VARIANT* pPropertyValue);
[propput] HRESULT ClientProperty(
[in] BSTR PropertyName,
[in] VARIANT pPropertyValue);
Parameters
PropertyName PropertyName is the name of the property to set or retrieve. See the following Remarks section for a list of properties. The following properties are supported (the property names are case sensitive):
| Property Name |
Description |
| ServerHTTPRequest |
A True/False value indicating whether to use the "server-safe" XML components to load the Web Services Description Language (WSDL) and Web Services Meta Language (WSML) files. Set to True when an Active Server Pages
(ASP) application or an ISAPI DLL uses the SOAPClient object. When ServerHTTPRequest is set to true, the WinHTTP Proxy
Configuration Utility must be used to configure WinHTTP. This is necessary even if a proxy server is not being used |
| ConnectorProgID |
Specifies the ProgID of a class that implements the ISOAPConnector interface. Will create and use objects of this class when sending requests to the service. When set to an empty string, the default value,
SOAPClient uses
a SOAPConnectorFactory object to create a connector for the transport protocol specified the WSDL. |
pPropertyValue
pPropertyValue is the property's value.
Visual Basic syntax
Property
ClientProperty(ByVal PropertyName As String) As Object
Visual Basic example
Dim Client As New SOAPClient
Client.ClientProperty("ServerHTTPRequest") = True
ConnectorProperty Property
Sets and retrieves properties specific to the transport protocol connector used by a SOAPClient object.
Method definition
[propget] HRESULT ConnectorProperty (
[in] BSTR PropertyName,
[out, retval] VARIANT* pPropertyValue);
[propput] HRESULT ConnectorProperty (
[in] BSTR PropertyName,
[in] VARIANT pPropertyValue);
Parameters
PropertyName
PropertyName is the name of the property to set or retrieve. Which properties are supported depends on the connector being used. The protocol specified by the <soap:binding> transport attribute in the Web Services Description Language (WSDL) file determines the connector to use.
pPropertyValue
pPropertyValue is the value of the property.
Visual Basic syntax
Property ConnectorProperty(ByVal PropertyName As String)
Visual Basic example
Dim Client As New SOAPClient
Client.mssoapinit WSDLFile, Service, Port
Client.ConnectorProperty("ProxyUser") = User
Client.ConnectorProperty("ProxyPassword") = Password
Connector properties
| Property |
Description |
| AuthPassword |
The password used for end point authentication. |
| AuthUser |
The user name used for end point authentication. |
| EndPointURL |
The end point URL. |
| ProxyPassword |
The password used for proxy authentication. |
| ProxyPort |
The port of the proxy server to use. |
| ProxyServer |
The IP address or host name of the proxy server
|
| ProxyUser |
The user name used for proxy authentication. |
| SOAPAction |
The value used in the SOAPAction HTTP header. |
| SSLClientCertificateName |
A string identifying the client certificate to use for the Secure Sockets Layer (SSL) protocol, if any. The syntax is:
[CURRENT_USER | LOCAL_MACHINE\[store-name\]]cert-name
with the defaults being CURRENT_USER\MY (the same store that Microsoft Internet Explorer uses). |
| Timeout |
The timeout for HttpConnector. This timeout is in milliseconds. |
| UseSSL |
A Boolean value (true or false) that specifies the use of SSL. |
Detail Property
The detail property is read-only. It provides the value of the <detail> element of the <Fault> element in the Simple Object Access Protocol (SOAP) message.
Method definition
[propget] HRESULT detail(
[out, retval] BSTR* bstrDetail);
Parameters
bstrDetail
bstrDetail is the detail of the fault.
Visual Basic syntax
Property detail() As String
HeaderHandler (SOAPClient)
Sets the header handler for the next call against this client instance.
Method definition
HRESULT HeaderHandler([in] IDispatch* rhs);
Parameters
rhs
rhs is the reference to the COM class interface that implements the IHeaderHandler.
Visual Basic syntax
Property HeaderHandler() As Object
Visual Basic example
Set sc = WScript.CreateObject("MSSOAP.SOAPClient")
sc.mssoapinit=http://localhost/DocSample7/DocSample7.wsdl
sc.HeaderHandler = WScript.CreateObject("SessionInfoClient.clientHeaderHandler")
Sc.SomeMethod "param1", "param2"
Faultactor Property (SOAPClient)
The faultactor property is read-only, and provides the Universal Resource Identifier (URI) that generated the fault.
Method definition
[propget] HRESULT faultactor(
[out, retval] BSTR* bstrActor);
Parameters
bstrActor
The bstrActor is the URI that generated the fault.
Visual Basic syntax
Property faultactor() As String
Visual Basic example
wscript.echo soapclient.faultactor
Faultcode Property (SOAPClient)
The faultcode property is read-only. It provides the value of the <faultcode> element of the <Fault> element in the Simple Object Access Protocol (SOAP) message.
Method definition
[propget] HRESULT faultcode(
[out, retval] BSTR* bstrFaultcode);
Parameters
bstrFaultcode
bstrFaultcode is the value of the <faultcode> element.
Visual Basic syntax
Property faultcode() As String
Visual Basic example
wscript.echo soapclient.faultcode
Faultstring Property (SOAPClient)
This faultstring property is read-only. It provides the value of the <faultstring> element of the <Fault> element in the Simple Object Access Protocol (SOAP) message.
Method definition
[propget] HRESULT faultstring(
[out, retval] BSTR* bstrFaultstring);
Parameters
bstrFaultstring
bstrFaultstring is the value of the <faultstring> element.
Visual Basic syntax
Property faultstring() As String
Visual Basic example
wscript.echo soapclient.faultstring
For More Information and Referred