Apply this attribute to a SOAP method in an XML Web service to specify the data member used to hold the value of a SOAP header.
[ soap_header( value, required, in, out ) ]
- A string specifying the name of the data member representing the SOAP header.
- required (optional)
- A Boolean value specifying whether the SOAP header is required. If omitted, default is false.
- in (optional)
- A Boolean value specifying whether the SOAP header should be sent to the server from the client. If omitted, default is true.
- out (optional)
- A Boolean value specifying whether the SOAP header should be sent to the client from the server. If omitted, default is true.
|Applies to||Method, coclass method|
For more information about the attribute contexts, see Attribute Contexts.
For more information about the meaning of the requirements, see Attribute Requirements.
If in is true, this attribute injects code to parse the SOAP request for the appropriate header. If the SOAP header is present when the method is called, the value of the corresponding data member will be set to the value of the header.
If out is true, the attribute will ensure that the value of the data member will be packaged as a SOAP header in the response and sent back to the client when the method returns.
In addition, the attribute adds the information about the specified header to the WSDL generated for the XML Web service.
The type of the data member to which this attribute can be applied is limited to the types supported by ATL Server for SOAP. See ATL Server Web Service Supported Types for the list of allowed C++ data types and their corresponding W3C schema data types.
Memory for SOAP method parameters and members used as SOAP headers must be allocated and freed using the memory manager returned by CSoapRootHandler::GetMemMgr (except for BSTRs, which must be allocated using SysAllocString and related functions). Apart from using CSoapRootHandler::GetMemMgr instead of the COM task allocator, COM memory allocation rules apply.
Note that the contents of the data member specified using this attribute are only valid during the method call. If data was put in the data member by the ATL Server code as a result of the call, it will be freed when the method returns.
See soap_handler for details of the effects of this attribute.
See SOAP Server Code and see the SOAPState Sample.