SOAP Header structure. More...

Detailed Description

SOAP Header structure.

This structure is generated by the wsdl2h tool from a WSDL with SOAP Header definitions and/or by soapcpp2 to complete the SOAP Header definitions. The SOAP Header definitions can also be specified manually in the interface header file for soapcpp2. If no SOAP Header structure is declared in the interface header file input to soapcpp2 then the soapcpp2 tool will generate an empty structure.

A SOAP Header contains meta-data, such as WS-Addressing and WS-Security headers, associated with messages. SOAP Header elements may be marked with mustUnderstand which produces and recognizes SOAP_ENV:mustUnderstand="true" in XML to force the receiver to produce an error if the header element was not recognized.

The //gsoap <prefix> service method-input-header-part: and //gsoap <prefix> service method-output-header-part: directives indicates which member (i.e. XML element) of SOAP_ENV__Header is relevant to the input and output SOAP Headers associated with a service operation.

Because this structure is declared mutable (which is a C/C++ extension that only soapcpp2 understands), multiple SOAP_ENV__Header structures in the interface header file input are combined into one structure generated by soapcpp2 for C/C++ compilation.

Example:

// example .h file for soapcpp2
//gsoap ns service name: example
//gsoap ns service namespace: urn:example
struct SOAP_ENV__Header {
  mustUnderstand int *ns__someHeaderValue; // optional element with SOAP_ENV:mustUnderstand="true" attribute
};
//gsoap ns service method-input-header-part: webmethod ns__someHeaderValue
//gsoap ns service method-output-header-part: webmethod ns__someHeaderValue
int ns__webmethod(...);

#include "soapH.h"
struct soap *soap = soap_new();
... // context initializations
// add a SOAP Header to the message
soap->header = NULL; // make sure we allocate a new header
soap_header(soap);   // allocate SOAP_ENV__Header and set soap->header to point to it
int num = 123;
soap->header->ns__someHeaderValue = &num;
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
{
  soap_print_fault(soap, stderr);
}
else
{
  if (soap->header) // received a SOAP_ENV__Header?
    ... // yes, inspect SOAP_ENV__Header ns__someHeaderValue
}
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

See also: soap::header, soap::actor, soap_header.