WinBatch & SOAP

The support behind SOAP is interesting. One of the main reasons is probably its grounding in XML. Another advantage of SOAP is its explicit definition of an HTTP binding, a standard method for HTTP tunneling. HTTP tunneling is the process of hiding another protocol inside HTTP messages in order to pass through a firewall unimpeded. Firewalls will usually allow HTTP traffic through port 80, but will restrict the use of other protocols and ports.

A port is a communication address on a computer that complements the Internet address. Each network application on a computer uses a different port to communicate. By convention, Web servers use port 80 for HTTP requests, but application servers can use any one of thousands of other ports.

The power that comes from XML's extensibility and the convenience of using the firewall-immune HTTP protocol partly explain SOAP's success.

However, there is no SOAP API, instead SOAP assumes that you will use as much existing technology as possible.

SOAP Definition

SOAP is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. SOAP uses XML technologies to define an extensible messaging framework, which provides a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation specific semantics.

SOAP uses two existing and widely deployed protocols: HTTP and XML. HTTP is SOAP's RPC-style transport, and XML is its encoding scheme.

In short:
HTTP + XML = SOAP

SOAP is a call-response mechanism. The client (your application) makes a call to the server (a web server, somewhere on the internet), passing in parameters; and the server provides a response. Both call and response are transported in the form of XML documents. Therefore, to build our own example SOAP system, we need both a client and a server � a caller and a responder.

SOAP messaging framework facilitates exchanging XML messages in heterogeneous environments where interoperability has long been a challenge.

SOAP is just another XML markup language accompanied by rules that dictate its use. SOAP has a clear purpose: exchanging data over networks. Specifically, it concerns itself with encapsulating and encoding XML data and defining the rules for transmitting and receiving that data. In a nutshell, SOAP is a network application protocol.

The most common application of SOAP is as a Remote Procedure Call (RPC) protocol.

Existing technology

Soap is based on existing technology. Here are some of the existing technologies that can be utiltized in SOAP communication: XML, HTTP and WSDL .

XML

XML is an acronym for Extensible Markup Language. An open standard for exchanging structured documents and data over the Internet.

SOAP versioning is based on XML namespaces. SOAP 1.1 is identified by the http://schemas.xmlsoap.org/soap/envelope/ namespace while SOAP 1.2 is identified by the http://www.w3.org/2002/12/soap-envelope namespace. This will change when it becomes a Recommendation.

HTTP

HTTP communicates over TCP/IP. An HTTP client connects to an HTTP server using TCP. After establishing a connection, the client can send an HTTP request message to the server:

		POST /item HTTP/1.1
		Host: 189.123.345.239
		Content-Type: text/plain
		Content-Length: 200

The server then processes the request and sends an HTTP response back to the client. The response contains a status code that indicates the status of the request:

		200 OK
		Content-Type: text/plain
		Content-Length: 200

In the example above, the server returned a status code of 200. This is the standard success code for HTTP.

If the server could not decode the request, it could have returned something like this:

		400 Bad Request
		Content-Length: 0

A SOAP method is an HTTP request/response that complies with the SOAP encoding rules.

		HTTP + XML = SOAP

A SOAP request could be an HTTP POST or an HTTP GET request.

The HTTP POST request specifies at least two HTTP headers: Content-Type and Content-Length.

WSDL

Web Services Description Language (WSDL) is a specification to describe networked XML-based services. It provides a simple way for service providers to describe the basic format of requests to their systems regardless of the underlying protocol.

The WSDL document is like a contract between the client and server. The server agrees to provide certain services only if the client sends a properly formatted SOAP request message.

To illustrate, suppose a WSDL file defines a service called StockQuoteService, which describes operations such as GetLastTradePrice, GetLowestPriceOfTheDay, and GetHighestPriceOfTheDay. This WSDL file is placed somewhere on the server. A client who wishes to send a SOAP request to this service obtains a copy of this WSDL file from the server. The client then uses the information in this file to format a SOAP request message. The client sends this request to the server. The server executes the requested operation and sends the resulting stock price back to the client as a SOAP response message.

Where is the WSDL Standard? The W3C has the WSDL 1.1 specification. It can be found at http://www.w3.org/TR/wsdl.

Writing a SOAP script

First you will need to track down a SOAP Web Service that you would like to query for information. Then you must understand how to format the SOAP Message you want to send to the SOAP Web Service.

SOAP Web Services

XMethods.com Provides an ever-growing list of publicly available SOAP services. In addition to telling you whether the optional SOAP Action parameter is necessary for each service, descriptions of many of them include sample XML requests.

SOAPAgent.com is yet another resource directory dedicated to SOAP and Web Services.

Amazon Search Searches books and other products using Amazon's XML Interface.

SOAP Message

The most difficult part of using SOAP is to create a valid SOAP message. As mentioned previously, you can determine all of the necessary SOAP Message elements by looking at the WSDL file provided by the Web Service.

In order to create a SOAP message, you'll need to collect the following information

The method name.
The namespace URI for the method name.
The parameter names and types.
The value of the SOAPAction header.
The URL where the service is running.

If you know where to locate the WSDL file, you may be able to generate a complete message using Microsoft's 'Web Services Description Language Tool' (Wsdl.exe)

The Web Services Description Language tool generates code for XML Web services and XML Web service clients from WSDL contract files, XSD schemas, and .discomap discovery documents.

Development

With WinBatch you have a few different options when writing code to send a SOAP message. You will have to decide for yourself which option best fits your needs.

WinInet

The WinInet extender can be used to simplify the task of writing HTTP client applications. Following are the steps required to send a generic HTTP request using the WinInet extender:

Create a top level handle for other internet functions using iBegin(). This begins an HTTP session.
Call iHostConnect() define the connection parameters. Pass the server and HTTP port to this method
iHttpInit() initializes a datahandle and sets up - but does not actually perform - an Http request. Pass the rest of the URL (except server name), the HTTP method (GET/POST/...) to this function.
Open an HTTP request using iHttpOpen. Optionally, pass headers as the second parameter to the iHttpOpen() function to supply any request headers. This completes an HTTP request and actually sends it to the server.
Check the return value of iHttpOpen() to find out if the HTTP request succeeded.
On success, use iReadData() or iReadDataBuf() to read the response.
Finally, call iClose() for each connection handle.

Here is a Web service client code that uses the WinInet extender to call Currency Exchange WebService on XMethods.com. This Web service, given two country names returns the exchange rate between any two currencies.

;Currency Exchange WebService
; Exchange rate between any two currencies.
;
; Takes in country1 and country2, and returns the exchange rate between currencies
;(Returns value of 1 unit of country1's currency converted into country2's unit currency).
;
;The following country names are valid:
;afghanistan
;albania
;algeria
;andorra
;andorra
;angola
;argentina
;aruba
;australia
;austria
;bahrain
;bangladesh
;barbados
;belgium
;belize
;bermuda
;bhutan
;bolivian
;botswana
;brazil
;england
;united kingdom
;uk
;great britain
;brunei
;burundi
;cambodia
;canada
;cape verde
;cayman islands
;chile
;china
;colombia
;comoros
;costa rica
;croatia
;cuba
;cyprus
;czech republic
;denmark
;dijibouti
;dominican republic
;netherlands
;east caribbean
;ecuador
;egypt
;el salvador
;estonia
;ethiopia
;euro
;falkland islands
;fiji
;finland
;france
;gambia
;germany
;ghana
;gibraltar
;greece
;guatemala
;guinea
;guyana
;haiti
;honduras
;hong kong
;hungary
;iceland
;india
;indonesia
;iraq
;ireland
;israel
;italy
;jamaica
;japan
;jordan
;kazakhstan
;kenya
;korea
;kuwait
;laos
;latvia
;lebanon
;lesotho
;liberia
;libya
;lithuania
;luxembourg
;macau
;macedonia
;malaga
;malawi kwacha
;malaysia
;maldives
;malta
;mauritania
;mauritius
;mexico
;moldova
;mongolia
;morocco
;mozambique
;myanmar
;namibia
;nepal
;new Zealand
;nicaragua
;nigeria
;north korea
;norway
;oman
;pakistan
;panama
;papua new guinea
;paraguay
;peru
;philippines
;poland
;portugal
;qatar
;romania
;russia
;samoa
;sao tome
;saudi arabia
;seychelles
;sierra leone
;singapore
;slovakia
;slovenia
;solomon islands
;somalia
;south africa
;spain
;sri lanka
;st helena
;sudan
;suriname
;swaziland
;sweden
;switzerland
;syria
;taiwan
;tanzania
;thailand
;tonga
;trinidad
;tunisia
;turkey
;united states
;us
;usa
;uae
;united arib emirates
;uganda
;ukraine
;uzbekistan
;vanuatu
;venezuela
;vietnam
;yemen
;yugoslavua
;zambia
;zimbabwe
;
;--------------------------------------------------------------------------------
;
;Usage Notes
;
;Request Parameter Schema:
;<element name="country1" type="string" />
;<element name="country2" type="string" />
;
;Response Parameter Schema:
;<element name="return" type="float" />
;
;Encoding Style for both request and response:
;http://schemas.xmlsoap.org/soap/encoding
;
;----------------------------------------------------------
;For XMethods Server implementation, use port 9090 instead of port 80.
;----------------------------------------------------------
;
;Sample Request envelope:
;
;<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema">
;<SOAP-ENV:Body>
;<ns1:getRate xmlns:ns1="urn:xmethods-CurrencyExchange" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
;<country1 xsi:type="xsd:string">England</country1>
;<country2 xsi:type="xsd:string">Japan</country2>
;</ns1:getRate>
;</SOAP-ENV:Body>
;</SOAP-ENV:Envelope>
;
;
;-----------------------------------------------------------
;
;Sample Response Envelope:
;
;<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema">
;<SOAP-ENV:Body>
;<ns1:getRateResponse xmlns:ns1="urn:xmethods-CurrencyExchange" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
;<return xsi:type="xsd:float">154.9423</return>
;</ns1:getRateResponse>
;</SOAP-ENV:Body>
;</SOAP-ENV:Envelope>


#DefineFunction iSoapRequest( host, urlpath, soaprequest, soapaction, request )
   ; Place Soap Request in Binary Buffer
   SOAPRequestLen = StrByteCount( SOAPRequest, -1 )
   SOAPRequestBuf = BinaryAlloc( SOAPRequestLen )
   BinaryPokeStr( SOAPRequestBuf, 0, SOAPRequest )
   SOAPRequestBufAddr = IntControl( 42, SOAPRequestBuf, 0, 0, 0 )

   ; Allocate and define a top level handle for other internet functions.
   tophandle=iBegin( 2, "", "" )


   ; Connect to an Internet host
   connecthandle=iHostConnect( tophandle, host, @HTTP, "", "" )

   ; Initializes a datahandle and sets up - but does not actually perform - an Http request
   datahandle=iHttpInit( connecthandle, "POST", urlpath, "", 4 ) ;4 = Keep Alive Connection
   If datahandle==0
      err=iGetLastError()
      Message( "Last Error", err )
      iClose( tophandle )
      Exit
   EndIf

   ; Define SOAP Header
   myheader=StrCat('SOAPAction: "',SOAPAction,'"',@CRLF,'Content-Type: text/xml; charset=UTF-8', @CRLF, 'Content-Length:', SOAPRequestLen )
   ; Completes an HTTP request and actually sends it to the server.
   rslt=iHttpOpen(datahandle, myheader, SOAPRequestBufAddr, BinaryEodGet(SOAPRequestBuf))
   If rslt=="ERROR" || rslt!=200
      If rslt == "ERROR"
         errstr = "WinInet Error"
         rslt = iGetLastError()
      Else
         errstr = "HTTP Error"
      EndIf
      Message("Error!",iHttpHeaders(datahandle))
   EndIf

   If request == 1
      headers = iHttpHeaders(datahandle)
      Result = headers
      Goto CleanUp
   EndIf

   If request == 0
      ; Allocate buffer to hold the entire file
      bufferSize = 65536
      buf = BinaryAlloc( bufferSize )
      ;Get address of buffer
      bufaddr = IntControl ( 42, buf, 0, 0, 0 )
      BinaryEodSet(buf, bufferSize )
      bytesread = iReadDataBuf( datahandle, bufaddr, bufferSize )
      ;Message( 'bytes read', bytesread )
      SOAPResponse = BinaryPeekStr( buf, 0, bytesread )
      BinaryFree(buf)
      Result = SOAPResponse
      Goto CleanUp
  EndIf

   :CleanUp

   iClose(datahandle)
   iClose(connecthandle)
   iClose(tophandle)
   Return Result
#EndFunction


AddExtender( 'C:\Program Files\Microsoft Visual Studio\MyProjects\WinInet\Debug\wwint44i.dll' )

host = 'services.xmethods.net:9090'
urlpath =  '/soap'
country1 = 'USA'
country2 = 'Canada'

; Define SOAP Message
SOAPRequest = '<soap:Envelope xmlns:mrns0="urn:xmethods-CurrencyExchange" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><mrns0:getRate><country1 xsi:type="xs:string">':country1:'</country1><country2 xsi:type="xs:string">':country2:'</country2></mrns0:getRate></soap:Body></soap:Envelope>'
SOAPAction = ''
request = 0

SOAPResponse = iSoapRequest( host, urlpath, SOAPRequest, SOAPAction, request )
Message( "SOAPResponse", SOAPResponse )
Exit

SOAP and Wininet LIMITATIONS

If you plan to use WinInet in a production environment to implement SOAP, it is important to be aware of some of its limitations.

WinInet provides a large amount of functionality, but is not at all suited for use by a service or in some general client situations. Microsoft has even suggested not to use it for a server or service. WinInet has SSL support for secure http (HTTPS) communications, but this will not work properly running as a service, with IE 4.0 or later installed. The problem is that the registry keys describing the root Certificate Authorities are stored under the different 'user' keys, which are unaccessible to a service, which looks under the 'Services' key. So you will get an 'invalid CA' error.

Secondly, WinInet will usually enforce a 2 connection limit to the same http server. This is actually reccomended behaviour for http 1.1, but for some clients this would not be suitable when you want to do multiple simultaneous requests.

You also do not have source for the code and there are some bugs, which vary between the differnet versions of Internet Explorer. For example, even the latest version will treat a timeout on a receive that has no content length set the same as if the server had just closed the stream. It considers it an 'end of content' instead of returning a 'timeout' error like it should.

XMLHTTP

Microsoft's suite of XML DOM (Document Object Model) components includes the XMLHTTP object. This object is originally designed to provide client-side access to XML documents on remote servers through the HTTP protocol. It exposes a simple API which allows you to send requests and get the resulting data.

If you have a current version of Internet Explorer then you probably have MSXML installed. If you need to install it, you can install the latest version of MSXML component itself. If you don't have it installed, you will get the error '1727 COM: Invalid Class String' when you execute CreateObject("Microsoft.XMLHTTP").

References

http://www.w3.org/TR/soap/ This page (http://www.w3.org/TR/soap) contains links to the SOAP/1.1 Note and the SOAP Version 1.2 Recommendation documents.

http://www.soapclient.com

Article ID:   W17345

File Created: 2014:05:29:10:13:44

Last Updated: 2014:05:29:10:13:44

Database Search

TechHome