Description

Obtains a SOAP request header. Call only from within a CFC web service function that is processing a request as a SOAP web service.

Returns

A SOAP request header.

Category

XML functions

History

ColdFusion MX 7: Added this function.

Function syntax

GetSOAPRequestHeader(namespace, name [, asXML])

See also

AddSOAPRequestHeader, AddSOAPResponseHeader, GetSOAPRequest, GetSOAPResponse, GetSOAPResponseHeader, IsSOAPRequest; "Basic web service concepts" in the ColdFusion Developer's Guide

Parameters

Usage

If you specify false for the asXML parameter, ColdFusion first attempts to retrieve the header using the data type specified in the header's xsi:type attribute. If the xsi:type attribute is not available, ColdFusion attempts to retrieve the header as a string. If you specify true for the asXML parameter, ColdFusion retrieves the header as raw XML.

This function throws an error if it is invoked in a context that is not a web service request. Use the IsSOAPRequest function to determine whether the CFC is running as a web service.

Example

This example creates a CFC web service that illustrates the operation of the GetSOAPRequestHeader function and also provides a web service that illustrates the operation of other ColdFusion SOAP functions.

Save the following code as headerservice.cfc in a folder called soapheaders under your web root. Test its operation, and specifically the operation of the GetSOAPRequestHeader function, by executing the examples that invoke this web service. For example, see the example for AddSOAPRequestHeader.

<h3>GetSOAPRequestHeader Example</h3>
<cfcomponent displayName="tester" hint="Test for SOAP headers">

<cffunction name="echo_me" 
    access="remote"
    output="false" 
    returntype="string" 
    displayname="Echo Test" hint="Header test">
    
<cfargument name="in_here" required="true" type="string">

<cfset isSOAP = isSOAPRequest()>
<cfif isSOAP>

    <!--- Get the first header as a string and as XML --->
    <cfset username = getSOAPRequestHeader("http://mynamespace/", "username")>
    <cfset return = "The service saw username: " & username>
    <cfset xmlusername = getSOAPRequestHeader("http://mynamespace/", "username", "TRUE")>
    <cfset return = return & "<br> as XML: " & xmlusername>
    
    <!--- Get the second header as a string and as XML --->
    <cfset password = getSOAPRequestHeader("http://mynamespace/", "password")>
    <cfset return = return & "The service saw password: " & password>
    <cfset xmlpassword = getSOAPRequestHeader("http://mynamespace/", "password", "TRUE")>
    <cfset return = return & "<br> as XML: " & xmlpassword>

    <!--- Add a header as a string --->
<cfset addSOAPResponseHeader("http://www.tomj.org/myns", "returnheader", "AUTHORIZED VALUE", false)>

    <!--- Add a second header using a CFML XML value --->
    <cfset doc = XmlNew()>
    <cfset x = XmlElemNew(doc, "http://www.tomj.org/myns", "returnheader2")>
    <cfset x.XmlText = "hey man, here I am in XML">
    <cfsetx.XmlAttributes["xsi:type"] = "xsd:string">
    <cfset tmp = addSOAPResponseHeader("ignoredNameSpace", "ignoredName", x)> 

<cfelse>
    <!--- Add a header as a string - Must generate error! 
<cfset addSOAPResponseHeader("http://www.tomj.org/myns", "returnheader", "AUTHORIZED VALUE", false)>
    --->
<cfset return = "Not invoked as a web service">
</cfif>

<cfreturn return>

</cffunction>

</cfcomponent>