XML-RPC and SOAP Programming Guide Contents Introduction to XML-RPC and SOAP Programming Guide 4 Who Should Read This Document 4 Organization of This Document 5 About AppleScript’s Support for XML-RPC and SOAP 6 The XML-RPC and SOAP Protocols 6 AppleScript Support for Remote Procedure Calls 7 Remote Procedure Calls From Scripts 9 Remote Procedure Calls From Applications 13 Making Remote Procedure Calls From Scripts 18 Scripting an XML-RPC Call 18 Scripting a SOAP Request 22 A Simple Translation Script 22 A More Complex Translation Script 24 Making Remote Procedure Calls From Applications 27 Making an XML-RPC Call 27 Setting Up a Project 27 Includes, Constants, and Declarations 28 A Main Function That Makes an XML-RPC Call 29 Displaying XML-RPC Debug Information 32 Making a SOAP Request 35 Setting Up a Project 36 Includes, Constants, and Declarations 36 A Main Function That Makes a SOAP Request 37 Creating Parameter List Records 41 Displaying SOAP Request Debug Information 42 Document Revision History 45 2005-03-03 | Copyright © 2001, 2005 Apple Computer, Inc. All Rights Reserved. 2 Figures and Listings About AppleScript’s Support for XML-RPC and SOAP 6 Figure 1-1 The Apple Event Manager processing a remote procedure call Apple Event. 8 Listing 1-1 Sample list of misspelled words returned by spellCheck remote procedure call. 11 Listing 1-2 Event class and event ID constants for remote procedure call Apple events. 14 Listing 1-3 Address descriptor type for remote procedure call Apple events. 14 Listing 1-4 Constants for specifying a SOAP schema. 15 Listing 1-5 Constants used in constructing an XML-RPC or SOAP request in a remote procedure call Apple event. 15 Listing 1-6 Constants for turning on the Apple Event Manager’s remote procedure call debugging. 16 Listing 1-7 Key constants for remote procedure call debugging attributes. 16 Making Remote Procedure Calls From Scripts 18 Listing 2-1 A script that makes an XML-RPC request to check the spelling of a text phrase. 18 Listing 2-2 A simple script that calls a SOAP translation server. 22 Listing 2-3 A more detailed script that calls a SOAP translation server. 24 Making Remote Procedure Calls From Applications 27 Listing 3-1 Includes, constants, and declarations for making an XML-RPC call. 28 Listing 3-2 main function to send an XML-RPC Apple event. 30 Listing 3-3 A function to display debug information from an XML-RPC reply Apple event. 33 Listing 3-4 Sample header and data from an XML-RPC post and the reply. 34 Listing 3-5 Includes, constants, and declarations for making a SOAP request. 36 Listing 3-6 main function to send a SOAP Apple event. 38 Listing 3-7 A function to create a parameter list record for a SOAP request Apple event. 41 Listing 3-8 Sample header and data from a SOAP post and the reply. 42 2005-03-03 | Copyright © 2001, 2005 Apple Computer, Inc. All Rights Reserved. 3 Introduction to XML-RPC and SOAP Programming Guide Note: This document was previously titled “XML-RPC and SOAP Support.” XML-RPC and SOAP Programming Guide describes how to use Apple Script and the Apple Event Manager in OS X to make remote procedure calls using the XML-RPC and SOAP (Simple Object Access Protocol) protocols. XML-RPC is a protocol for using XML and HTTP to make remote procedure calls over the Internet. SOAP (Simple Object Access Protocol) is a remote procedure call protocol designed for exchanging information in a distributed environment, where a server may consist of a hierarchy of objects. This book describes only how to send XML-RPC and SOAP requests, not how to serve them. Note: Web service protocols such as XML-RPC and SOAP are evolving, as is the support for them in OS X. The scripts and code samples in this document depend on third-party web services that are also subject to change. Though the samples have been tested as published, your experience may vary. The sample code in this book can be adapted for Carbon applications, Cocoa applications, simple tools, or other code. However, there is no specific Cocoa class support provided. Who Should Read This Document To take full advantage of this document, you should be familiar with AppleScript, either through writing AppleScript scripts or creating scriptable applications. You can learn more about these topics in AppleScript Documentation. In particular, see AppleScript Overview and Apple Events Programming Guide. You should also be familiar with the XML-RPC and SOAP protocols. You can find information on these protocols at third-party websites. For example, the XML-RPC specification is currently described at http://www.xmlr- pc.com/spec and the SOAP specification at http://www.w3.org/TR/. 2005-03-03 | Copyright © 2001, 2005 Apple Computer, Inc. All Rights Reserved. 4 Introduction to XML-RPC and SOAP Programming Guide Organization of This Document Organization of This Document This document is organized into the following chapters: ● “About AppleScript’s Support for XML-RPC and SOAP” (page 6) provides a brief introduction to the XML-RPC and SOAP protocols, then describes the scripting support in OS X version 10.1 (and later) for these protocols, including the syntax for script statements and the APIs for making remote procedure calls from applications or other code. ● “Making Remote Procedure Calls From Scripts” (page 18) provides sample scripts and step by step descriptions for making XML-RPC and SOAP requests from scripts. ● “Making Remote Procedure Calls From Applications” (page 27) provides sample code and step by step descriptions for making XML-RPC and SOAP requests from applications and other code. ● “Document Revision History” (page 45) describes the history of this book. 2005-03-03 | Copyright © 2001, 2005 Apple Computer, Inc. All Rights Reserved. 5 About AppleScript’s Support for XML-RPC and SOAP Starting with OS X version 10.1, AppleScript and the Apple Event Manager provide XML-RPC and SOAP support such that: ● Scripters can make XML-RPC calls and SOAP requests from scripts. ● Developers can make XML-RPC calls and SOAP requests from applications or other code by sending Apple events. The XML-RPC and SOAP Protocols A remote procedure call is a request to a server application at another location to perform operations and return information. XML-RPC is a simple protocol that allows software running in different environments to make remote procedure calls over the Internet. XML-RPC uses two industry standards: XML (extensible markup language) for encoding messages, and HTTP (hypertext transfer protocol) for transporting them. A properly formatted XML-RPC message is an HTTP POST request whose body is in XML. The specified remote server executes the requested call and returns any requested data in XML format. XML-RPC recognizes procedure parameters by position. Parameters and return values can be simple types such as numbers, strings, and dates, or more complex types such as structures and arrays. To learn more about XML-RPC messages, see the XML-RPC specification at http://www.xmlrpc.com/spec. SOAP (Simple Object Access Protocol) is an RPC protocol designed for a distributed environment, where a server may consist of a hierarchy of objects whose methods can be called over the Internet. A goal of SOAP is to establish a standard protocol that will serve both web service providers and service users. As with other remote procedure call protocols, SOAP uses XML to encode messages and HTTP to transport them. A SOAP request contains a header and an envelope; the envelope in turn contains the body of the request. One key difference between the SOAP and XML-RPC protocols is that with SOAP, parameters are notational (a request must encode the method parameter names within its XML), rather than positional (recognized by position). To learn more about SOAP messages, see the SOAP specification at http://www.w3.org/TR/. 2005-03-03 | Copyright © 2001, 2005 Apple Computer, Inc. All Rights Reserved. 6 About AppleScript’s Support for XML-RPC and SOAP AppleScript Support for Remote Procedure Calls Remote procedure calls provide a powerful tool for accessing services over the Internet. For example, there are already a variety of web-based servers that can check spelling, translate text between languages, provide stock prices, supply weather and traffic information, and more. You can find available services at sites such as XMethods at http://www.xmethods.net/. There you can also find information you’ll need to make remote procedure calls to these services. AppleScript Support for Remote Procedure Calls This section describes how to make XML-RPC and SOAP requests from scripts and from applications or other code. Using this support, both scripters and developers can take advantage of the growing number of XML-RPC and SOAP servers available on the Internet. 2005-03-03 | Copyright © 2001, 2005 Apple Computer, Inc. All Rights Reserved. 7 About AppleScript’s Support for XML-RPC and SOAP AppleScript Support for Remote Procedure Calls With OS X version 10.1, the Apple Event Manager is able to process Apple events that encapsulate remote procedure calls, whether the events originate from scripts or applications. Figure 2-1 (page 8) shows a simplified view of this process. Figure 1-1 The Apple Event Manager processing a remote procedure call Apple Event. Script Application Or Apple event Reply event Apple Event Manager XML XML Internet server The Apple Event Manager recognizes a remote procedure call Apple event by its address descriptor, which uses the descriptor type typeApplicationURL. To process a remote procedure call Apple event (assuming the event and the XML it contains are properly formatted), the Apple Event Manager performs these basic steps: 1.