Handling SOAP Headers (Windows Embedded CE 6.0)
1/6/2010
The SOAP Toolkit for Windows Embedded CE allows messages to contain header content in addition to the normal body content.
Headers often pass information between the client and service that is not strictly part of the operation being performed.
For example, a client request for a login operation might cause the server to store a session ID in the header of a response message. The client would then return this session ID in the header of each subsequent request message.
The SOAP Toolkit allows headers to be accessed and created on client and server.
Using Headers on the Client Side
To use headers on the client, you must provide a COM class that implements the IHeaderHandler interface. Further, you must have the HeaderHandler property of the SoapClient object reference an instance of this class. You access the SoapClient object using the ISoapClient interface.
Each time the client application calls a method of the SoapClient object, the SoapClient object calls the ISoapClient::willWriteHeaders method of the header handler.
If willWriteHeaders returns True, the SoapClient object writes a SOAP <Header> element to the request message and then calls the IHeaderHandler::writeHeaders method.
The writeHeaders method uses the specified SoapSerializer object (accessed using the ISoapSerializer interface) to write header content. The SoapClient object then writes the body of the request message, sends the message to the server, and receives the response message.
When the response message is complete, the SoapClient object calls the IHeaderHandler::readHeader method once for each header in the response message. Finally, the operation method returns to the client application.
On the client, the pObject parameter of the readHeader and writeHeader methods is always NULL. Also, the return value of readHeader is ignored.
Using Headers on the Server Side
To use headers in the service, you must provide a COM class that implements the IHeaderHandler interface and identify that class in the appropriate <service> element in the Web Services Meta Language (WSML) file.
In that <service> element, you use a <using> element to define the header handler object. Then, to associate this header handler object to a particular port or service, you use the headerHandler attribute of that particular <port> or <operation> element.
For example, the following WSML file defines the ServiceHeaderHandler object as being the SessionInfo.ServiceHeaderHandler class; then it associates the handler with the port named ServiceSoapPort.
<service name='SessionInfo'>
<using PROGID='SessionInfo.Service' cachable='0' ID='ServiceObject' />
<using PROGID='SessionInfo.ServiceHeaderHandler'
cachable='0' ID='ServiceHeaderHandler' />
<port name='ServiceSoapPort' headerHandler="ServiceHeaderHandler">
...
</port>
</service>
When the server receives a request for a port or operation that a header handler is defined for, the SoapServer object calls the header handler's readHeader method for each header in the request message.
If the handler understood the header, the readHeader method returns True.
If the header handler returns False for a header that contains the mustUnderstand='1' attribute, the SoapServer object returns the must understand fault.
The pObject parameter passed to readHeader method references the object that is going to handle the request.
The header handler sets properties or call methods on this object as necessary to prepare it for the request.
After each header in the request is passed to the readHeader method, the SoapServer object calls the server object. When the server object returns, the SoapServer object calls the header handler's willWriteHeaders method.
If willWriteHeaders returns True, the SoapServer calls the handler's writeHeader method. The pObject parameter passed to the writeHeader references the object that has handled the request.
The header handler accesses properties or call methods on this object as necessary to retrieve the information to be sent in the response header.
The writeHeader method can use the provided SoapSerializer object to write header content to the response message.