<html>
<head>
<link href="mmres://user_interface_reference.css" rel="stylesheet" type="text/css">
<title>ADDSOAPREQUESTHEADER</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
   <div id="Description">
   <table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
      <tr> 
         <td valign="top" class="name">ADDSOAPREQUESTHEADER</td>
         <td valign="top" nowrap class="compatibility">&nbsp;</td>
      </tr>
      <tr>
         <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
      </tr>


    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Description</span>
<p>
Adds a SOAP header to a web service request before making the request. 
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Returns</span>
<p>
Nothing.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Category</span>
<p>
XML functions
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">History</span>
<p>
ColdFusion&#160;MX&#160;7: Added this function.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Function syntax</span><pre>AddSOAPRequestHeader(webservice, namespace, name, value [, mustunderstand])
</pre>    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">See also</span>
<p>
AddSOAPResponseHeader, GetSOAPRequest, GetSOAPRequestHeader, GetSOAPResponse, GetSOAPResponseHeader, IsSOAPRequest; "Basic web service concepts" in Chapter&#160;36, "Using Web Services," in ColdFusion MX Developer's Guide
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Parameters</span>
<p>

</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Usage</span>
<p>
Used within CFML code by a consumer of a web service before it calls the web service.
</p>

<p>
If you pass XML in the value parameter, ColdFusion ignores the namespace and name parameters. If you require a namespace, define it within the XML itself.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Example</span>
<p>
There are two parts to this example. The first part is the web service CFC that this function (as well as the other ColdFusion SOAP functions) uses to demonstrate its interaction with a web service. To implement the web service for this function, see the example for AddSOAPResponseHeader.
</p>

<p>
Execute the following example as a client to see how the AddSOAPRequestHeader function operates.
</p>
<pre>&lt;!--- Note that you might need to modify the URL in the CreateObject function
to match your server and the location of the headerservice.cfc file if it is
different than shown here. Likewise for the cfinvoke tag at the end. ---&gt;

&lt;h3&gt;AddSOAPRequestHeader Example&lt;/h3&gt;
&lt;cfscript&gt;
 // Create the web service object.
 ws = CreateObject(&quot;webservice&quot;, &quot;http://localhost/soapheaders/
headerservice.cfc?WSDL&quot;);
 
 // Set the username header as a string.
 addSOAPRequestHeader(ws, &quot;http://mynamespace/&quot;, &quot;username&quot;, &quot;tom&quot;, false);
 
 // Set the password header as a CFML XML object.
 doc = XmlNew();
 doc.password = XmlElemNew(doc, &quot;http://mynamespace/&quot;, &quot;password&quot;);
 doc.password.XmlText = &quot;My Voice is my Password&quot;;
 doc.password.XmlAttributes[&quot;xsi:type&quot;] = &quot;xsd:string&quot;;
 addSOAPRequestHeader(ws, &quot;ignoredNameSpace&quot;, &quot;ignoredName&quot;, doc);
  
 // Invoke the web service operation.
 ret = ws.echo_me(&quot;argument&quot;);
 
 // Get the first header as an object (string) and as XML.
 header = getSOAPResponseHeader(ws, &quot;http://www.tomj.org/myns&quot;, 
&quot;returnheader&quot;);
 XMLheader = getSOAPResponseHeader(ws, &quot;http://www.tomj.org/myns&quot;, 
&quot;returnheader&quot;, true);

 // Get the second header as an object (string) and as XML.
 header2 =  getSOAPResponseHeader(ws, &quot;http://www.tomj.org/myns&quot;, 
&quot;returnheader2&quot;);
 XMLheader2 = getSOAPResponseHeader(ws, &quot;http://www.tomj.org/myns&quot;, 
&quot;returnheader2&quot;, true);
&lt;/cfscript&gt;
&lt;hr&gt;
&lt;cfoutput&gt;
Soap Header value: #HTMLCodeFormat(header)#&lt;br&gt;
Soap Header XML value: #HTMLCodeFormat(XMLheader)#&lt;br&gt;
Soap Header 2 value: #HTMLCodeFormat(header2)#&lt;br&gt;
Soap Header 2 XML value: #HTMLCodeFormat(XMLheader2)#&lt;br&gt;
Return value: #HTMLCodeFormat(ret)#&lt;br&gt;
&lt;/cfoutput&gt;
&lt;hr&gt;

&lt;cfinvoke component=&quot;soapheaders.headerservice&quot; method=&quot;echo_me&quot; 
returnvariable=&quot;ret&quot; in_here=&quot;hi&quot;&gt;
&lt;/cfinvoke&gt;
&lt;cfoutput&gt;Cfinvoke returned: #ret#&lt;/cfoutput&gt;
</pre>
         </td>
      </tr>
   </table>
   </div>
<div id="WEBSERVICE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">WEBSERVICE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>A web service object as returned from the cfobject tag or the CreateObject function.</p>

  </td>
  </tr>
  </table>
</div>
<div id="NAMESPACE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">NAMESPACE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>A string that is the namespace for the header.</p>

  </td>
  </tr>
  </table>
</div>
<div id="NAME">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">NAME</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>A string that contains the name of the SOAP header in the request.</p>

  </td>
  </tr>
  </table>
</div>
<div id="VALUE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">VALUE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>The value for the SOAP header; this can be a CFML XML value.</p>

  </td>
  </tr>
  </table>
</div>
<div id="MUSTUNDERSTAND">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">MUSTUNDERSTAND</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>Optional. True or False (default). Sets the SOAP mustunderstand value for this header.</p>

  </td>
  </tr>
  </table>
</div>

  </body>
</html>
