Consuming Web Services

.NET Web Services is a form of distributed computing that enables your application to use the logic of a remote component over the Internet using standard protocols. Web Services is one of the most exciting aspects of using the Compact Framework on a mobile device such as Pocket PC, because it enables you to create rich applications that can access Web Service data from one or many sources without being tethered to a desktop.

For example, consider a Pocket PC device that has a GPS unit attached to it over the serial port (you may someday even be able to use a Pocket PC Phone Edition device to request your current position based on the nearest cellular tower). You could hypothetically use a Web Service to request a map of you current surroundings based on the longitude and latitude that the GPS provides. You could then access another Web Service to get a list of the ATMs or restaurants in your local area. By using Web Services, your applications can focus on tying remote data together into a useful program, rather than concentrate on how to get the data to your device, or replicate functionality that has already been developed elsewhere.

The .NET Compact Framework supports the following functionality regarding Web Services on a Pocket PC device:

• All Web Services must be based on the HTTP protocol. Other protocols, such as SMTP, are not supported.

• Data is transmitted using the Simple Object Access Protocol (SOAP) XML format.

• The Compact Framework supports consuming Web Services by client applications only, and does not natively support hosting them. If you need to support hosting a Web Service using the Compact Framework, you can manually build an HTTP listener (using the TcpListener class) and manually handle incoming SOAP requests.

TIP:

A great Web site for finding Web Services that are publicly available on the Internet is www.xmethods.com. There you can find Web Services for everything from currency conversion to stock quotes.

In the next section, you will learn what is involved on the client side to consume a Web Service on the Pocket PC.

The Microsoft TerraServer Web Service

The Microsoft TerraServer, located at http://terraserver.microsoft.com, is a massive database (about 3.3 terabytes) of both satellite images and topographic maps for much of the United States. By using TerraServer's search engine, you can zoom in on aerial images for almost any street in the U.S., as well as obtain data about surrounding landmarks. TerraServer fortunately also provides a Web Service that you can use to perform queries and get maps from the database (which is rather nice, as it would be rather difficult to store all 3.3 terabytes on a Pocket PC).

In this section, we will use the TerraServer Web Services (also called TerraService) as an example of how you can use and consume .NET Web Services on a Pocket PC device using the .NET Compact Framework. More information about the Web Service API that TerraServer provides is available at http://terraserver.homeadvisor.msn.com/webservices.aspx.

The first thing you need to do to consume a Web Service is create a new project. To do this, select the Smart Device Application project type under the Visual C# Project tree. For this example, let's call the new project TerraServiceTest.

After the project has been created, you need to add a new reference for the Web Service you are planning to use in your class. All you need to do is right-click on References in the Solution Explorer and select Add Web Reference (see Figure 12.1).

Figure 12.1. Adding a Web reference

The Add Web Reference dialog box will appear (see Figure 12.2). In it, you specify the URL for the WSDL or ASMX file that describes the Web Service. The TerraServer Web Service description is located at http://terraserver.homeadvisor.msn.com/TerraService.asmx.

Figure 12.2. Entering the URL for the Web Service

After you have entered the URL, click the Add Reference button. This will cause Visual Studio to generate a proxy class that will be used by your project to access the Web Service. Once this has completed, you will notice that the reference to the Web Service is now in your project (see Figure 12.3).

Figure 12.3. The Web reference is added to the project.

Now, all you need to do to use the TerraServer Web Service is add the namespace to your current project as follows:

 using TerraServiceTest.com.msn.homeadvisor.terraserver; 

That's it! Your C# program can now use the APIs and structures that are part of the Web Service just as if the component were on the device.

Let's take a look at some sample code that uses TerraService to download a "tile" of satellite image data for the Redmond, Washington, area:

 using System; using System.Data; using System.IO; using TerraServiceTest.com.msn.homeadvisor.terraserver; namespace TerraServiceTest {    /// <summary>Summary description for Class1. </summary>    class Class1 {       /// <summary> The main entry point for the       /// application. </summary>       static void Main(string[] args) {          // Create a new TerraService object          TerraService ts = new TerraService();          // Build a place to request tile information on          Place pl = new Place();          pl.City = "Redmond";          pl.State = "WA";          pl.Country = "USA";          PlaceFacts pf = ts.GetPlaceFacts(pl);          // Get the bounding box for the area          AreaBoundingBox abb = ts.GetAreaFromPt(pf.Center,             Theme.Photo, Scale.Scale16m, 640, 480);          // Grab the center tile          Byte[] imageBytes = ts.GetTile(abb.Center.             TileMeta.Id);          // Create a new file and dump the buffer to it          FileStream outputFileStream = new FileStream             ("\\map.jpg", FileMode.CreateNew);          BinaryWriter outputBinaryWriter = new BinaryWriter             (outputFileStream);          // Write          outputBinaryWriter.Write(imageBytes, 0, imageBytes.             Length);          // Clean up          outputBinaryWriter.Close();          outputFileStream.Close();       }    } } 

After the class has completed, you can view the downloaded map by launching Pocket Internet Explorer (see Figure 12.4).

Figure 12.4. Satellite map of the Redmond, WA, area downloaded via TerraServer