Apply this attribute to a method in an XML Web service to expose the specified member as a SOAP method with a corresponding WSDL description.
[ soap_method( name ) ]
- name (optional)
- A string specifying the WSDL name of the SOAP method corresponding to this member. If omitted, the name is taken from the member to which this attribute has been applied.
|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.
This attribute injects code to parse the SOAP request. If the request is a call on this method, the injected code will unpack the parameters from the XML request, convert to the C++ parameter types, call the corresponding C++ method, pack the return types into an XML response, and return it to the client.
In addition, this attribute adds the information about the specified method to the WSDL generated for the XML Web service.
The method must have marshaling information provided for its parameters by previously declaring the method as a member of an interface. See ATL Server Web Service Supported Types for the list of supported marshaling attributes.
The types of the parameters and return value on the method to which this attribute can be applied are 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.
Parameters that are also size_is parameters for in/out arrays are not marshaled (and do not appear in the WSDL). This is an issue when you want to use the same variable for two purposes, that is, sending and receiving a value. For example:
HRESULT Meth([in,out] int *var);
var were also a size_is parameter, it would not work in a SOAP method. In the following method,
var is not marshaled at all:
HRESULT Meth([in,out] int *var, [out, size_is(*var)] BSTR **bstrArray);
In this case, the generated client side method would look like:
HRESULT Meth(BSTR** bstrArray, int* bstrArray_nSizeIs);
The first parameter,
bstrArray, is ignored (because it does not appear in the WSDL).
The workaround is to declare an additional parameter that is not a size_is parameter, so that it will appear in the WSDL and be marshaled. In the following method, the additional parameter is
HRESULT Meth( [in,out] int * OneMoreVar, [out] int *var, [out, size_is(*var)] BSTR **bstrArray );
See SOAP Server Code and see the following samples:
- DataSetConsumer Sample
- MantaWeb Sample
- OnlineAddressBook Sample
- SOAPDataTypes Sample
- SOAPState Sample
- WeatherService Sample