Export (0) Print
Expand All

soap_method 

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
) ]

Parameters

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.

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);

However if 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 OneMoreVar:

HRESULT Meth( [in,out] int * OneMoreVar, [out] int *var, 
               [out, size_is(*var)] BSTR **bstrArray );

Attribute Context

Applies to

Method, coclass method

Repeatable

No

Required attributes

None.

Invalid attributes

None

For more information about the attribute contexts, see Attribute Contexts.

Attribute Requirements

Header

atlsoap.h

Project

EXE, DLL

Compiler

/D "_ATL_ATTRIBUTES"

For more information about the meaning of the requirements, see Attribute Requirements.

Community Additions

ADD
Show:
© 2014 Microsoft