You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by pr...@apache.org on 2006/04/19 17:14:44 UTC
svn commit: r395262 - /webservices/axis/trunk/c/include/axis/client/Call.hpp
Author: prestonf
Date: Wed Apr 19 08:14:25 2006
New Revision: 395262
URL: http://svn.apache.org/viewcvs?rev=395262&view=rev
Log:
Modified doxygen information within header so that class was properly documented.
Modified:
webservices/axis/trunk/c/include/axis/client/Call.hpp
Modified: webservices/axis/trunk/c/include/axis/client/Call.hpp
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/c/include/axis/client/Call.hpp?rev=395262&r1=395261&r2=395262&view=diff
==============================================================================
--- webservices/axis/trunk/c/include/axis/client/Call.hpp (original)
+++ webservices/axis/trunk/c/include/axis/client/Call.hpp Wed Apr 19 08:14:25 2006
@@ -27,7 +27,6 @@
* @author Sanjaya Singharage (sanjayas@opensource.lk)
* @author Samisa Abeysinghe (sabeysinghe@virtusa.com)
*/
-
#if !defined(_CALL_H____OF_AXIS_INCLUDED_)
#define _CALL_H____OF_AXIS_INCLUDED_
@@ -49,32 +48,175 @@
class ISoapAttachment;
class ContentIdSet;
+/**
+ * @class Call
+ *
+ * @brief This file Contains the Call class and equivalent C function tables
+ * that all web service stubs generated by WSDL2Ws tool use to talk
+ * to Axis Engine.
+ *
+ * @author Susantha Kumara (susantha@opensource.lk, skumara@virtusa.com)
+ * @author Sanjaya Singharage (sanjayas@opensource.lk)
+ * @author Samisa Abeysinghe (sabeysinghe@virtusa.com)
+ */
+
/* A separate call class object should be used by each thread */
class STORAGE_CLASS_INFO Call
{
public:
Call();
virtual ~Call();
- void AXISCALL setSOAPVersion(SOAP_VERSION version);
- int AXISCALL setTransportProperty(AXIS_TRANSPORT_INFORMATION_TYPE type,
- const char* value);
- const char* AXISCALL getTransportProperty(const char *key, bool response=true);
- int AXISCALL setHandlerProperty(AxisChar* name, void* value, int len);
+ /**
+ * Set the expected SOAP version. The currently supported SOAP versions
+ * are 1.1 and 1.2.
+ *
+ * @param version is an enumerated type. SOAP_VERSION is defined in
+ * SoapEnvVersions.hpp and currently has the following values;- SOAP_VER_1_1
+ * and SOAP_VER_1_2.
+ */
+ void AXISCALL setSOAPVersion( SOAP_VERSION version);
+
+ /**
+ * Set a property in the transport layer.
+ *
+ * @param type is an enumerated type. AXIS_TRANSPORT_INFORMATION_TYPE is
+ * defined in GDefine.hpp and currently has the following values;- @n
+ * SOAPACTION_HEADER, SERVICE_URI, OPERATION_NAME, SOAP_MESSAGE_LENGTH,
+ * TRANSPORT_PROPERTIES, SECURE_PROPERTIES, DLL_NAME, CHANNEL_HTTP_SSL_DLL_NAME (same as DLL_NAME),
+ * CHANNEL_HTTP_DLL_NAME and CONTENT_TYPE.
+ * @param value points to a null terminated string that contains the new
+ * transport property value.
+ * @return The return value is either AXIS_SUCCESS or AXIS_FAIL.
+ * @note This method can also throw the following exception;- AxisGenException
+ */
+ int AXISCALL setTransportProperty( AXIS_TRANSPORT_INFORMATION_TYPE type,
+ const char * value);
+
+ /**
+ * Get a property from either the request or response HTTP Header.
+ *
+ * @param key is a null terminated character string. The 'key' is the name
+ * of the HTTP header information element that is to be found. For example,
+ * the HTTP header may look something like this;- @n
+ * POST /axis/AxisBench HTTP/1.1 @n
+ * Host: 127.0.0.1:12345 @n
+ * Content-Type: text/xml; charset=UTF-8 @n
+ * SOAPAction: "" @n
+ * Content-Length: 83779 @n
+ * Then if 'key' was "Host", the returned null terminated character string would
+ * be "127.0.0.1:12345".
+ *
+ * @param response is a boolean. If 'response' is set to TRUE, then the
+ * response HTTP header is used, else the request HTTP header will be used.
+ * The default is TRUE, which implies that the response HTTP header will be used.
+ * @return is a null terminated character string containing the associated
+ * 'key' value. If the key was not found, then the return value will be NULL.
+ */
+ const char * AXISCALL getTransportProperty( const char * key,
+ bool response = true);
+
+ /**
+ * Set a handler property. This adds a new property to a list of properties
+ * that a handler can access when it is invoked.
+ *
+ * @param name is a null terminated character string containing the name of
+ * the handler property.
+ * @param value is a pointer to an untyped object.
+ * @param len is an integer value that is the length of the object passed in
+ * the 'value' parameter.
+ * @return Always AXIS_SUCCESS.
+ * @note The method does not check if the name already exists in the list of
+ * handler properties and so it is possible to have more than one object with
+ * the same name in the list. The user is advised to ensure that all names
+ * are unique.
+ */
+ int AXISCALL setHandlerProperty( AxisChar * name,
+ void * value,
+ int len);
+
/**
* set the protocol that the underlying transport will use.
- * If there is not transport set then the transport protocol is stored locally until there is a transport.
+ * If there is not transport set then the transport protocol is stored locally
+ * until there is a transport.
*
- * @param protocol the protocol that you want. Allowed values are defined in GDefine.hpp AXIS_PROTOCOL_TYPE
- * @return AXIS_SUCCESS if the protocol was set correctly in the underlying transport or, if there is no transport then the value was stored safely.
+ * @param protocol the protocol that you want. Allowed values are defined in
+ * GDefine.hpp AXIS_PROTOCOL_TYPE
+ * @return AXIS_SUCCESS if the protocol was set correctly in the underlying
+ * transport or, if there is no transport then the value was stored safely.
*/
- int AXISCALL setProtocol(AXIS_PROTOCOL_TYPE protocol);
+ int AXISCALL setProtocol( AXIS_PROTOCOL_TYPE protocol);
+
/**
* Get the protocol that the transport is or will use.
+ *
* @return the transport protocol being used.
*/
AXIS_PROTOCOL_TYPE AXISCALL getProtocol();
+
+ /**
+ * At the end of every web service (request/reply SOAP message pair) call,
+ * the deserialiser needs to be uninitialised. If there was a "sessionid" in
+ * the message data, then replace the existing session id with the one from the
+ * message. If there was no new session id, then delete the existing one. An
+ * example of it use can be found in any generated stub or in this code snippet
+ * below:- @n
+ * try @n
+ * { @n
+ * if( AXIS_SUCCESS != m_pCall->initialize( CPP_DOC_PROVIDER)) return pReturn; @n
+ * if( NULL == m_pCall->getTransportProperty( "SOAPAction", false)) @n
+ * { @n
+ * m_pCall->setTransportProperty( SOAPACTION_HEADER , ""); @n
+ * } @n
+ * m_pCall->setSOAPVersion( SOAP_VER_1_1); @n
+ * m_pCall->setOperation( "doBenchRequest", "http://axisbench.test.apache.org"); @n
+ * includeSecure(); @n
+ * applyUserPreferences(); @n
+ * : @n
+ * if( AXIS_SUCCESS == m_pCall->invoke()) @n
+ * { @n
+ * : @n
+ * } @n
+ * <B> m_pCall->unInitialize(); </B>@n
+ * }
+ *
+ * @return Always AXIS_SUCCESS.
+ */
int AXISCALL unInitialize();
- int AXISCALL initialize(PROVIDERTYPE nStyle);
+
+ /**
+ * Populate the message data object by doing the following;- @n
+ * Move the handler data previously added using the setHandlerProperty method. @n
+ * Add the serialiser and deserialiser entry points. @n
+ * Set the serialiser and deserialiser provider type (as defined by nStyle). @n
+ * Reset and initialise the serialiser and deserialiser engines. @n
+ * Set the serialiser and deserialiser encoder/decoder styles to RPC or DOC @n
+ * Set the sessionid property. @n
+ * Move the attachments data. @n
+ *
+ * @param nStyle Set the serialiser and deserialiser provider type. PROVIDERTYPE
+ * is an enumerated type and is defined in WSDDDefines.hpp. The current values
+ * are:- @n
+ * C_RPC_PROVIDER @n
+ * C_DOC_PROVIDER @n
+ * CPP_RPC_PROVIDER @n
+ * CPP_DOC_PROVIDER @n
+ * COM_PROVIDER (not implemented)@n
+ * @return If the initialisation is successful, then AXIS_SUCCESS is returned,
+ * otherwise AXIS_FAIL is returned.
+ * @note This method may thrown an exception.
+ */
+ int AXISCALL initialize( PROVIDERTYPE nStyle);
+
+ /**
+ * This is the main entry point into the Axis engine. Calling this method
+ * will begin the sequence that serialises the message, invokes that request
+ * handlers, transmits the request message and then wait for the response
+ * message, calls the response handlers and then deserialises the response
+ * message.
+ * @return If the invocation is successful, then AXIS_SUCCESS is returned,
+ * otherwise AXIS_FAIL is returned.
+ * @note This method may thrown an exception.
+ */
int AXISCALL invoke();
/**