PrevNextUpHome BREW C++ Class Library & GUI Framework & XML Middleware : SophiaFramework 4.1
SFXSOAPRPC
Class for processing the SOAP-RPC protocol.
#include <SFXSOAPRPC.hpp>
class SFXSOAPRPC;
SFMTYPEDEFCLASS(SFXSOAPRPC)

Inheritance diagram

 Collaboration diagram of SFXSOAPRPCClass

Description

SFXSOAPRPC is the class that supports the SOAP-RPC protocol.

[Note] 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 488. The method to call the web service using the SOAP-RPC Protocol

#define AMAZON_ID "" // Amazon ID must be set

SFMTYPEDEFCLASS(SOAPTest)
class SOAPTest : public SFCApplication {
    SFMSEALCOPY(SOAPTest)
private:
    SFXSOAPRPC _rpc;    // variable for processing the SOAP-RPC protocol

    Void OnSOAP(Void);
    static Void OnResultSHP_SOAP(SFCError error, const SFXSOAPRPC::Params& result, const SFXSOAPRPC::FAULT& fault, SFXSOAPParserConstRef soap, VoidPtr reference);
    Void OnResult_SOAP(SFCError error, const SFXSOAPRPC::Params& result, const SFXSOAPRPC::FAULT& fault, SFXSOAPParserConstRef soap);
};

Void SOAPTest::OnSOAP()
{
    // set method name
    _rpc.SetMethodName("ItemSearch");
    
    // set SOAP encoding
    _rpc.SetEncodingStyle("http://schemas.xmlsoap.org/soap/encoding/");
    // the following code is the same as the above
	// _rpc.SetEncodingStyle("STANDARD");

    // set target URI
    _rpc.SetTargetObjectURI("https://webservices.amazon.com/");

    // set parameters of web service
    _rpc.AddParameter("AWSAccessKeyId", 
                      SFXBuffer(SFXAnsiString(AMAZON_ID)));
    _rpc.AddParameter("Keywords", 
                      SFXBuffer(SFXAnsiString("caviar")));
    _rpc.AddParameter("MerchantId", 
                      SFXBuffer(SFXAnsiString("Amazon")));
    _rpc.AddParameter("SearchIndex", 
                      SFXBuffer(SFXAnsiString("GourmetFood")));

    // call web service
    _rpc.Invoke("http://soap.amazon.co.jp/onca/soap?Service=AWSECommerceService",
                "http://soap.amazon.com",
                OnResultSHP_SOAP,
                this);
}

// callback function to be notified of the result of the web service
// error: error value, result: return value of web service, fault: SOAP Fault element, soap : SOAP message, reference: data passed to callback function
Void SOAPTest::OnResultSHP_SOAP(SFCError error, const SFXSOAPRPC::Params& result, const SFXSOAPRPC::FAULT& fault, SFXSOAPParserConstRef soap, VoidPtr reference)
{
    static_cast<SOAPTestPtr>(reference)->OnResult_SOAP(error, result, fault, soap);
}

// Function to process the SOAP message received from web server
Void SOAPTest::OnResult_SOAP(SFCError error, const SFXSOAPRPC::Params& result, const SFXSOAPRPC::FAULT& fault, SFXSOAPParserConstRef soap)
{
    if (error == SFERR_NO_ERROR) {

        // get result of SOAP message(SFXSOAPRPC::Params array) for each parameter

        // get enumerator
        SFXSOAPRPC::Params::Enumerator paramEtor = result.GetFirstEnumerator();

        while (paramEtor.HasNext()) {

            // get each parameter
            SFXSOAPRPC::LPPARAMETER temp = paramEtor.GetNext();

            // display name of parameter
            TRACE("parameter-name: %s", temp->_name.GetCString());
            // display type of parameter
            TRACE("parameter-type: %d", temp->_type);

            if (!temp->_value.IsEmpty()) {
                // display value of parameter
                TRACE("parameter-value: %s", ACharConstPtr(temp->_value.GetBuffer()));
            }
        }
   }
   // display error message(SOAP Fault)
   else if (error == SFERR_SOAP_FAULT_MESSAGE) {

        if(!fault._faultactor.IsEmpty())
            // if faultactor element is not empty, display its content
            TRACE("faultactor: %s", fault._faultactor.GetCString());    

        if(!fault._faultcode.IsEmpty())
            // if faultcode element is not empty, display its content
            TRACE("faultcode: %s", fault._faultcode.GetCString());     

        if(!fault._faultstring.IsEmpty())
            // if faultstring element is not empty, display its content
            TRACE("faultstring: %s", fault._faultstring.GetCString());  

        if (fault._faultdetail) 
             // if detail element is not empty, display its content
            TRACE("faultstring: %s", fault._faultdetail->GetText().GetCString());
    }
    return;
}

Reference

SFXSOAPWriter | SFXSOAPParser | SFXSOAPServiceProxy

Member

Constructor/Destructor
SFXSOAPRPC( Void )
Constructor of SFXSOAPRPC class.
SFXSOAPRPC( SFXAnsiStringConstRef targeturi , SFXAnsiStringConstRef prefix , SFXAnsiStringConstRef method , ParamsConstRef params , SFXAnsiStringConstRef encodingstyle = "NONE" , SFXAnsiStringConstRef port = SFXAnsiString::EmptyInstance() )
Constructor of SFXSOAPRPC class.
~SFXSOAPRPC( Void )
Destructor of SFXSOAPRPC class.
Public Functions
SFCError AddAttribute( SFXAnsiStringConstRef param , SFXAnsiStringConstRef name , SFXAnsiStringConstRef value , PARAMETER::Mode mode = PARAMETER::IN )
Add an attribute to the parameter.
SFCError AddMethodAttribute( SFXAnsiStringConstRef name , SFXAnsiStringConstRef value )
Add a method attribute.
SFCError AddParameter( SFXAnsiStringConstRef name , SFXBufferConstRef value , PARAMETER::Types type = PARAMETER::XSD_STRING , PARAMETER::Mode mode = PARAMETER::IN )
Add a parameter.
Void Cancel( Void )
Cancel the SOAP-RPC communication.
ACharConstPtr GetEncodingStyle( Void )
Get the SOAP encoding.
ACharConstPtr GetMethodName( Void )
Get the method name of Web Service.
ParamsConstPtr GetParams( Void )
Get the list of parameters.
const LPPARAMETER GetResultValueByName( SFXAnsiStringConstRef name )
Get the return value of a specified parameter.
ParamsConstPtr GetResultValues( Void )
Get the list of the output parameters.
ACharConstPtr GetTargetObjectURI( Void )
Get target URI.
UInt32 GetTrustMode( Void )
Get the SSL trust mode.
SFCError Invoke( SFXAnsiStringConstRef url , SFXAnsiStringConstRef SOAPActionURI , NotifySPP spp = null , VoidPtr reference = null )
Invoke( SFXAnsiStringConstRef url , SFXAnsiStringConstRef SOAPActionURI , SFXAnsiStringConstRef input , NotifySPP spp = null , VoidPtr reference = null )
Call the Web Service method.
Bool IsConnecting( Void )
Check whether or not to be connected to the server.
Void RemoveAllParams( Void )
Remove all the parameters of the web service.
Void Reset( Void )
Reset all the internal variables.
Void SetEncodingStyle( SFXAnsiStringConstRef encodingstyle )
Set the SOAP encoding.
SFXXMLElementPtr SetHeader( SFXAnsiStringConstRef encodingstyle = "NONE" )
Set the Header element of the SOAP-RPC message.
Void SetMethodName( SFXAnsiStringConstRef method )
Set the method name of the web service.
Void SetNotifyHandler( NotifySPP spp , VoidPtr reference )
Set the callback function to get the return value.
SFCError SetParams( ParamsConstRef params )
Set the parameters.
Void SetTargetObjectURI( SFXAnsiStringConstRef targeturi , SFXAnsiStringConstRef prefix = SFXAnsiString::EmptyInstance() )
Set the target URI.
Void SetTrustMode( UInt32 param )
Set the SSL trust mode.
Types
FAULT
Data structure for the SOAP Fault.
LPFAULT
Pointer type of SFXSOAPRPC::FAULT.
LPPARAMETER
Pointer type of SFXSOAPRPC::PARAMETER.
NotifySPP
Prototype of the callback function.
PARAMETER
Data structure for the parameter.

SFXSOAPRPC::SFXSOAPRPC
Constructor of SFXSOAPRPC class.
[ public, explicit ]
SFXSOAPRPC(Void);
[ public, explicit ]
SFXSOAPRPC(
    SFXAnsiStringConstRef targeturi                               // target URI
    SFXAnsiStringConstRef prefix                                  // namespace prefix of target URI
    SFXAnsiStringConstRef method                                  // target method
    ParamsConstRef params                                         // parameters
    SFXAnsiStringConstRef encodingstyle = "NONE"                  // SOAP encoding
    SFXAnsiStringConstRef port = SFXAnsiString::EmptyInstance()   // port of web service
);

Description

The following variables are defined in the params argument.

Variable Description
_type type of parameter
_mode I/O mode of parameter
_name name of parameter
_value value of parameter
_attrlist attribute information of parameter

SFXSOAPRPC::~SFXSOAPRPC
Destructor of SFXSOAPRPC class.
[ public ]
~SFXSOAPRPC(Void);

SFXSOAPRPC::AddAttribute
Add an attribute to the parameter.
[ public ]
SFCError AddAttibute(
    SFXAnsiStringConstRef param            // name of parameter
    SFXAnsiStringConstRef name             // name of attribute
    SFXAnsiStringConstRef value            // value of attribute
    PARAMETER::Mode mode = PARAMETER::IN   // mode of attribute (default: input mode)
);

Return value

  • Success : SFERR_NO_ERROR
  • If insufficient memory : SFERR_NO_MEMORY
  • If failed : SFERR_FAILED

SFXSOAPRPC::AddMethodAttribute
Add a method attribute.
[ public ]
SFCError AddMethodAttribute(
    SFXAnsiStringConstRef name    // name of attribute
    SFXAnsiStringConstRef value   // value of attribute
);

Return value

  • Success : SFERR_NO_ERROR
  • If insufficient memory : SFERR_NO_MEMORY
  • If failed : SFERR_FAILED

SFXSOAPRPC::AddParameter
Add a parameter.
[ public ]
SFCError AddParameter(
    SFXAnsiStringConstRef name                      // name of parameter
    SFXBufferConstRef value                         // value of parameter
    PARAMETER::Types type = PARAMETER::XSD_STRING   // type of parameter(default: string)
    PARAMETER::Mode mode = PARAMETER::IN            // mode of parameter(default: input mode)
);

Return value

  • Success : SFERR_NO_ERROR
  • If insufficient memory : SFERR_NO_MEMORY
  • If failed : SFERR_FAILED

Example

SFXSOAPRPC rpc;

rpc.AddParameter("Index", SFXBuffer(SFXAnsiString("1")), 
                 SFXSOAPRPC::PARAMETER::SOAP_INT, SFXSOAPRPC::PARAMETER::IN );

Reference

SFXSOAPRPC::PARAMETER


SFXSOAPRPC::Cancel
Cancel the SOAP-RPC communication.
[ public ]
Void Cancel(Void);

SFXSOAPRPC::GetEncodingStyle
Get the SOAP encoding.
[ public, const ]
ACharConstPtr GetEncodingStyle(Void);

Description

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.

[Note] About SOAP Encoding

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


SFXSOAPRPC::GetMethodName
Get the method name of Web Service.
[ public, const ]
ACharConstPtr GetMethodName(Void);

SFXSOAPRPC::GetParams
Get the list of parameters.
[ public, const ]
ParamsConstPtr GetParams(Void);

Return value

Return the pointer to the SFXSOAPRPC::LPPARAMETER structure.

Description

Get the SFXSOAPRPC::PARAMETER structure.

[Note] Note
SFXSOAPRPC::LPPARAMETER is the type of pointer to the SFXSOAPRPC::PARAMETER structure.

Example

SFXSOAPRPC _rpc;    // variable for processing SOAP-RPC protocol
    
SFXSOAPRPC::ParamsConstPtr lp;
lp = _rpc.GetParams();          // get list of parameters
SFXSOAPRPC::LPPARAMETER item;
item = lp->Get(0);           // get first element

TRACE("%s",item->_name.GetCString());  // display type of parameter
TRACE("%s",item->_value.GetBuffer());  // display value of parameter

Reference

SFXSOAPRPC::LPPARAMETER | SFXSOAPRPC::PARAMETER


SFXSOAPRPC::GetResultValueByName
Get the return value of a specified parameter.
[ public, const ]
const LPPARAMETER GetResultValueByName(
    SFXAnsiStringConstRef name   
);

SFXSOAPRPC::GetResultValues
Get the list of the output parameters.
[ public, const ]
ParamsConstPtr GetResultValues(Void);

Return value

Return the pointer to the SFXSOAPRPC::LPPARAMETER structure.

Description

Get the SFXSOAPRPC::PARAMETER structure.

[Note] Note
SFXSOAPRPC::LPPARAMETER is the type of pointer to the SFXSOAPRPC::PARAMETER structure.

Example

SFXSOAPRPC _rpc;    // variable for processing SOAP-RPC protocol

SFXSOAPRPC::ParamsConstPtr lp;
lp = _rpc.GetResultValues();    // get list of output parameters
SFXSOAPRPC::LPPARAMETER item;
item = lp->Get(0);           // get first element

TRACE("%s",item->_name.GetCString());   // display type of parameter
TRACE("%s",item->_value.GetBuffer());   // display value of parameter

Reference

SFXSOAPRPC::LPPARAMETER | SFXSOAPRPC::PARAMETER


SFXSOAPRPC::GetTargetObjectURI
Get target URI.
[ public, const ]
ACharConstPtr GetTargetObjectURI(Void);

SFXSOAPRPC::GetTrustMode
Get the SSL trust mode.
[ public, const ]
UInt32 GetTrustMode(Void);

Description

The SSL trust mode can be one of the following values.

  • SSL_TRUST_MODE_FAIL
  • SSL_TRUST_MODE_CHECK
  • SSL_TRUST_MODE_IGNORE
  • SSL_TRUST_MODE_ALWAYS
[Note] Note
Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXHTTPConnection::GetTrustMode


SFXSOAPRPC::Invoke
Call the Web Service method.
[ public ]
SFCError Invoke(
    SFXAnsiStringConstRef url             // Web Service IP address
    SFXAnsiStringConstRef SOAPActionURI   // SoapAction attribute value
    NotifySPP spp = null                  // callback function
    VoidPtr reference = null              // data passed to the callback function
);
[ public ]
SFCError Invoke(
    SFXAnsiStringConstRef url             // Web Service IP address
    SFXAnsiStringConstRef SOAPActionURI   // SoapAction attribute value
    SFXAnsiStringConstRef input           // SOAP message
    NotifySPP spp = null                  // callback function
    VoidPtr reference = null              // data passed to the callback function
);

Return value

  • Success : SFERR_NO_ERROR
  • If Envelope element is not found : SFERR_SOAP_EXPECT_ENVELOPE( 0x699F )
  • If Envelope element is duplicated : SFERR_SOAP_REPEATED_ENVELOPE( 0x69A2 )
  • If Body element is not found : SFERR_SOAP_EXPECT_BODY( 0x69A0 )
  • If argument is invalid : SFERR_INVALID_PARAM
  • If insufficent memory : SFERR_NO_MEMORY
  • If failed : SFERR_FAILED

SFXSOAPRPC::IsConnecting
Check whether or not to be connected to the server.
[ public, const ]
Bool IsConnecting(Void);

Return value

  • If connected : true
  • Otherwise : false

SFXSOAPRPC::RemoveAllParams
Remove all the parameters of the web service.
[ public ]
Void RemoveAllParams(Void);

SFXSOAPRPC::Reset
Reset all the internal variables.
[ public ]
Void Reset(Void);

SFXSOAPRPC::SetEncodingStyle
Set the SOAP encoding.
[ public ]
Void SetEncodingStyle(
    SFXAnsiStringConstRef encodingstyle   // 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

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.

[Note] About SOAP Encording

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


SFXSOAPRPC::SetHeader
Set the Header element of the SOAP-RPC 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 of the SOAP-RPC document. If the Header 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.

[Note] About SOAP Encording

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


SFXSOAPRPC::SetMethodName
Set the method name of the web service.
[ public ]
Void SetMethodName(
    SFXAnsiStringConstRef method   // method name of the web service
);

SFXSOAPRPC::SetNotifyHandler
Set the callback function to get the return value.
[ public ]
Void SetNotifyHandler(
    NotifySPP spp       // callback function
    VoidPtr reference   // data passed to the callback function
);

SFXSOAPRPC::SetParams
Set the parameters.
[ public ]
SFCError SetParams(
    ParamsConstRef params   // parameters
);

Return value

  • Success : SFERR_NO_ERROR
  • If insufficient memory : SFERR_NO_MEMORY
  • If failed : SFERR_FAILED

SFXSOAPRPC::SetTargetObjectURI
Set the target URI.
[ public ]
Void SetTargetObjectURI(
    SFXAnsiStringConstRef targeturi                                 // target URI
    SFXAnsiStringConstRef prefix = SFXAnsiString::EmptyInstance()   // namespace prefix of target URI
);

SFXSOAPRPC::SetTrustMode
Set the SSL trust mode.
[ public ]
Void SetTrustMode(
    UInt32 param   // SSL verification mode
);

Description

One of the following values are available for the SSL trust mode:

  • SSL_TRUST_MODE_FAIL: Default, fail on trust errors.
  • SSL_TRUST_MODE_CHECK: Suspend on trust errors so they can be checked and ignored.
  • SSL_TRUST_MODE_IGNORE: Ignore all trust errors.
  • SSL_TRUST_MODE_ALWAYS: Always suspend so trust can always be checked.
[Note] Note
Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXHTTPConnection::SetTrustMode


SFXSOAPRPC::FAULT
Data structure for the SOAP Fault.
typedef struct SFXSOAPRPC::_Fault SFXSOAPRPC::FAULT

Description

[Note] About SOAP Fault

Simple Object Access Protocol (SOAP) 1.1 ( W3C ) : SOAP Fault

SOAP Tutorial : SOAP Fault Element

* Only SOAP Fault of SOAP 1.1 is supported.

Reference

SFXSOAPParser::GetFault | SFXSOAPParser::GetFaultActor | SFXSOAPParser::GetFaultCode | SFXSOAPParser::GetFaultDetail | SFXSOAPParser::GetFaultString


SFXSOAPRPC::LPFAULT
Pointer type of SFXSOAPRPC::FAULT.
typedef struct SFXSOAPRPC::_Fault * SFXSOAPRPC::LPFAULT

SFXSOAPRPC::LPPARAMETER
Pointer type of SFXSOAPRPC::PARAMETER.
typedef struct SFXSOAPRPC::_Parameter * SFXSOAPRPC::LPPARAMETER

SFXSOAPRPC::NotifySPP
Prototype of the callback function.
typedef Void(* SFXSOAPRPC::NotifySPP)(SFCError error, const Params &result, const FAULT &fault, SFXSOAPParserConstRef soap, VoidPtr reference)

Arguments

error

error value

result

return value

fault

Fault element of the SOAP message

soap

reference to the SOAP message

reference

data passed to the callback function


SFXSOAPRPC::PARAMETER
Data structure for the parameter.
typedef struct SFXSOAPRPC::_Parameter SFXSOAPRPC::PARAMETER

Description

Variable Description
_type type of parameter
_mode Input/Output mode of parameter
_name name of parameter
_value value of parameter(instance of SFXBuffer class)
_attrlist attribute information of parameter

_type values

For definition of XML schema

  • XSD_STRING
  • XSD_FLOAT
  • XSD_BOOLEAN
  • XSD_DOUBLE
  • XSD_INTEGER
  • XSD_INT
  • XSD_LONG
  • XSD_SHORT
  • XSD_DECIMAL
  • XSD_BASE64
  • XSD_HEXBINARY
  • XSD_BYTE
  • XSD_DATETIME
  • XSD_QNAME

For definition of SOAP message

  • SOAP_STRING
  • SOAP_BOOLEAN
  • SOAP_DOUBLE
  • SOAP_BASE64
  • SOAP_FLOAT
  • SOAP_INT
  • SOAP_LONG
  • SOAP_SHORT
  • SOAP_BYTE
  • SOAP_ARRAY
  • UNKNOWN

_mode values

  • IN : input mode
  • INOUT : input/output mode
  • OUT : output mode

_attrlist is the list of parameter attributes. To store the attribute of a parameter, use the SFXSOAPRPC::AddAttribute function.