WebReference.com - Chapter 30 of Curl Programming Bible, from John Wiley & Sons (8/8)

[previous]

Curl Programming Bible, chapter 30

Reading and Writing SOAP Headers

The SOAP Header is an optional part of a SOAP message. When a SOAP Header is present, it contains information not directly related to the SOAP operation invocation. Examples of what may be passed in SOAP Headers are authentication credentials, transaction identification, and session state information.

In Curl, SOAP Headers are represented as arrays of XMLToken. (See "The XMLToken Class" earlier in this chapter.) To include a SOAP Header in a SOAP request, use the header keyword argument in the Soap-1-1-HttpOperation.call method. Consider this code snippet that builds an array of XMLToken:

|| construct a header as an array of XMLToken
{let input-headers:{Array-of XMLToken}={new {Array-of XMLToken}}}
|| the header element is "echoMeStringRequest" containing a string
{input-headers.append {new XMLStartElement,
                          {new XMLName,
                              "https://soapinterop.org/echoheader/",
                              "echoMeStringRequest"}
                      }
}
{input-headers.append {new XMLCharacters, "Hello, Header"}}
{input-headers.append {new XMLEndElement}}

And there's a Soap-1-1-HttpOperation.call that passes the array of XMLToken so it is sent as the SOAP Header:

|| the actual SOAP call -- headers are passed a value 
|| of keyword argument
{let anys:{Array-of any}=
    {echo-void.call headers=input-headers}
}

Here is what the SOAP Header would look like in the request message for this code snippet:

<SOAP-ENV:Header>
<NS0:echoMeStringRequest xmlns:NS0="https://soapinterop.org/echoheader/">Hello, Header</NS0:echoMeStringRequest>
</SOAP-ENV:Header>

The SOAP Header in the response message is a return argument in the Soap-1-1-HttpOperation.call method. The call method returns two values: the first is an array containing the output arguments; the second is an array of XMLToken. The second value is the contents of the SOAP Header in the response message. If the SOAP response does not contain a SOAP Header, the second value returned by the call method will be an empty array. In our examples so far, we have assigned the first value returned by the Soap-1-1-HttpOperation.call method. Here is an example in which you assign both return values:

{let (anys:{Array-of any}, return-headers:{Array-of XMLToken})=
    {echo-void.call headers=input-headers, trace?=true}
}

In this example, the return-headers will contain the SOAP Header in the response message represented as an array of XMLToken.

SOAP and Security

Curl has a security model to prevent malicious and poorly written applets from causing damage to a user's machine and compromising sensitive data on intranets. As part of the security model, a Curl applet's HTTP access is limited. SOAP calls are treated the same as HTTP accesses. In general, applets residing on the local file system can not make any HTTP connections. Applets loaded from a Web server can make HTTP connections to the Web server they were loaded from. Curl provides a mechanism to override these restrictions. By placing a curl-access file on a Web server, one can allow any (or some subset of) Curl applets to access the Web server. For instance, the Web services hosted on https://www.xmethods.net are available from any Curl applet because www.xmethods.net/curl-access.txt contains the following:

	# This file tells the Curl Surge engine that it is ok to let
	# applets contact it for data
	version 2.0
	allow-all:

These security restrictions limit an applet to calling Web services on the Web server it was loaded from. That is, the host name in the URL in the Soap-1-1-HttpOperation.address field must match the host name of the applet's URL. The examples in this chapter violate this restriction by calling Web servers hosted on various Internet sites. As a result, these examples will throw a SecurityException unless run as privileged applets. Note, it is dangerous to grant privilege to an applet unless you understand the origin and operation of the applet.

CROSS-REFERENCE: See Chapter 26 for information on how to grant privilege to an applet.

Summary

This chapter gives an overview of Web services specifications. And it explains how to call Web services from Curl.

Topics covered in this chapter include the following:

• How to call SOAP operations using the Soap-1-1-HttpOperation.call method
• How to describe SOAP operation using the Soap-1-1-HttpOperation constructor
• The mappings provided between XML types and Curl types
• How to pass array arguments
• How to troubleshoot problems in SOAP calls
• How to create custom mappings so you can pass complex types in SOAP calls
• How to read and write SOAP Headers
• The implications of the Curl security model on SOAP calls

[previous]

Created: August 14, 2002
Revised: August 14, 2002

URL: https://webreference.com/programming/curlbible/chap30/8.html