Soap Envelope in Xcode

ommunicating with the outside world is one of the ways to make your iPhone applications interesting and useful. This is especially true today where they are so many web services that provide so much useful functionality. However, consuming web services in iPhone is not for the faint-of-heart. Unlike other development tools (such as Microsoft Visual Studio), Xcode does not have built-in tools that make consuming web services easy. Everything must be done by hand and you need to know how to form the relevant XML messages to send to the web services and then parse the returning XML result.

This article will give you a good understanding of how to communicate with XML web services from within your iPhone application, and the examples will provide a solid foundation for consuming other web services in your own projects.

Consuming Web Services

Figure 1. IPToCountry Web Service: This web service exposes two web methods.

Before beginning an Xcode project to consume a web service, examining a real web service to see the different ways you can consume is worthwhile. My favorite example is to use an ASMX XML web service created using .NET. For discussion purposes, here's a look at a web service called IPToCountry, which lets you supply an IP address and returns the country to which the IP address belongs.

The IPToCountry web service is located at http://www.ecubicle.net/iptocountry.asmx. If you use Safari to load this URL, you'll see that it exposes two web methods as shown in Figure 1.

As an example, the FindCountryAsXML returns the result (the country) as an XML string. Clicking the FindCountryAsXML link reveals the page shown in Figure 2.

Figure 2. FindCountryAsXml Service: Testing the web service through a browser interface shows the XML packets exchanged between the client and the server.

The important parts are the sections following the Test section of the page. They detail the various ways in which you can consume the web service. In the .NET world, accessing the web service is a pretty straightforward affair—Visual Studio provides a built-in tool that automatically creates a web proxy service object for the web service when you download the WSDL document. For iPhone development, you need to get your hands dirty, so it's far more important to understand the underlying mechanics of consuming web services.

Using SOAP 1.1

One way to consume this web service is to use SOAP (Simple Object Access Protocol). When using SOAP, you use the HTTP POST method to send a request to the web service, as shown in the following example:

POST /iptocountry.asmx HTTP/1.1
Host: www.ecubicle.net
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://www.ecubicle.net/webservices/FindCountryAsXml"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <FindCountryAsXml xmlns="http://www.ecubicle.net/webservices/">
      <V4IPAddress>string</V4IPAddress>

    </FindCountryAsXml>
  </soap:Body>
</soap:Envelope>

The parts of the code in bold are the placeholders where you need to substitute the actual values. A couple of important things to note from the above:

• The URL for the web service is http://www.ecubicle.net/iptocountry.asmx.


• The URL for the SOAPAction attribute is http://www.ecubicle.net/webservices/FindCountryAsXml.



• The Content-Type for the request is text/xml; charset=utf-8.


• The HTTP method is POST.


• The SOAP request is shown below:
  
  

  <?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  
    <soap:Body>
      <FindCountryAsXml xmlns="http://www.ecubicle.net/webservices/">
        <V4IPAddress>string</V4IPAddress>
      </FindCountryAsXml>
    </soap:Body>
  
  </soap:Envelope>
  




• The Content-Length of the SOAP request is the total number of characters in the complete SOAP request.

The web service will return a response formatted as follows:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <FindCountryAsXmlResponse 
      xmlns="http://www.ecubicle.net/webservices/">
      <FindCountryAsXmlResult>xml result</FindCountryAsXmlResult>
    </FindCountryAsXmlResponse>

  </soap:Body>
</soap:Envelope>

For a real request, the result (the country) will be enclosed within the block of XML code (the bold placeholder in the preceding example). You would need to extract it from the XML result.