Using the Mozilla SOAP API
Pages: 1, 2, 3, 4, 5

Constructing the SOAP Message

You create a SOAP message just as you would an array or image object with scripting. A number of SOAP-related objects are available, but for now you'll only need to worry about these four:

• SOAPCall: the heart of the SOAP operation, providing the means to encode and send your message.
• SOAPParameter: a single parameter to be passed as an argument to the service method. Multiple parameters are stored in an array to be given to the SOAPCall object.
• SOAPResponse: the response from the service. It contains the results of the method invoked by the SOAPCall.
• SOAPFault: an object that represents an error or warning from the service.

The SOAPCall and SOAPParameter objects are the only ones you'll need to create with JavaScript. SOAPResponse and SOAPFault are automatically generated when the service sends back a response.

Identifying Service Methods

So what methods can you call on a given Web service? Usually a service will provide a WSDL (Web Service Description Language, yet another XML schema) file describing the available methods and the parameters required for calling them. A smart SOAP client will be able to parse this file and automatically generate the interfaces it needs to communicate with the service.

Mozilla is smart, but not quite that smart - its WSDL interface is still being developed. So for now we're stuck reading the WSDL file ourselves to learn what a service has to offer. A tutorial on WSDL could easily fill another article, so I'm going to skip the gory details and only point to the relevant parts as needed throughout this article.

The WSDL file for the Google Web API identifies three methods: doGoogleSearch, doGetCachedPage, and doSpellingSuggestion. Of these three, I'm going to focus on doGoogleSearch for the sample code, but I'll leave some room for the other two methods as well. I'll begin by defining a function to create and send a SOAP message specifically tailored for Google:

function callGoogle(method,params,callback){

}

The callGoogle function requires three arguments:

• method: a string indicating the service method you want to call.
• params: an array containing SOAPParameter objects.
• callback: a pointer to the JavaScript function that will handle the SOAP response from the service.

callGoogle will use the values of these three arguments to create a SOAPCall object representing the message I want to send.

Enabling Security Privileges

Before you create a SOAP message, you need to allow the user to grant "UniversalBrowserRead" permissions to the script so it can make the call to the remote service. To do this, you'll need to use the Privilege Manager, part of the original Netscape product and the Mozilla code base.

function callGoogle(method,params,callback){
  try {
    netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");
  } catch (e) {
    alert(e);
    return false;
  }
}

The above code must go inside the JavaScript function or code block responsible for initiating the SOAP call, and must come before the call itself. When this code executes, users are presented with a prompt that asks them to grant or deny the privilege:

This should happen every time the callGoogle function is invoked.

Remember that this privilege can only be granted to a signed script or one running from the local machine. Otherwise, the code will produce an "enablePrivilege not granted" error and the SOAP call will not be made.