ATL Attributes: soap_handler

Adds support for SOAP

Syntax

[
    define_attribute = "soap_handler",
    argument_list = {
        "name",
        "namespace",
        "protocol",
        "style",
        "use"
    },
    argument_type ("name") = eANSIStringValue,
    argument_type ("namespace") = eANSIStringValue,
    argument_type ("protocol") = eANSIStringValue,
    argument_type ("style") = eANSIStringValue,
    argument_type ("use") = eANSIStringValue,
    default_value ("name") = "",
    default_value ("namespace") = "",
    default_value ("protocol") = "soap",
    default_value ("style") = "rpc",
    default_value ("use") = "encoded",
    help_string = "Adds support for SOAP",
    usage = eClassUsage | eCoClassUsage | eStructUsage,
    group = eHPS,
    shipping = true
];

An empty (or defaulted) namespace argument is effectively a direction to form the namespace as urn:class, where class is the name of the target class.

The case-insensitive style argument can be document or rpc. Anything else is an error (ATL2238). The case-insensitive use argument can be literal or encoded. Anything else is an error (ATL2239). It is an error (ATL2237) to combine rpc with literal, or document with encoded.

It is an error (ATL2249) if the name argument contains any character that is not a letter, digit or underscore.

Documentation Error

As the product documentation says: “the majority of attributes are not repeatable.” The product documentation makes repeatable attributes seem even more uncommon, because many that actually are repeatable are said not to be. For soap_handler, the product documentation is incorrect in the other direction. This attribute is plainly said to be repeatable. Yet it just as plainly is not. The following example is close to minimal:

#define     _WIN32_WINNT 0x0400
#define     _ATL_ATTRIBUTES
#include    <atlbase.h>
#include    <atlsoap.h>

__interface ITest
{
    HRESULT Method (VOID);
};

[
    soap_handler (""),          // C3319
    soap_handler ("")
]
class CTest : public ITest
{
    [soap_method] HRESULT Method (VOID);
};

The error message complains specifically that the soap_handler attribute cannot be repeated (albeit citing the first occurrence rather than the repeat). Delete the repetition and the error goes away.

Note, by contrast, that the product documentation says the soap_header attribute is not repeatable when in fact it is. The relevance is that where the documentation for soap_handler refers to soap_header, there is a strong suggestion that soap_header must be repeatable: “Use the soap_header attribute on SOAP methods where you want to obtain or attach the value of one or more SOAP headers.” Perhaps the reason the documentation is wrong for both attributes is simply that their (similar) names got confused by whoever at Microsoft had the bookkeeping task of transferring content from the formal syntax definitions in the source code to the corresponding tables in the documentation.