SFXSOAPServiceProxy

Class which creates a proxy and implements dynamic binding using the WSDL document.

#include <SFXSOAPServiceProxy.hpp>

class SFXSOAPServiceProxy;

SFMTYPEDEFCLASS(SFXSOAPServiceProxy)

Collaboration diagram

Description

	Caution
	This class does not support WSDL 1.1 completely.

SFXSOAPServiceProxy is the class for accessing the Web service using the WSDL document.

	About Web Services Description Language ( WSDL )
	W3C WSDL 1.1 : Web Services Description Language ( WSDL ) 1.1 ( WSDL 1.1 is supported)

Example 839. The method to call the web service using the SFXSOAPServiceProxy class for WSDL

SFXSOAPServiceProxy _wsdl;  // variable for creating proxy and performing dynamic binding using the WSDL document

// set callback function to be notified of having received result from web server
_wsdl.SetNotifyHandler(OnResultSHP, this);

// set WSDL document
if (_wsdl.SetWSDLDocument(SFXPath("weatherbycity2.xml")) == SFERR_NO_ERROR) {

    // set name of web service
    _wsdl.SetServiceName("WeatherByCity");

    // set port name of web service
    _wsdl.SetPortName("WeatherByCitySoap");

    // set method name of web service
    _wsdl.SetMethodName("GetWeatherByCity");

    // set values to parameters of web service 
    // set user properties for web service
    _wsdl.SetParameterValue("UserID", 
                            SFXBuffer(SFXAnsiString("sophia@s-cradle.com")));
    _wsdl.SetParameterValue("Password", 
                            SFXBuffer(SFXAnsiString("*******")));

    // set parameters for web service
    _wsdl.SetParameterValue("CityName", 
                            SFXBuffer(SFXAnsiString("Washington")));
    _wsdl.SetParameterValue("StateAbbreviationORCountryName", 
                            SFXBuffer(SFXAnsiString("PA")));

    // call web service
    _wsdl.Invoke();
}

Reference

SFXSOAPWriter | SFXSOAPParser | SFXSOAPRPC | SFXXMLDOMParser

Member

Constructor/Destructor
SFXSOAPServiceProxy( `Void` ) Constructor of the SFXSOAPServiceProxy class.
SFXSOAPServiceProxy( `SFXAnsiStringConstRef` wsdl ) Constructor of the SFXSOAPServiceProxy class.
SFXSOAPServiceProxy( `SFXAnsiStringConstRef` wsdl , `SFXAnsiStringConstRef` service , `SFXAnsiStringConstRef` port , `SFXAnsiStringConstRef` method ) Constructor of the SFXSOAPServiceProxy class.
~SFXSOAPServiceProxy( `Void` ) Desctructor of SFXSOAPServiceProxy.

Public Functions
`Void`	Cancel( `Void` ) Cancel the SOAP communication.
`ACharConstPtr`	GetMethodName( `Void` ) Get the method name of the web service.
`ACharConstPtr`	GetPortName( `Void` ) Get the port name of the web service.
`const SFXSOAPRPC::LPPARAMETER`	GetResultValueByName( `SFXAnsiStringConstRef` name ) Get the return value of the specified parameter.
`ParamsConstPtr`	GetResultValues( `Void` ) Get the array of the output parameters.
`ACharConstPtr`	GetServiceName( `Void` ) Get the name of the web service.
`UInt32`	GetTrustMode( `Void` ) Get the SSL trust mode
`SFCError`	Invoke( `NotifySPP` spp = null , `VoidPtr` reference = null ) Call the method of the web service.
`Bool`	IsConnecting( `Void` ) Check whether or not to be connected to the server.
`Void`	Reset( `Void` ) Reset all the internal variables.
`SFCError`	SetMethodAttribute( `SFXAnsiStringConstRef` name , `SFXAnsiStringConstRef` value ) Set the attribute to the method of the web service.
`Void`	SetMethodName( `SFXAnsiStringConstRef` method ) Set the method name of the web service .
`Void`	SetNotifyHandler( `SFXSOAPRPC::NotifySPP` spp , `VoidPtr` reference ) Set the callback function to be notified of the return value.
`SFCError`	SetParameterValue( `SFXAnsiStringConstRef` name , `SFXBufferConstRef` value , `SFXPropertyConstRef` attribute = SFXProperty::EmptyInstance() ) Set the content of the parameter and its attributes.
`Void`	SetPortName( `SFXAnsiStringConstRef` port ) Set the port name of the web service.
`Void`	SetServiceName( `SFXAnsiStringConstRef` service ) Set the name of the web service.
`Void`	SetTrustMode( `UInt32` param ) Set the SSL trust mode.
`SFCError`	SetWSDLDocument( `SFXAnsiStringConstRef` wsdl ) Set the WSDL document.
`SFCError`	SetWSDLDocument( `SFXPathConstRef` wsdl ) Set the WSDL document.

SFXSOAPServiceProxy::SFXSOAPServiceProxy

Constructor of the SFXSOAPServiceProxy class.

[ public, explicit ]
SFXSOAPServiceProxy(Void);

[ public, explicit ]
SFXSOAPServiceProxy(
    SFXAnsiStringConstRef wsdl   
);

[ public, explicit ]
SFXSOAPServiceProxy(
    SFXAnsiStringConstRef wsdl      // name of the WSDL document
    SFXAnsiStringConstRef service   // name of web service
    SFXAnsiStringConstRef port      // port name
    SFXAnsiStringConstRef method    // method name
);

SFXSOAPServiceProxy::~SFXSOAPServiceProxy

Desctructor of SFXSOAPServiceProxy.

[ public ]
~SFXSOAPServiceProxy(Void);

SFXSOAPServiceProxy::Cancel

Cancel the SOAP communication.

[ public ]
Void Cancel(Void);

SFXSOAPServiceProxy::GetMethodName

Get the method name of the web service.

[ public, const ]
ACharConstPtr GetMethodName(Void);

SFXSOAPServiceProxy::GetPortName

Get the port name of the web service.

[ public, const ]
ACharConstPtr GetPortName(Void);

SFXSOAPServiceProxy::GetResultValueByName

Get the return value of the specified parameter.

[ public, const ]
const SFXSOAPRPC::LPPARAMETER GetResultValueByName(
    SFXAnsiStringConstRef name   // name of parameter
);

SFXSOAPServiceProxy::GetResultValues

Get the array of the output parameters.

[ public, const ]
ParamsConstPtr GetResultValues(Void);

Return value

Array of the output parameters of the SFXSOAPRPC::LPPARAMETER type(SFXSOAPRPC::Params).

Description

This function gets the array of the output parameters of the SFXSOAPRPC::LPPARAMETER type(SFXSOAPRPC::Params).

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

Example

SFXSOAPServiceProxy _wsdl;    // SFXSOAPServiceProxy object

SFXSOAPRPC::ParamsConstPtr lp;
lp = _wsdl.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

SFXSOAPServiceProxy::GetServiceName

Get the name of the web service.

[ public, const ]
ACharConstPtr GetServiceName(Void);

SFXSOAPServiceProxy::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
	Reference: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXHTTPConnection::GetTrustMode

SFXSOAPServiceProxy::Invoke

Call the method of the web service.

[ public ]
SFCError Invoke(
    NotifySPP spp = null       // callback function(Default: null)
    VoidPtr reference = null   // data passed to the callback function(Default: null)
);

Return value

If succeeds: SFERR_NO_ERROR
If the Envelope element does not exist: SFERR_SOAP_EXPECT_ENVELOPE( 0x699F )
If the Body element does not exist: SFERR_SOAP_EXPECT_BODY( 0x69A0 )
If the Envelope element duplicates: SFERR_SOAP_REPEATED_ENVELOPE( 0x69A2 )
If argument is invalid: SFERR_INVALID_PARAM
If insufficient memory: SFERR_NO_MEMORY
If failed: SFERR_FAILED

The errors on the WSDL document is as follows:

The web service specified does not exist.: SFERR_WSDL_EXPECT_SERVICE( 0x69A6 )
The port of web service specified does not exist.: SFERR_WSDL_EXPECT_PORT( 0x69A7 )
Cannot bind the port of the web service specified.: SFERR_WSDL_EXPECT_BINDING( 0x69A8 )
The method of web service specified does not exist.: SFERR_WSDL_EXPECT_OPERATION( 0x69A9 )
There is no port type to be expected.: SFERR_WSDL_EXPECT_PORTTYPE( 0x69AA )
There is no message to be expected.: SFERR_WSDL_EXPECT_MESSAGE( 0x69AB )

Reference: SFCErrorEnum

Reference

SFXSOAPServiceProxy::IsConnecting

Check whether or not to be connected to the server.

[ public, const ]
Bool IsConnecting(Void);

Return value

If connected: true
Otherwise: false

SFXSOAPServiceProxy::Reset

Reset all the internal variables.

[ public ]
Void Reset(Void);

SFXSOAPServiceProxy::SetMethodAttribute

Set the attribute to the method of the web service.

[ public ]
SFCError SetMethodAttribute(
    SFXAnsiStringConstRef name    // name of attribute
    SFXAnsiStringConstRef value   // value of attribute
);

SFXSOAPServiceProxy::SetMethodName

Set the method name of the web service .

[ public ]
Void SetMethodName(
    SFXAnsiStringConstRef method   // method name
);

SFXSOAPServiceProxy::SetNotifyHandler

Set the callback function to be notified of the return value.

[ public ]
Void SetNotifyHandler(
    SFXSOAPRPC::NotifySPP spp   // callback function
    VoidPtr reference           // data passed to callback function
);

SFXSOAPServiceProxy::SetParameterValue

Set the content of the parameter and its attributes.

[ public ]
SFCError SetParameterValue(
    SFXAnsiStringConstRef name                                     // name of parameter
    SFXBufferConstRef value                                        // value of parameter
    SFXPropertyConstRef attribute = SFXProperty::EmptyInstance()   // attributes(pairs of an attribute name and its value)
);

SFXSOAPServiceProxy::SetPortName

Set the port name of the web service.

[ public ]
Void SetPortName(
    SFXAnsiStringConstRef port   // port name
);

SFXSOAPServiceProxy::SetServiceName

Set the name of the web service.

[ public ]
Void SetServiceName(
    SFXAnsiStringConstRef service   // name of the web service
);

SFXSOAPServiceProxy::SetTrustMode

Set the SSL trust mode.

[ public ]
Void SetTrustMode(
    UInt32 param   // SSL trust 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
	Reference: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXHTTPConnection::SetTrustMode

SFXSOAPServiceProxy::SetWSDLDocument

Set the WSDL document.

[ public ]
SFCError SetWSDLDocument(
    SFXAnsiStringConstRef wsdl   // WSDL document
);

[ public ]
SFCError SetWSDLDocument(
    SFXPathConstRef wsdl   // file path
);

Return value

If succeeds: SFERR_NO_ERROR
If file path is invalid or argument is null: SFERR_INVALID_PARAM
If the WSDL document has already been opened: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY
If failed: SFERR_FAILED

The error codes that may occur when parsing a SOAP document are as follows:

There is no Body element: SFERR_SOAP_EXPECT_BODY( 0x69A0 )
There is invalid element: SFERR_SOAP_REDUNDANT_ELEMENT( 0x69A3 )
Error found in the version: SFERR_XML_BAD_VERSION( 0x6901 )
Error found in the encoding: SFERR_XML_BAD_ENCODING( 0x6902 )
Error found in the standalone attribute: SFERR_XML_BAD_STANDALONE( 0x6903 )
Error found in the string such as "", "<[[", "]]>": SFERR_XML_BAD_SEQUENCE( 0x6904 )
Error found in the attribute's default type: SFERR_XML_BAD_ATTRDEFTYPE( 0x6905 )
Error found in the attribute type: SFERR_XML_BAD_ATTRTYPE( 0x6907 )
There is no "=" mark: SFERR_XML_EXPECT_EQUALSIGN( 0x6908 )
There is no attribute name: SFERR_XML_EXPECT_ATTRNAME( 0x690A )
XML declaration is not completed: SFERR_XML_EXPECT_DECLSTRING( 0x690C )
There is no element name: SFERR_XML_EXPECT_ELEMENTNAME( 0x690D )
There is no name in Processing Instruction (PI): SFERR_XML_EXPECT_PINAME( 0x690E )
There is no white space: SFERR_XML_EXPECT_WHITESPACE( 0x690F )
There is no end tag: SFERR_XML_EXPECT_ENDTAG( 0x6912 )
There is no quoted string in the XML declaration: SFERR_XML_EXPECT_QUOTEDSTRING( 0x691D )
The version is not specified by the XML declaration: SFERR_XML_EXPECT_XMLVERSION( 0x691E )
The encoding is not specified by the XML declaration: SFERR_XML_EXPECT_ENCODING( 0x691F )
The tag of the same layer not terminated: SFERR_XML_UNTERMINATED_STARTTAG( 0x692D )
The processing instruction (PI) not terminated: SFERR_XML_UNTERMINATED_PI( 0x692E )
The comment not terminated: SFERR_XML_UNTERMINATED_COMMENT( 0x692F )
The XML declaration not terminated: SFERR_XML_UNTERMINATED_XMLDECL( 0x6933 )
The Entity reference not terminated: SFERR_XML_UNTERMINATED_ENTITYREF( 0x6934 )
The CDATA section document not terminated: SFERR_XML_UNTERMINATED_CDATA( 0x6935 )
The version other than XML 1.0/ 1.1: SFERR_XML_UNSUPPORT_XMLVERSION( 0x6936 )
There is no character in the valid range: SFERR_XML_INVALID_CHARREF( 0x6938 )
Error found in the attribute value: SFERR_XML_INVALID_ATTRVALUE( 0x6939 )
Error found in the element name: SFERR_XML_INVALID_ELEMENTNAME( 0x693A )
Error found in the Entity reference name: SFERR_XML_INVALID_ENTITYREFNAME( 0x693B )
Error found in the element: SFERR_XML_INVALID_ELEMENT( 0x693C )
Error found in the xml:space attribute: SFERR_XML_INVALID_XMLSPACE( 0x693F )
The prefix definition is not found: SFERR_XML_UNKNOWN_PREFIX( 0x696B )
Error found in the standalone attribute: SFERR_XML_INVALID_INSTANDALONE( 0x6941 )
The prefix definition is not found: SFERR_XML_UNKNOWN_PREFIX( 0x696B )
Extra ">" tag found: SFERR_XML_MORE_ENDTAG( 0x6971 )
The tag is not symmetry: SFERR_XML_TAGSTACK_NOTEMPTY( 0x698C )
The processing instruction (PI) is not before "xml": SFERR_XML_PI_START_NO_WITHXML( 0x698D )
Error found in the root defined by DOCTYPE: SFERR_XML_ROOTELEM_NOTLIKE_DOCTYPE( 0x698E )
The required attribute has not been set yet: SFERR_XML_ATTR_NOTPROVIDED( 0x698F )
The Standalone attribute is not default setting: SFERR_XML_NODEFAULT_ATTR_FORSTANDALONE( 0x6990 )
Error found found in the EOF: SFERR_XML_UNEXPECTED_EOF( 0x6995 )
In the XML document with namespace, if extra xmlns found in the element's prefix: SFERR_XML_REDUNDANT_XMLNS_PREFIX( 0x6997 )

Reference: SFCErrorEnum

Reference

SFCErrorEnum