SFXSOAPWriter

Class for creating a SOAP message.

#include <SFXSOAPWriter.hpp>

class SFXSOAPWriter : public static_exception< SFCError >;

SFMTYPEDEFCLASS(SFXSOAPWriter)

Inheritance diagram

Collaboration diagram

Description

SFXSOAPWriter is the class for creating a SOAP message.

	Note
	When creating a SOAP message using this class, functions such as `SFXSOAPWriter::SetBody`, `SFXSOAPWriter::SetEnvelope`, `SFXSOAPWriter::SetFault`, `SFXSOAPWriter::SetFaultDetail` and so on can be called in any order.

	About Simple Object Access Protocol ( SOAP )
	W3C SOAP latest information : Latest SOAP versions (SOAP 1.1 and SOAP 1.2 are supported. However, SOAP Attachment has not been implemented and only SOAP Fault of SOAP 1.1 is supported.)

Example 840. The method to create the SOAP message using the SFXSOAPWriter class

SFXSOAPWriter soapwriter;   // variable to generate each element of SOAP message
SFCError      error;        // variable to store error value

// create Envelope element
// namespace prefix: "SOAP-ENV" by default
// SOAP Message Version: SFXSOAPParser::SOAP_VERSION_1_2 ("http://www.w3.org/2003/05/soap-envelope") or
//                SFXSOAPParser::SOAP_VERSION_1_1 ("http://schemas.xmlsoap.org/soap/envelope/") 
// SOAP encoding: "STANDARD "("http://schemas.xmlsoap.org/soap/encoding/" ) or 
//                "NONE "(No SOAP encoding is set)
SFXXMLElementPtr envelope = soapwriter.SetEnvelope("env", SFXSOAPParser::SOAP_VERSION_1_2, "STANDARD ");


// create Header and Body elements
if (envelope) {

    // add namespace xmlns:m= "http://www.example.org/timeouts"
    error = soapwriter.AddNamespace(envelope, "m", "http://www.example.org/timeouts");
    // confirm whether namespace has been added or not
    if(error != SFERR_NO_ERROR){
         TRACE("-----Envelope_NAMESPACE_ERROR:%d-----", error);
    }
    // set SOAP Fault element consisted of faultcode, faultstring, and faultactor elements (by default, it is the child element of Body element)
    soapwriter.SetFault("testing-fault-code","testing-fault-string","testing-fault-actor");

    // set detail element to SOAP Fault element
    soapwriter.SetFaultDetail("STANDARD")->SetText("testing-fault-detail-message");

    // set Header element
    SFXXMLElementPtr header = soapwriter.SetHeader();

    if (header) {
        // add attribute of isbn:bookname="The Football World Cup"
        error = soapwriter.AddAttribute(header, "bookname", "http://www.example.com/ISBN", "The Football World Cup", "isbn");
        // confirm whether attribute has been added or not
        if(error != SFERR_NO_ERROR){
            TRACE("-----HEADER_ATTRIBUTE_ERROR:%d-----", error);
        }
           
        // add namespace xmlns:isbn="http://www.example.com/ISBN"
        error = soapwriter.AddNamespace(header, "isbn", "http://www.example.com/ISBN");
        // confirm whether namespace has been added or not
        if(error != SFERR_NO_ERROR){
            TRACE("-----HEADER_NAMESPACE_ERROR:%d-----", error);
        }

        // add Upgrade element as child element of Header element
        // namespace of Upgrade element is the same as that of Header element
        SFXXMLElementPtr elem = soapwriter.SetElement(header, "Upgrade", header->GetNamespaceURI(), header->GetPrefix());

        if (elem) {
            // set SupportedEnvelope element as child element of Upgrade element
            elem = soapwriter.SetElement(elem, "SupportedEnvelope", header->GetNamespaceURI(), header->GetPrefix());

            // add attribute of SupportedEnvelope element
            error = soapwriter.AddAttribute(elem, "qname", "http://schemas.xmlsoap.org/soap/envelope/", "ns1:Envelope");
            // confirm whether attribute has been added or not
            if(error != SFERR_NO_ERROR){
                TRACE("-----UPGRADE_ATTRIBUTE_ERROR:%d-----", error);
            }
                
            // add namespace of SupportedEnvelope element
            error = soapwriter.AddNamespace(elem, "ns1", "http://schemas.xmlsoap.org/soap/envelope/");   
            // confirm whether namespace has been added or not
            if(error != SFERR_NO_ERROR){
                TRACE("-----UPGRADE_NAMESPACE_ERROR:%d-----", error);
            }
        }
    }

    // save SOAP message created
    error = soapwriter.Save("soapwriter.xml");

    // confirm SOAP message has been stored or not
    if(error != SFERR_NO_ERROR){
        TRACE("-----SOAP_SAVE_ERROR:%d-----", error);
    }

}

Example 841. Execution Result: SOAP message created by the above code ( "soapwriter.xml" )

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
              xmlns:m="http://www.example.org/timeouts">
    <env:Header isbn:bookname="The Football World Cup" xmlns:isbn="http://www.example.com/ISBN">
        <env:Upgrade>
            <env:SupportedEnvelope qname="ns1:Envelope" xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"/>
        </env:Upgrade>
    </env:Header>
    <env:Body>
        <env:Fault>
            <faultcode>testing-fault-code</faultcode>
            <faultstring>testing-fault-string</faultstring>
            <faultactor>testing-fault-actor</faultactor>
            <detail env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">testing-fault-detail-message</detail>
        </env:Fault>
    </env:Body>
</env:Envelope>

Reference

SFXSOAPParser |

Member

Constructor/Destructor
SFXSOAPWriter( `Void` ) Constructor of the SFXSOAPWriter class.
~SFXSOAPWriter( `Void` ) Desctructor of SFXSOAPWriter class.

Public Functions
`SFCError`	AddAttribute( `SFXXMLElementPtr` element , `SFXAnsiStringConstRef` name , `SFXAnsiStringConstRef` uri = SFXAnsiString::EmptyInstance() , `SFXAnsiStringConstRef` value = SFXAnsiString::EmptyInstance() , `SFXAnsiStringConstRef` prefix = SFXAnsiString::EmptyInstance() ) Add an attribute to the element.
`SFCError`	AddNamespace( `SFXXMLElementPtr` element , `SFXAnsiStringConstRef` prefix , `SFXAnsiStringConstRef` uri ) Add a namespace to an element.
`Void`	Reset( `Void` ) Reset all the internal variables.
`SFCError`	Save( `SFXAnsiStringConstRef` output , `Bool` indent = true ) Save the SOAP message to the file.
`SFCError`	Save( `SFXOutputStreamRef` output , `Bool` indent = true ) Save the SOAP message to the file.
`SFCError`	Save( `SFXPathConstRef` output , `Bool` indent = true ) Save the SOAP message to the file.
`SFXXMLElementPtr`	SetBody( `SFXAnsiStringConstRef` encodingstyle = "NONE" ) Set the Body element to the SOAP message.
`SFXXMLElementPtr`	SetElement( `SFXXMLElementPtr` parent , `SFXAnsiStringConstRef` name , `SFXAnsiStringConstRef` uri = SFXAnsiString::EmptyInstance() , `SFXAnsiStringConstRef` prefix = SFXAnsiString::EmptyInstance() , `SFXAnsiStringConstRef` text = SFXAnsiString::EmptyInstance() , `SFXAnsiStringConstRef` encodingstyle = "NONE" ) Set the child element to an element
`SFXXMLElementPtr`	SetEnvelope( `SFXAnsiStringConstRef` prefix = SFXAnsiString::EmptyInstance() , `SFXSOAPParser::SOAP_VERSION` version = SFXSOAPParser::SOAP_VERSION_1_1 , `SFXAnsiStringConstRef` encodingstyle = "NONE" ) Set the Envelope element to the SOAP message.
`SFXXMLElementPtr`	SetFault( `SFXAnsiStringConstRef` faultcode , `SFXAnsiStringConstRef` faultstring , `SFXAnsiStringConstRef` faultactor = SFXAnsiString::EmptyInstance() ) Set the Fault element(faultcode, faultstring, and faultactor elements) to the SOAP message.
`SFXXMLElementPtr`	SetFaultDetail( `SFXAnsiStringConstRef` encodingstyle = "NONE" ) Set the detail element to the SOAP message.
`SFXXMLElementPtr`	SetHeader( `SFXAnsiStringConstRef` encodingstyle = "NONE" ) Set the Header element to the SOAP message.

SFXSOAPWriter::SFXSOAPWriter

Constructor of the SFXSOAPWriter class.

[ public, explicit ]
SFXSOAPWriter(Void);

SFXSOAPWriter::~SFXSOAPWriter

Desctructor of SFXSOAPWriter class.

[ public ]
~SFXSOAPWriter(Void);

SFXSOAPWriter::AddAttribute

Add an attribute to the element.

[ public ]
SFCError AddAttribute(
    SFXXMLElementPtr element                                        // element
    SFXAnsiStringConstRef name                                      // name of attribute 
    SFXAnsiStringConstRef uri = SFXAnsiString::EmptyInstance()      // namespace URI of attribute
    SFXAnsiStringConstRef value = SFXAnsiString::EmptyInstance()    // value of attribute 
    SFXAnsiStringConstRef prefix = SFXAnsiString::EmptyInstance()   // namespace prefix of attribute
);

Return value

If succeeds: SFERR_NO_ERROR
If the Envelope element not found: SFERR_SOAP_EXPECT_ENVELOPE
If argument is invalid: SFERR_INVALID_PARAM
If attribute cannot be added: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

SFXSOAPWriter::AddNamespace

Add a namespace to an element.

[ public ]
SFCError AddNamespace(
    SFXXMLElementPtr element       // element
    SFXAnsiStringConstRef prefix   // namespace prefix
    SFXAnsiStringConstRef uri      // namespace URI
);

Return value

If succeeds: SFERR_NO_ERROR
If the Envelope element not found: SFERR_SOAP_EXPECT_ENVELOPE
If argument is invalid: SFERR_INVALID_PARAM
If namespace cannot be added: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

SFXSOAPWriter::Reset

Reset all the internal variables.

[ public ]
Void Reset(Void);

SFXSOAPWriter::Save

Save the SOAP message to the file.

[ public ]
SFCError Save(
    SFXAnsiStringConstRef output   // file name
    Bool indent = true             // whether or not to indent
);

[ public ]
SFCError Save(
    SFXOutputStreamRef output   // output stream
    Bool indent = true          // whether or not to indent
);

[ public ]
SFCError Save(
    SFXPathConstRef output   // file path
    Bool indent = true       // whether or not to indent
);

Return value

If succeeds: SFERR_NO_ERROR
If Envelope element is not found: SFERR_SOAP_EXPECT_ENVELOPE( 0x699F )
If Body element is not found: SFERR_SOAP_EXPECT_BODY( 0x69A0 )
If file for SOAP message has already been opened: SFERR_INVALID_STATE
If argument is invalid: SFERR_INVALID_PARAM
If insufficent memory: SFERR_NO_MEMORY
If failed: SFERR_FAILED
Other errors : error value defined in the AEEError.h

Description

Save the SOAP message to the specified file or stream.

The default directory of file path is the home directory of application.

SFXSOAPWriter::SetBody

Set the Body element to the SOAP message.

[ public ]
SFXXMLElementPtr SetBody(
    SFXAnsiStringConstRef encodingstyle = "NONE"   // SOAP encoding
);

Argument

encodingstyle

The values for the SOAP encoding are defined as follows:

Value	Description
"NONE"	SOAP encoding is not specified
"STANDARD"	"http://schemas.xmlsoap.org/soap/encoding/" is specified.

Description

Set the Body element to the SOAP message. If the Body element has already existed, this setting is not performed.

SOAP encoding is not for encoding the characters but for representing the data types of SOAP document as XML format.

Usually, the encoding style defined at the " http://schemas.xmlsoap.org/soap/envelope/ " URI is used as SOAP encoding.

	About SOAP encoding
	W3C Simple Object Access Protocol (SOAP) 1.1 : SOAP Encoding

SFXSOAPWriter::SetElement

Set the child element to an element

[ public ]
SFXXMLElementPtr SetElement(
    SFXXMLElementPtr parent                                         // parent element
    SFXAnsiStringConstRef name                                      // name of child element
    SFXAnsiStringConstRef uri = SFXAnsiString::EmptyInstance()      // namespace URI of child element
    SFXAnsiStringConstRef prefix = SFXAnsiString::EmptyInstance()   // namespace prefix of child element
    SFXAnsiStringConstRef text = SFXAnsiString::EmptyInstance()     // text content of child element
    SFXAnsiStringConstRef encodingstyle = "NONE"                    // SOAP encoding of child element
);

Argument

encodingstyle

The values for the SOAP encoding are defined as follows:

Value	Description
"NONE"	SOAP encoding is not specified.
"STANDARD"	"http://schemas.xmlsoap.org/soap/encoding/" is specified.

SFXSOAPWriter::SetEnvelope

Set the Envelope element to the SOAP message.

[ public ]
SFXXMLElementPtr SetEnvelope(
    SFXAnsiStringConstRef prefix = SFXAnsiString::EmptyInstance()           // namespace prefix of Envelope element
    SFXSOAPParser::SOAP_VERSION version = SFXSOAPParser::SOAP_VERSION_1_1   // version of SOAP document
    SFXAnsiStringConstRef encodingstyle = "NONE"                            // SOAP encoding of the Envelope element
);

Argument

prefix

Namespace prefix of the Envelop element. (default: "SOAP-ENV")

encodingstyle

The values for the SOAP encoding are defined as follows:

Value	Description
"NONE"	SOAP encoding is not specified
"STANDARD"	"http://schemas.xmlsoap.org/soap/encoding/" is specified.

Description

Set the Envelope element to the SOAP message. If the Envelope element has already existed, this setting is not performed.

SFXSOAPWriter::SetFault

Set the Fault element(faultcode, faultstring, and faultactor elements) to the SOAP message.

[ public ]
SFXXMLElementPtr SetFault(
    SFXAnsiStringConstRef faultcode                                     // content of faultcode
    SFXAnsiStringConstRef faultstring                                   // content of faultstring
    SFXAnsiStringConstRef faultactor = SFXAnsiString::EmptyInstance()   // content of faultactor
);

Description

Set the Fault element(faultcode, faultstring, and faultactor elements) to the SOAP message. If the Fault element have already existed, this setting is not performed.

SFXSOAPWriter::SetFaultDetail

Set the detail element to the SOAP message.

[ public ]
SFXXMLElementPtr SetFaultDetail(
    SFXAnsiStringConstRef encodingstyle = "NONE"   // SOAP encoding
);

Argument

encodingstyle

The values for the SOAP encoding are defined as follows:

Value	Description
"NONE"	SOAP encoding is not specified
"STANDARD"	"http://schemas.xmlsoap.org/soap/encoding/" is specified.

SFXSOAPWriter::SetHeader

Set the Header element to the SOAP message.

[ public ]
SFXXMLElementPtr SetHeader(
    SFXAnsiStringConstRef encodingstyle = "NONE"   // SOAP encoding
);

Argument

encodingstyle

The values for the SOAP encoding are defined as follows:

Value	Description
"NONE"	SOAP encoding is not specified
"STANDARD"	"http://schemas.xmlsoap.org/soap/encoding/" is specified.

Description

Set the Header element to the SOAP message. If the Header element has already existed, this setting is not performed.