/*
 *   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.
 *
 */

#if !defined(AXIS_SOAPTRANSPORT_H__OF_AXIS_INCLUDED_)
#define AXIS_SOAPTRANSPORT_H__OF_AXIS_INCLUDED_

#include <axis/GDefine.hpp>
#include <axis/ISoapAttachment.hpp>

/**
 * @file SOAPTransport.h
 *
 * Contains the interfaces that any transport layer should implement in order
 * for using in Axis. The implementation should be at lease thread safe. The
 * Axis Engine creates a separate transport object for each thread.
 */

#ifdef __cplusplus

/**
 * @interface AxisIOStream
 *
 * Interface of the input/output stream of Axis transport. The use of this
 * interface is to avoid the parser being provided the full functionalies
 * of SOAPTransport interface
 *
 * @brief Interface of the input/output stream of Axis transport. ISOAPTransport is
 *        derived from this interface
 */

AXIS_CPP_NAMESPACE_START

typedef enum
{
    TRANSPORT_FINISHED=0,
    TRANSPORT_IN_PROGRESS,
    TRANSPORT_FAILED
} AXIS_TRANSPORT_STATUS;

typedef enum
{
    AXIS_HTTP_GET,
    AXIS_HTTP_POST,
    AXIS_HTTP_UNSUPPORTED
} AXIS_HTTP_METHOD;

// Samisa: This was in the removed include/axis/server/Packet.hpp
// This is required by Apache transports in src/server/apache*
// I added this here as I felt this is the most suitable place for it.
typedef struct
{
    const void* pBufferId;
    const char* pcBuffer;
} BufferInfo;

// Samisa : This too was defined in include/axis/server/Packet.hpp
// and used by Apache transports in src/server/apache*
typedef struct
{
    char* headername;
    char* headervalue;
} Ax_header;


// Samisa: NO_OF_SERIALIZE_BUFFERS too was defined in include/axis/server/Packet.hpp
// As that header has been removed I put it here.
// This is used by Apache transport classes in ser/srver/apache*
#define NO_OF_SERIALIZE_BUFFERS 20

/*
 * This function is provided by the Axis Engine. 
 * Called by transport module when it needs to say that
 * a message buffer passed to it is no longer being used by the transport 
 * and can be re-used by the 
 * Axis engine.This function should be called for each buffer 
 * if AXIS_MODULE_CALLBACK_SEND_MESSAGE_BYTES
 * returned TRANSPORT_IN_PROGRESS.
 * @param 
 *        1st - buffer that Axis gave to the transport layer
 *        2nd - buffer id    which uniquely identifies the buffer
 *        3rd - Ax_soapstream object which act like a thread id
 */
typedef void (AXISCALL * AXIS_ENGINE_CALLBACK_RELEASE_SEND_BUFFER)
(const char*, const void*);
 
class AxisIOStream
{
public:
    /**
     * Destructor
     */
    virtual ~AxisIOStream() {}

    /**
     * Sends a buffer to the transport layer. A Caller may call this method
     * multiple times to send several buffers. Its upto the transport to
     * decide how they are sent (chunked/unchunked etc). But should return the
     * appropriate status code.
     *
     * @brief Sends a buffer to the transport layer.
     * @pre   1. Transport connection should have been established by calling
     *           Openconnection of the SOAPTransport's implementaion.
     *        2. If the implementaion of SOAPTransport intends to accumulate
     * @param pcSendBuffer Null terminated character buffer to be sent.
     * @param pBufferid void* that represents the buffer id. This pointer will
     *        only be needed by the transport layer when it needs to call
     *        caller provided callback function to indicate that transport
     *        layer has finished using the buffer. So when the transport layer
     *        intends to keep the pcSendBuffer for late sending, the value of
     *        pBufferid should also be stored. In case when pBufferid is NULL
     *        the transport layer can keep the buffer for late sending. But
     *        MUST never call the release buffer callback.
     *
     * @return Transport status. Three states are possible. They are,
     *       TRANSPORT_FINISHED    - Passed buffer has been sent. So the caller
     *                               can re-use the buffer
     *       TRANSPORT_IN_PROGRESS - Passed buffer is not yet sent. So the
     *                               caller cannot re-use the buffer
     *       TRANSPORT_FAILED      - Transport layer has failed. So the caller
     *                               should not send any more buffers.
     * @post In case this function returns TRANSPORT_IN_PROGRESS. The caller
     *       should wait till the transport layer calls the provided callback
     *       function with the bufferid to indicate that it can re-use
     *       the buffer. The transport layer MUST call the callback function
     *       for each buffer for which this function returned the status
     *       code TRANSPORT_IN_PROGRESS.
     */
    virtual AXIS_TRANSPORT_STATUS sendBytes(const char* pcSendBuffer, const void* pBufferid)=0;
    
    /**
     * Gets a part of or full SOAP message. A Caller may call this method
     * multiple times to get parts of the SOAP message until the function
     * return status says that no more data available.
     *
     * @brief Gets a part of or full SOAP message.
     * @pre   Transport connection should have been established by calling
     *        Openconnection of the SOAPTransport's implementation.
     * @param pcBuffer The character buffer provided by the caller to be
     *        filled by the transport layer. The size of the buffer is given
     *        by the value of second parameter piRetSize. The transport layer
     *        should fill the buffer and put the number of bytes filled into
     *        the inout parameter piRetSize.
     * @param piRetSize Inout parameter which contain the size of the buffer
     *        as the in value. On return the transport layer should populate
     *        this parameter with the number of bytes copied to the buffer.
     *
     * @return Transport status. Three states are possible. They are,
     *       TRANSPORT_FINISHED    - Method call successful. No more data
     *                               is available. If pcBuffer contains any
     *                               data this is the final part of the message.
     *                               can re-use the buffer.
     *       TRANSPORT_IN_PROGRESS - Method call is successful. There can be
     *                               more data of this message for subsequent
     *                               calls to this method. pcBuffer must have
     *                               been filled to its maximum capacity.
     *       TRANSPORT_FAILED      - Transport layer has failed. So the caller
     *                               should not call this method again. Any
     *                               data in the pcBuffer are not reliable and
     *                               should not be used.
     */
    virtual AXIS_TRANSPORT_STATUS getBytes(char* pcBuffer, int* piRetSize)=0;
};

/**
 * @interface SOAPTransport
 *
 * Interface of any Axis transport. Every transpor layer should implement this
 * interface in order to be used with Axis Engine. This interface contain the
 * functionalities independent of the type of transport (whether HTTP, SMTP,
 * etc).
 *
 * @brief Interface of any Axis transport layer.
 *
 */
AXIS_CPP_NAMESPACE_END
AXIS_CPP_NAMESPACE_START
class SOAPTransport : public AxisIOStream
{
public:
    SOAPTransport()
    {
        m_pcEndpointUri = NULL;
        m_pcUsername    = NULL;
        m_pcPassword    = NULL;        
    }
    
    virtual ~SOAPTransport()
    {
        delete[]m_pcUsername;
        delete[]m_pcPassword;
    };
    /**
     * Opens a connection with the provided endpoint URI. The connection
     * type (protocol) is decided by the implementation and the protocol
     * set. See example implementation.
     *
     * @brief Opens a connection with the provided endpoint URI.
     * @pre   The endpoint URI and the protocol type (if needed) MUST have
     *        been set.
     * @example AxisTransport.h
     * @return Returns AXIS_SUCCESS if connection established successfully.
     *         Else returns AXIS_FAIL
     */
    virtual int openConnection()=0;
    
    /**
     * @brief Closes the connection established with OpenConnection.
     * @param forceClose whether or not to force a close. If true, 
     *        the connection will be closed.  If false, the transport
     *        will determine whether connection should be closed based
     *        on transport dependent properties.  For example, 
     *        HTTP transport may use HTTP header "Connection: close"
     *        to determine if connection should be closed.
     * @example AxisTransport.h
     */
    virtual void closeConnection(bool forceClose=true)=0;
    
    /**
     * Sets a predefined transport property to be included in the outgoing
     * message. This transport property is not persistent in the transport
     * layer. These transport properties should be set for each outgoing
     * message.
     *
     * @brief Sets a predefined transport property for outgoing message.
     * @param eType Predefined transport property to be set.
     *        for predefined transport property types.
     * @param pcValue Transport property value to be set.
     */
    virtual int setTransportProperty(AXIS_TRANSPORT_INFORMATION_TYPE eType, const char* pcValue)=0;
    /**
     * @brief Gets a predefined transport property in the arrived message
     *
     * @param eType Predefined transport property to get.
     *        for predefined transport property types.
     * @return Value of the transport property if available. Returns null
     *         if unavailable.
     */
    virtual const char* getTransportProperty(AXIS_TRANSPORT_INFORMATION_TYPE eType)=0;
    /**
     * Sets any transport property to be included in the outgoing message.
     * This transport property is not persistent in the transport layer.
     * These transport properties should be set for each outgoing message.
     *
     * @brief Sets any transport property.
     * @param pcKey Key for the transport property to be set.
     * @param pcValue Value for transport property to be set.
     */
    virtual int setTransportProperty(const char* pcKey, const char* pcValue)=0;
    /**
     * @brief Gets any transport property in the arrived message
     *
     * @param pcKey The key of the transport property to get.
     * @param response gets a property from the response message when true and
     *                 from the send message when false
     * @return Value of the transport property if available. Returns null
     *         if unavailable.
     * NOTE: If there are multiple properties with the same name then only the first one in the message
     * will be returned - please use getTransportProperties if you want all properties.
     */
    virtual const char* getTransportProperty(const char* pcKey, bool response=true)=0;

    /**
     * Sets a SOAP attachment to be sent with outgoing message. This
     * attachment is usually the base64 or hex encoded character buffer
     * that is null terminated.
     *
     * @brief Sets a SOAP attachment to be sent with outgoing message
     * @param pcAttachmentid An identifier for the attachment. This identifier also
     *        will go in to the SOAP message so that the recipient will know that
     *        there is an attachemet in the message.
     * @param pcAttachment The attachment. This is usually a null terminated string
     *        encoded to base64 or hex binary.
     */
    virtual void setAttachment(const char* pcAttachmentid, const char* pcAttachment)=0;
    /**
     * Gets an attachment arrived in the inbound message. Usually the SOAP message will
     * contain the information indicating that there is an attachment arrived at the
     * transport. The SOAP message also contain the attachement id which is required
     * to request the transport for the particular attachment.
     *
     * @brief Gets an attachment arrived in the inbound message.
     * @pre To get an attachment the attachment id must be provided. The SOAP message
     *      should contain the attachment id.
     * @param pcAttachmentid Attachment identifier that the caller should find from
     *        the SOAP message and pass in. The transport will use this identifier
     *        to locate the corresponding attachment.
     * @return The attachment if available. Returns null if the attachment
     *         corresponding to the pcAttachmentid is not found.
     */    
    virtual ISoapAttachment* getAttachment(const char* pcAttachmentid)=0;
    virtual ISoapAttachment** getAllAttachments(int *pAttchArraySize)=0;


    virtual char* getIncomingSOAPMimeHeaders()=0;

    /**
     * Sets the the remote endpoint for tranport to connect to. This URI
     * depends on the the transport type. 
     *
     * @pre   A caller should use the method getProtocol() to get the type
     *        of the transport. Then the caller should set the endpoint URI
     *        accordingly. For example if the transport is HTTP this
     *        endpoint can be "http://www.xxx.com/"and if the transport is
     *        SMTP this endpoint can be the mail server and port.
     *
     * @brief Sets the remote endpoint for tranport to connect to.
     * @param pcEndpointUri Endpoint URI to connect to.
     */
    virtual void setEndpointUri(const char* pcEndpointUri)=0;
    /**
     * Sets the session id for the transport session. Actual usage of this
     * session id is depend on the implementation of the transport.
     *
     * @brief Sets the session id for the transport session.
     * @param pcSessionId The session id.
     */
    virtual void setSessionId(const char* pcSessionId)=0;
    /**
     * Gets the session id of the transport session sent by the remote end if
     * any. 
     *
     * @brief  Sets the session id for the transport session.
     * @return Session id if available. Returns null otherwise.
     */
    virtual const char* getSessionId()=0;
    /**
     * Gets the service name of the web service to be invoked. How this
     * service name is found is upto the type of the transport layer. For
     * example HTTP transports will look at the value of http header
     * "soapAction" and extract the service name. Whereas a SMTP transport
     * will look at recepitent address.
     *
     * @brief  Gets the service name of the web service to be invoked.
     * @return Service name if available and null otherwise.
     */
    virtual const char* getServiceName()=0;
    /**
     * Gets the protocol type of the transport library. The caller should
     * use this function to check the protocol of the transport layer and
     * should use the transport accordingly.
     *
     * @brief Gets the protocol type of the transport library.
     * @return The type of the transport. See AXIS_PROTOCOL_TYPE
     */
    virtual AXIS_PROTOCOL_TYPE getProtocol()=0;

    /**
     * Sets the protocol to be used by the transport library. 
     *
     * @param eProtocol - protocol to be used by transport.
     *                    See AXIS_PROTOCOL_TYPE in GDefine.hpp
     * @return AXIS_SUCCESS if protocol is supported. Else AXIS_FAIL.
     */
    virtual int setProtocol(AXIS_PROTOCOL_TYPE eProtocol)=0;

    /**
     * Gets the sub protocol. The usefulness of this method and the return
     * values depend on the particular implementation. For example HTTP
     * transports should return one of the values defined in enumeration
     * AXIS_HTTP_METHOD.
     *
     * @brief Gets the sub protocol. 
     * @return Type of the sub protocol (Ex: GET, POST, UNSUPPORTED for HTTP).
     */
    virtual int getSubProtocol()=0;
    /**
     * @brief Forces transport to send any remaining data of the outgoing message.
     * @return Transport status. Two return status are possible. They are,
     *         TRANSPORT_FAILED   - Sending data has failed.
     *         TRANSPORT_FINISHED - Sending finished and successful.
     */
    virtual AXIS_TRANSPORT_STATUS flushOutput()=0;
  /**
    * Set proxy server and port for transport.
    *
    * Setting the proxy is useful for users who are behind proxies.
    *
    * For some transports this method may not make sense.
    * Hence this method is not pure virtual.
    * Those transports that implement this interface, that wish to use proxy, must provide an implementation.
    * Also, the hadling of the proxy is the responsibility of the deriving classes
    *
    * @param pcProxyHost Host name of proxy server
    * @param uiProxyPort Port of proxy server
    */
    virtual void setProxy(const char* pcProxyHost, unsigned int uiProxyPort) {}

  /**
    * Set transport timeout.
    *
    * @param lSeconds Timeout in seconds
    */
    virtual void setTimeout(long lSeconds) = 0;
    
    /**
      * Set transport connect timeout.
      *
      * @param lSeconds Timeout in seconds
      */
    virtual void setConnectTimeout(long lSeconds) = 0;

  /**    
    * Iterator initiatior for transport property keys
    *
    * This method must be called first to initiate access to the list of 
    * transport property keys.
    * 
    * @param response - whether this is the response headers or not
    * @return First transport property key. If there are no transport 
    * properties set, returns NULL.
    */
    virtual const char* getFirstTransportPropertyKey(bool response=true) { return 0; };

  /**
    * 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 get the response message property or the sent message property
    * @return Next transport property key. If there are no transport 
    * properties set or if iterator is at the end of the list, returns NULL.
    */
    virtual const char* getNextTransportPropertyKey(bool response=true) { return 0; };

  /**
    * 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 get the response message property or the sent message property
    * @return Current transport property key. If there are no transport 
    * properties set or if iterator is at the end of the list, returns NULL.
    */
    virtual const char* getCurrentTransportPropertyKey(bool response=true) { return 0; };
    
  /**
    * 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 paires, 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. 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 to get the property value from the response or outgoing message
    * @return Current transport property value. If there are no transport 
    * properties set or if iterator is at the end of the list, returns NULL.
    */
    virtual const char* getCurrentTransportPropertyValue(bool response=true) { return 0; };

  /**
    * Deletes the transport property key:value pair currently pointed to by 
    * the iterator.
    * @param response whether to delete the response property or request property.
    */
    virtual void deleteCurrentTransportProperty(bool response=true) {};

  /**
    * Deletes the given occerance 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.
    *
    * @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.
    */
    virtual void deleteTransportProperty(char* pcKey, unsigned int uiOccurance = 1) {};
        
  /**
    * Set whether to Maitain session with service ot not.
    * @param bSession - true is session should be maintained. False otherwise.
    */
    virtual void setMaintainSession(bool bSession) {};

  /**
    * Get the last channel error string from the active channel.
    * @return string - Last active channel error string.
    */
    virtual const char * getLastChannelError() {return NULL;}
    
  /**
    * Is there a response that needs to be consumed?
    *  @return boolean - true if response data needs to be processed, falso otherwise.
    */
    virtual bool isThereResponseData() {return false;}
   
    /**
      * Enable trace.
      *  @param logFilePath  path to log file. 
      *  @param filters      log filters.  See common/AxisTrace.h.
      */
      virtual void enableTrace(const char* logFilePath, const char *filters) { }
      
  /**
    * Sets the username to be used for basic authentication
    */
    void setUsername(const char* pcUsername)
    {
        delete [] m_pcUsername;
        m_pcUsername = NULL;

        if (!pcUsername)
            return;

        m_pcUsername = new char[strlen (pcUsername) + 1];
        strcpy (m_pcUsername, pcUsername);
    }
    
    void setPassword (const char *pcPassword)
    {
        delete [] m_pcPassword;
        m_pcPassword = NULL;

        if (!pcPassword)
            return;

        m_pcPassword = new char[strlen (pcPassword) + 1];
        strcpy (m_pcPassword, pcPassword);
    }


  /**
    * Gets the username used for basic authentication
    */
    const char* getUsername()
    {
        return m_pcUsername;
    }
    

  /**
    * Gets the password used for basic authentication
    */
    const char* getPassword()
    {
     return m_pcPassword;
    }

protected:
    /**
     * Outgoing endpoint URI
     */
    char* m_pcEndpointUri;
    /**
     * Release buffer callback function registered. Usefull if the transport
     * is accumulating buffers to be sent later. Ex: non-chunked behavior
     * of http transports
     */ 
    AXIS_ENGINE_CALLBACK_RELEASE_SEND_BUFFER m_pReleaseBufferCallback;
 
    AXIS_PROTOCOL_TYPE m_eProtocolType;  

    /**
      * Username
      */
    char* m_pcUsername;

    /**
    * Password
    */
    char* m_pcPassword;

};

AXIS_CPP_NAMESPACE_END

#endif

#endif // !defined(AXIS_SOAPTRANSPORT_H__OF_AXIS_INCLUDED_)