| /* |
| * Copyright 2003-2004 The Apache Software Foundation. |
| // (c) Copyright IBM Corp. 2004, 2005 All Rights Reserved |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| * |
| */ |
| |
| /** |
| * @file Stub.hpp |
| * |
| * Contains the Stub base class that all C++ web service stubs inherit |
| * from. The functions in this Stub base class provides the client |
| * application some added functionality to manipulate the SOAP messages. |
| */ |
| |
| #if !defined(_STUB_H____OF_AXIS_INCLUDED_) |
| #define _STUB_H____OF_AXIS_INCLUDED_ |
| |
| #include <stdarg.h> |
| |
| #include <axis/client/Call.hpp> |
| |
| #include <vector> |
| |
| using namespace std; |
| |
| |
| /** |
| * @class Stub |
| * |
| * @brief This is the client Stub base class to be inherited by all stub |
| * classes generated by WSDL2WS tool. This class acts as the interface |
| * between the users and the Axis C++ engine (client side). Programmer |
| * can use the API defined here to enrich the client application |
| * functionality. Setting transport properties, setting SOAP headers, |
| * setting connection timeout and specifying a proxy on the client stub |
| * is facilitated with this interface. |
| * |
| */ |
| |
| AXIS_CPP_NAMESPACE_START |
| |
| class IAttribute; |
| |
| class STORAGE_CLASS_INFO Stub |
| { |
| public: |
| |
| /** |
| * Constructor. |
| * |
| * @param pcEndPointURI End point URI of the service to connect to. |
| * e.g. http://localhost:8080/axis/services/echo |
| * @param eProtocol The protocol that this stub should use to communicate |
| * with the endpoint. See AXIS_PROTOCOL_TYPE in GDefine.h for |
| * possible values for eProtocol. |
| */ |
| Stub(const char *pcEndPointURI, |
| AXIS_PROTOCOL_TYPE eProtocol); |
| |
| /** |
| * Destructor. |
| */ |
| virtual ~Stub(); |
| |
| /** |
| * Set end point of service to connect to. |
| * |
| * @param pcEndPointURI End point URI of the service to connect to. |
| * e.g. http://localhost:8080/axis/services/echo |
| */ |
| |
| void AXISCALL setEndPoint(const char *pcEndPointURI); |
| |
| /** |
| * Set transport property. |
| * |
| * Handling the semantics of the headers is up to the user. |
| * The user has to make sure that the key:value paires passed to this method |
| * would make sense at transport level. |
| * The Stub class does not validate the key value paires to see if the properties |
| * make sense to the undelying transport. |
| * |
| * Some example transport properties: |
| * <BR> For HTTP: "Accept-Language: da, en-gb;q=0.8, en;q=0.7" |
| * <BR> For HTTP: "Cookie: sessiontoken=123345456;" |
| * <BR> For SMTP: "Reply-To: user@apache.org" |
| * |
| * @param pcKey Header name e.g. "Accept-Language". |
| * Note that the key is not tested for uniqueness. |
| * One can set several values to the same key and they all will |
| * appear in the outgoing transport header. |
| * e.g. If the method is called twise with (k,v1) and (k,v2) |
| * both k:v1 and k:v2 will appear in transport header as |
| * seperate properties. |
| * The exception to this is "Cookie" where multiple cookie values will only result in one "Cookie:" header being sent as is correct for HTTP. |
| * @param pcValue Header value e.g. "da, en-gb;q=0.8, en;q=0.7" |
| */ |
| void AXISCALL setTransportProperty(const char *pcKey, |
| const char *pcValue); |
| |
| /** |
| * Get a transport property. |
| * |
| * Returns the value of a transport property based on a key. |
| * |
| * @param key the property's name to search for |
| * @param response set to true searches the response message for the property |
| * set to false searches the send message for the property |
| * @return the value of the property or NULL if it was not found. |
| */ |
| const char* AXISCALL getTransportProperty(const char *key, |
| bool response=true); |
| |
| /** |
| * Iterator initiatior for transport property keys |
| * |
| * This method must be called first to initiate access to the list of |
| * transport property keys. If you initialise e.g. response then ensure |
| * that you call this method for outgoing message too if you want the |
| * outgoing message in future calls. |
| * |
| * |
| * @param response whether the response or outgoing message is being used. |
| * @return First transport property key. If there are no transport |
| * properties set, returns NULL. |
| */ |
| const char* getFirstTransportPropertyKey(bool response=true); |
| |
| |
| /** |
| * Iterator for transport property keys |
| * |
| * getFirstTransportPropertyKey() method must have been called at least once |
| * before this method is called. If not behaviour is undefined. |
| * |
| * This method advances the iterator by one position. |
| * Repeated calls always retuen the next value. |
| * |
| * @param response whether the response or outgoing message should be used |
| * @return Next transport property key. If there are no transport |
| * properties set or if iterator is at the end of the list, returns NULL. |
| */ |
| const char* getNextTransportPropertyKey(bool response=true); |
| |
| /** |
| * Accessor for transport property keys. |
| * |
| * This method gives access to the key corresponding to the transport key |
| * currently being pointed by transport property key iterator. |
| * |
| * getFirstTransportPropertyKey() method must have been called at least once |
| * before this method is called. If not behaviour is undefined. |
| * |
| * This method does not advance the iterator. |
| * Repeated calls always retuen the same key unless |
| * getNextTransportPropertyKey() is called in between. |
| * |
| * @param response whether the response or outgoing message is being used. |
| * @return Current transport property key. If there are no transport |
| * properties set or if iterator is at the end of the list, returns NULL. |
| */ |
| const char* getCurrentTransportPropertyKey(bool response=true); |
| |
| /** |
| * Accessor for transport property values. |
| * |
| * This method gives access to the value corresponding to the transport key |
| * currently being pointed by transport property key iterator. |
| * As keys and values are treated as pairs, access to the value field is |
| * based on the access to the key field. |
| * |
| * getFirstTransportPropertyKey() method must have been called at least once |
| * before this method is called. It must be called with the same "response" |
| * value as used here. If not behaviour is undefined. |
| * |
| * This method does not advance the iterator. |
| * Repeated calls always retuen the same value unless |
| * getNextTransportPropertyKey() is called in between. |
| * |
| * @param response whether the response or outgoing message should be used |
| * @return Current transport property value. If there are no transport |
| * properties set or if iterator is at the end of the list, returns NULL. |
| */ |
| const char* getCurrentTransportPropertyValue(bool response=true); |
| |
| /** |
| * Deletes the transport property key:value pair currently pointed to by |
| * the iterator. |
| * @param response true if it's the response property or false for the request |
| */ |
| void deleteCurrentTransportProperty(bool response=true); |
| |
| /** |
| * Deletes the given occurance of the transport property key:value pair |
| * corresponding to the given key. |
| * |
| * This method does not advance the iterator in line with the deletes done. |
| * In case you want to access the transport properties after using this |
| * method, it is advisable to reinitialize the iterator using |
| * getFirstTransportPropertyKey(); |
| * However you can use this method despite where the iterator is |
| * pointing currently. |
| * |
| * NOTE: This method is used to delete individual cookies e.g. deleteTransportProperty("myCookie") will delete the cookie "myCookie" only. |
| * This method can also be used to delete all Cookies by doing deleteTransportProperty("Cookie"). |
| * |
| * @param pcKey Key of the transport property key:value pair to be deleted |
| * If the given key is not set currently, nothing will happen. |
| * @param uiOccurance Which occerance of the key to be deleted, because |
| * there can be multiple values for the same key. |
| * Default is to delete the first occurance. |
| * Count starts from 1. |
| */ |
| void deleteTransportProperty(char* pcKey, |
| unsigned int uiOccurance = 1); |
| |
| |
| /** |
| * Sets a property that can be accessed from a handler. |
| * |
| * @param name The name of the property |
| * @param value The value of the property |
| * @param len The length of the value |
| */ |
| void setHandlerProperty(AxisChar* name, |
| void* value, |
| int len); |
| |
| /** |
| * Create and add a SOAP header block to the Stub. |
| * |
| * This will create a header block that would look like the following when |
| * serialized: |
| * \verbatim |
| <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/"> |
| </th:TestHeader> |
| \endverbatim |
| * |
| * User must use the IHeaderBlock pointer returned and fill in the header structure. |
| * e.g. To make the SOAP header look like |
| * \verbatim |
| <SOAP-ENV:Header> |
| <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/"> |
| <Credentials> |
| <username>Test User</username> |
| <password>Test Password</password> |
| </Credentials> |
| </th:TestHeader> |
| </SOAP-ENV:Header> |
| \endverbatim |
| * the following code segment could be used |
| * <code> |
| * |
| * IHeaderBlock *phb = ws.createSOAPHeaderBlock("TestHeader", |
| * "http://ws.apache.org/axisCppTest/"); |
| * |
| * //Note: The prefix will be added automaticaly. |
| * |
| * //create parent node |
| * |
| * BasicNode *parentNode = phb->createChild(ELEMENT_NODE); |
| * |
| * parentNode->setLocalName("Credentials"); |
| * |
| * |
| * //create child node |
| * |
| * BasicNode *childNode = phb->createChild(ELEMENT_NODE); |
| * |
| * childNode->setLocalName("username"); |
| * |
| * |
| * //create char node for value |
| * |
| * BasicNode *valueNode = phb->createChild(CHARACTER_NODE); |
| * |
| * valueNode->setValue("Test User"); |
| * |
| * |
| * //buld node tree |
| * |
| * childNode->addChild(valueNode); |
| * |
| * parentNode->addChild(childNode); |
| * |
| * |
| * //add another node set |
| * |
| * childNode = phb->createChild(ELEMENT_NODE); |
| * |
| * childNode->setLocalName("password"); |
| * |
| * valueNode = phb->createChild(CHARACTER_NODE); |
| * |
| * valueNode->setValue("Test Password"); |
| * |
| * childNode->addChild(valueNode); |
| * |
| * parentNode->addChild(childNode); |
| * |
| * phb->addChild(parentNode); |
| * </code> |
| * |
| * @param pachLocalName Local tag name of the SOAP header. e.g. TestHeader |
| * @param pachUri Namespace URI to be used in SOAP header. |
| * e.g http://ws.apache.org/axisCppTestHeader/ |
| * |
| * @return Pointer to the creater SOAP header block. |
| */ |
| IHeaderBlock * AXISCALL createSOAPHeaderBlock(AxisChar * pachLocalName, |
| AxisChar * pachUri); |
| |
| /** |
| * Create and add a SOAP header block to the Stub. |
| * |
| * This will create a header block that would look like the following when |
| * serialized: |
| * \verbatim |
| <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/"> |
| </th:TestHeader> |
| \endverbatim |
| * |
| * User must use the IHeaderBlock pointer returned and fill in the header structure. |
| * e.g. To make the SOAP header look like |
| * \verbatim |
| <SOAP-ENV:Header> |
| <th:TestHeader xmlns:th="http://ws.apache.org/axisCppTest/"> |
| <Credentials> |
| <username>Test User</username> |
| <password>Test Password</password> |
| </Credentials> |
| </th:TestHeader> |
| </SOAP-ENV:Header> |
| \endverbatim |
| * the following code segment could be used |
| * <code> |
| * |
| * IHeaderBlock *phb = ws.createSOAPHeaderBlock("TestHeader", |
| * "http://ws.apache.org/axisCppTest/", |
| * "th"); |
| * |
| * |
| * //create parent node |
| * |
| * BasicNode *parentNode = phb->createChild(ELEMENT_NODE); |
| * |
| * parentNode->setLocalName("Credentials"); |
| * |
| * |
| * //create child node |
| * |
| * BasicNode *childNode = phb->createChild(ELEMENT_NODE); |
| * |
| * childNode->setLocalName("username"); |
| * |
| * |
| * //create char node for value |
| * |
| * BasicNode *valueNode = phb->createChild(CHARACTER_NODE); |
| * |
| * valueNode->setValue("Test User"); |
| * |
| * |
| * //buld node tree |
| * |
| * childNode->addChild(valueNode); |
| * |
| * parentNode->addChild(childNode); |
| * |
| * |
| * //add another node set |
| * |
| * childNode = phb->createChild(ELEMENT_NODE); |
| * |
| * childNode->setLocalName("password"); |
| * |
| * |
| * valueNode = phb->createChild(CHARACTER_NODE); |
| * |
| * valueNode->setValue("Test Password"); |
| * |
| * |
| * childNode->addChild(valueNode); |
| * |
| * parentNode->addChild(childNode); |
| * |
| * |
| * phb->addChild(parentNode); |
| * </code> |
| * |
| * @param pachLocalName Local tag name of the SOAP header. e.g. TestHeader |
| * @param pachPrefix Prefix to be used in XML represenation of SOAP header |
| * e.g. th |
| * @param pachUri Namespace URI to be used in SOAP header. |
| e.g http://ws.apache.org/axisCppTestHeader/ |
| * |
| * @return Pointer to the creater SOAP header block. |
| */ |
| IHeaderBlock* AXISCALL createSOAPHeaderBlock(AxisChar * pachLocalName, |
| AxisChar * pachUri, |
| AxisChar * pachPrefix); |
| |
| /** |
| * Iterator initiatior for SOAP header blocks |
| * |
| * This method must be called first to initiate access to the list of |
| * SOAP header blocks. |
| * |
| * @return First SOAP header block pointer. If there are no SOAP header |
| * blocks set, returns NULL. |
| */ |
| IHeaderBlock* getFirstSOAPHeaderBlock(); |
| |
| /** |
| * Iterator for SOAP header blocks |
| * |
| * getFirstSOAPHeaderBlock() method must have been called at least once |
| * before this method is called. If not behaviour is undefined. |
| * |
| * This method advances the iterator by one position. |
| * Repeated calls always retuen the next value. |
| * |
| * @return Next SOAP header block pointer. If there are no SOAP header |
| * blocks set or if iterator is at the end of the list, returns NULL. |
| */ |
| IHeaderBlock* getNextSOAPHeaderBlock(); |
| |
| /** |
| * Accessor for SOAP header blocks |
| * |
| * This method gives access to the SOAP header block pointer corresponding |
| * to the SOAP header block currently being pointed by SOAP header blocks |
| * iterator. |
| * |
| * getFirstSOAPHeaderBlock() method must have been called at least once |
| * before this method is called. If not behaviour is undefined. |
| * |
| * This method does not advance the iterator. |
| * Repeated calls always retuen the same key unless |
| * getNextSOAPHeaderBlock() is called in between. |
| * |
| * @return Current SOAP header block pointer. If there are no SOAP header |
| * block set or if iterator is at the end of the list, returns NULL. |
| */ |
| IHeaderBlock* getCurrentSOAPHeaderBlock(); |
| |
| /** |
| * Deletes the SOAP header block currently pointed to by |
| * the iterator. |
| */ |
| void deleteCurrentSOAPHeaderBlock(); |
| |
| /** |
| * Deletes the given SOAP header block pointer from the current list of |
| * SOAP header blocks. |
| * |
| * This method does a pointer comparison. It does not compare the contents |
| * within objects. |
| * Hence it is expected that either the pointer returned by the |
| * create method or by one of the iterator methods would be used with |
| * this method. |
| * |
| * This method does not advance the iterator in line with the deletes done. |
| * In case you want to access the SOAP header blocks after using this |
| * method, it is advisable to reinitialize the iterator using |
| * getFirstSOAPHeaderBlock(); |
| * However you can use this method despite where the iterator is |
| * pointing currently. |
| * |
| * @param pHeaderBlock Pointer of the header block to be deleted. |
| */ |
| void deleteSOAPHeaderBlock(IHeaderBlock* pHeaderBlock); |
| |
| /** |
| * Add namespace to SOAP header. |
| * |
| * @param pUri The namespace uri . |
| * @param pPrefix The prefix to associate with the uri. |
| */ |
| void addNamespaceToSOAPHeader(const AxisChar * pUri, const AxisChar * pPrefix); |
| |
| /** |
| * Clears SOAP header namespaces. |
| */ |
| void clearSOAPHeaderNamespaces(); |
| |
| /** |
| * Add attribute to SOAP header. |
| * |
| * @param pLocalname The local name of the Attribute. |
| * @param pPrefix The prefix of the Attribute. |
| * @param pValue The value of the Attribute. |
| */ |
| void addAttributeToSOAPHeader(const AxisChar * pLocalname, |
| const AxisChar * pPrefix, |
| const AxisChar * pValue); |
| |
| /** |
| * Clears SOAP header attributes. |
| */ |
| void clearSOAPHeaderAttributes(); |
| |
| /** |
| * Add namespace to SOAP body. |
| * |
| * @param pUri The namespace uri . |
| * @param pPrefix The prefix to associate with the uri. |
| */ |
| void addNamespaceToSOAPBody(const AxisChar * pUri, const AxisChar * pPrefix); |
| |
| /** |
| * Clears SOAP body namespaces. |
| */ |
| void clearSOAPBodyNamespaces(); |
| |
| /** |
| * Add attribute to SOAP body. |
| * |
| * @param pLocalname The local name of the Attribute. |
| * @param pPrefix The prefix of the Attribute. |
| * @param pUri The namespace uri of the Attribute. |
| * @param pValue The value of the Attribute. |
| */ |
| void addAttributeToSOAPBody(const AxisChar * pLocalname, |
| const AxisChar * pPrefix, |
| const AxisChar * pValue); |
| |
| /** |
| * Clears SOAP body attributes. |
| */ |
| void clearSOAPBodyAttributes(); |
| |
| /** |
| * Set proxy server and port for transport. |
| * |
| * @param pcProxyHost Host name of proxy server |
| * @param uiProxyPort Port of proxy server |
| */ |
| void setProxy(const char* pcProxyHost, unsigned int uiProxyPort); |
| /** |
| * Sets the username to be used for basic authentication |
| */ |
| void setUsername(const char* pcUsername); |
| /** |
| * Sets the password to be used for basic authentication |
| */ |
| void setPassword(const char* pcPassword); |
| |
| /** |
| * Set transport timeout. |
| * |
| * @param lSeconds Timeout in seconds. |
| * If lSeconds is 0, then the transport will assume no |
| * timeout. Hence you want to reset a timeout already set |
| * use 0. |
| */ |
| void setTransportTimeout(long lSeconds); |
| |
| /** |
| * Set transport connect timeout. |
| * |
| * @param lSeconds Timeout in seconds. |
| * If lSeconds is 0, then the transport will assume no |
| * timeout. Hence you want to reset a timeout already set |
| * use 0. |
| */ |
| void setTransportConnectTimeout(long lSeconds); |
| |
| /** |
| * Get the status of the stub to see any error situation |
| */ |
| int getStatus(); |
| |
| /** |
| * Set whether to Maintain session with service ot not. |
| * @param bSession - true if session should be maintained. False otherwise. |
| */ |
| void setMaintainSession(bool bSession); |
| |
| /** |
| * Set transport protocol to be used by the transport. |
| * @param eProtocol - protocol to use |
| */ |
| void setTransportProtocol(AXIS_PROTOCOL_TYPE eProtocol); |
| |
| /** |
| * Get transport protocol being used by the transport. |
| * @return Protocol used by transport |
| */ |
| AXIS_PROTOCOL_TYPE getTransportProtocol(); |
| |
| |
| /** |
| * Sets the username to be used for Proxy authentication |
| */ |
| void setProxyUsername(const char* pcProxyUsername); |
| |
| /** |
| * Sets the password to be used for Proxy authentication |
| */ |
| void setProxyPassword(const char* pcProxyPassword); |
| |
| /** |
| * Gets the username used for Proxy authentication |
| */ |
| const char* getProxyUsername(); |
| |
| /** |
| * Gets the password used for Proxy authentication |
| */ |
| const char* getProxyPassword(); |
| |
| /** |
| * Call object of the Stub. This is the point of access to the internals |
| * of the Axis engine. |
| */ |
| Call *getCall() { return m_pCall; } |
| |
| /** |
| * Creates an ISoapAttachment which represents an attachment. The ISoapAttachment should be passed as |
| * an attachmment parameter to a web service. The storage associated with the ISoapAttachment will be |
| * automatically deleted by Axis C++ if it is passed as a parameter to a web service. |
| */ |
| ISoapAttachment* createSoapAttachment(); |
| |
| /** |
| * Set SSL configuration properties. |
| */ |
| void AXISCALL SetSecure( char *pszArguments, ...); |
| |
| /** |
| * Set SSL configuration properties. Added |
| * to support C bindings implementation. |
| */ |
| void AXISCALL SetSecure( char *pszArguments, va_list args); |
| |
| /** |
| * Set pointer to exception handler function for stub object. |
| * This function was added in support of the c-Binding implementation. |
| */ |
| void setCExceptionHandler(void *pExceptionHandler) |
| { |
| m_pExceptionHandler = pExceptionHandler; |
| } |
| |
| /** |
| * Get pointer to exception handling function for call object. |
| * This function was added in support of the c-Binding implementation. |
| */ |
| void *getCExceptionHandler() { return m_pExceptionHandler; } |
| |
| protected: |
| /** |
| * Apply user set preferences to each call made on the Stub object. |
| * This method is required because Axis engine holds only part of the state |
| * with refereance to subsequent calls on the same Stub object. |
| * Foxing this approach would make the engine much more efficient. |
| */ |
| void applyUserPreferences(); |
| |
| /** |
| * Apply SSL configuration properties. |
| */ |
| void includeSecure(); |
| |
| /** |
| * Set SOAP Headers stored in m_vSOAPHeaderBlock vector. |
| * Called by applyUserPreferences for each and every method invocation. |
| */ |
| void setSOAPHeaders(); |
| |
| /** |
| * Set Authorization header for Proxy authentication |
| */ |
| void setProxyAuthorizationHeader(); |
| |
| /** |
| * Check for extraneous elements. Called at the end of SOAP processing |
| * to ensure that there are no extraneous elements. Will throw an |
| * exception if extraneous elements are detected. |
| */ |
| void checkForExtraneousElements(); |
| |
| /** |
| * Call object |
| */ |
| Call *m_pCall; |
| |
| /** |
| * Vector of Header Block pointers |
| */ |
| #ifdef WIN32 |
| #pragma warning (push) |
| #pragma warning (disable : 4251) |
| #endif |
| vector < IHeaderBlock * >m_vSOAPHeaderBlocks; |
| /** |
| * Transport keys iterator |
| */ |
| vector <IHeaderBlock *>::iterator m_viCurrentSOAPHeaderBlock; |
| |
| std::vector < IAttribute * >m_vSOAPHeaderNamespaces; |
| std::vector < IAttribute * >m_vSOAPHeaderAttributes; |
| |
| std::vector < IAttribute * >m_vSOAPBodyNamespaces; |
| std::vector < IAttribute * >m_vSOAPBodyAttributes; |
| |
| #ifdef WIN32 |
| #pragma warning (pop) |
| #endif |
| |
| /** |
| * Transport object |
| */ |
| SOAPTransport* m_pTransport; |
| |
| |
| /** |
| * proxy Username |
| */ |
| char* m_proxyUsername; |
| |
| /** |
| * proxy Password |
| */ |
| char* m_proxyPassword; |
| |
| private: |
| /** |
| * Copy constructor prohibited! |
| */ |
| Stub(const Stub& src) {} |
| |
| /** |
| * Assignment prohibited! |
| */ |
| Stub& operator=(const Stub& src) {return *this;} |
| |
| /** |
| * SSL configuration parameters |
| */ |
| std::string m_sArguments[8]; |
| |
| /** |
| * Following is for C-binding support. Pointer to exception handler function. |
| */ |
| void * m_pExceptionHandler; |
| }; |
| |
| AXIS_CPP_NAMESPACE_END |
| |
| #endif /* !defined(_STUB_H____OF_AXIS_INCLUDED_) */ |
