AddSoapHeaderNode - cClientWebService

Adds a SOAP header node to a method's request.

Parameters

Parameter	Type	Description
hoNode	Handle	The handle to an XML element node to added as a SOAP header

Syntax

Procedure AddSoapHeaderNode Handle hoNode

Call Example

Send AddSoapHeaderNode hoNode

Description

AddSoapHeaderNode is used to add SOAP headers to a method's SOAP request. This method, along with ClearSoapHeaders, is used to create and manage SOAP request headers. This is a low level mechanism. It is expected that a developer using this method understands SOAP Headers and understands how to work with XML objects.

The handle passed to this method must be a handle to an XML element object (cXMLDomElement). If an element node is not passed, an error will be generated.

Note that you do need to pass the actual SOAP node -- this is done for you. Instead you pass the element nodes that are the children of the header node. Each time you call AddSoapHeaderNode, you add a new node to the SOAP header.

<SOAP-ENV:Header 
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<Transaction xmlns="some-URI">5</Transaction>
   <RetryCount xmlns="some-URI">2</RetryCount>
</SOAP-ENV:Header>

The above SOAP header could be created as follows:

Procedure CallTheMethod
    Handle hoXml hoRoot hoNode
    String sName sReply


    // always first clear any existing headers 
    Send ClearSoapHeaders of oWSTestService1

    Get Create U_cXmlDomDocument to hoXml
    Get CreateDocumentElementNS of hoXml "some-URI" "Nodes" to hoRoot

    // create and add first SOAP Header
    Get AddElementNS of hoRoot "some-URI" "Transaction" "5" to hoNode
    Send AddSoapHeaderNode of oWSTestService1 hoNode
    Send Destroy of hoNode

    // create and add second SOAP Header
    Get AddElementNS of hoRoot "some-URI" "RetryCount" "2" to hoNode
    Send AddSoapHeaderNode of oWSTestService1 hoNode
    Send Destroy of hoNode

    // destroy the XML object
    Send Destroy of hoXml

    // invoke the service
    Get Value of oRequest to sName
    Get wsSayHello of oWSTestService1 sName to sReply
    Set Value of oResponse to sReply
End_Procedure

Lifespan of SOAP Request Headers

SOAP request headers in a web service client are maintained at the object level and not at the method level. When a header is added, it is added to all web service methods that are called within the object. Once a SOAP header is added, it will be added to all methods until the headers are all cleared using ClearSoapHeaders.

As a general rule, if you are using SOAP request headers in a web service object you should always clear the soap headers and add the new soap headers for each web service invocation.