/***************************************************************************
 *   Copyright (C) 2004 - 2005 by Raphael Langerhorst                      *
 *   raphael-langerhorst@gmx.at                                            *
 *                                                                         *
 *   Permission is hereby granted, free of charge, to any person obtaining *
 *   a copy of this software and associated documentation files (the       *
 *   "Software"), to deal in the Software without restriction, including   *
 *   without limitation the rights to use, copy, modify, merge, publish,   *
 *   distribute, sublicense, and/or sell copies of the Software, and to    *
 *   permit persons to whom the Software is furnished to do so, subject to *
 *   the following conditions:                                             *
 *                                                                         *
 *   The above copyright notice and this permission notice shall be        *
 *   included in all copies or substantial portions of the Software.       *
 *                                                                         *
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       *
 *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    *
 *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*
 *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR     *
 *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, *
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR *
 *   OTHER DEALINGS IN THE SOFTWARE.                                       *
 ***************************************************************************/

#ifndef GXMLNETWORK_H
#define GXMLNETWORK_H

#include <qobject.h>
#include <qdom.h>

namespace GWE
{

/**
 * \Interface GXmlNetwork GXmlNetwork.h
 * \brief Interface for XML based network implementations.
 * @author Raphael Langerhorst
 * 
 * This class is the abstract base class of all network implementations.
 * A GWE Server might have different simultaneous network implementations
 * active in case the GWE Server is routing between different network types.
 * In such situations the server has a different network ID for every
 * type of network.
 * 
 * The GWE Server management logic is implemented in the data controller, which
 * also knows to which destination server data should be sent. Thus this class
 * can concentrate on providing reliable data transportation.
 */
class GXmlNetwork : public QObject
{
  Q_OBJECT

  public:
  
  /**
   * Constructor.
   */
   GXmlNetwork(QObject *parent = 0, const char *name = 0)
     : QObject(parent,name)
     {}
   
  /**
   * Virtaul Destructor.
   */
   virtual ~GXmlNetwork() {}
   
   // NETWORK MANAGEMENT

   /**
    * @return true when the network is connected and usable, otherwise false
    */
   virtual bool isConnected() = 0;

   /**
    * @returns the network ID of this GWE Server instance.
    */
   virtual QString getNetworkId() const = 0;

  public slots:
   
   /**
    * Initialization.
    */
   virtual bool initNetwork() = 0;
   
   /**
    * Shuts down the network.
    * This should be called when the GWE Server is shutting down,
    * and AFTER all required tasks were performed to allow safe
    * shutdown (moving data to other server, etc.).
    */
   virtual bool closeNetwork() = 0;
   
   /**
    * Sets the password to be used
    */
   virtual void setPassword(const QString& password) = 0;
 
   // DATA TRANSPORTING
   
   /**
    * Add data for transportation. It is up to the network implementation when
    * the data is actually sent.
    * @param data The data that will be sent to the given network destination.
    * @param destination The GWE Server to which the data should be sent to.
    *
    * @see flushOutput()
    */
   virtual bool send(QDomElement data, const QString& destination) = 0;

   /**
    * Given string is directly sent, it's the responsibility of the application
    * to make it XML compliant.
    */
   virtual bool send(const QString& data) = 0;
   
   /**
    * Send all pending output data. This call blocks until all data was sent.
    */
   virtual bool flushOutput() = 0;
   
   /**
    * Try to establish a connection to given destination.
    */
   virtual void makeDestinationAvailable(const QString& destination) = 0;
   
   signals:
   
     // NETWORK MANAGEMENT
   
     /**
      * Emitted when the network has just been successfully connected.
      */
     void networkConnected();
    
     /**
      * Emitted when the network gets disconnetected.
      * It is also emitted when closeNetwork was called
      * to shut down the connection.
      */
     void networkDisconnected();
    
     /**
      * Emitted for any kind of error.
      * @param peer The address of the communication partner. Empty if communication was not peer to peer.
      */
     void networkError(int error_num, const QString& description, const QString& peer);
    
     /**
      * Emitted if a peer GWE Server is disconnected.
      */
     void peerDisconnected(const QString& peerNetworkId);
    
     // DATA TRANSPORTING
    
     /**
      * Emitted when one complete DOM document was successfully read from
      * given peer.
      */
     void dataAvailable(QDomElement data, const QString& source_peer);
     
     /**
      * Emitted when a GWE Server changes its presence state,
      * for example if the other server goes offline.
      */
     void presenceChanged(QString server, bool available);
};

}  //GWE namespace

#endif //GXMLNETWORK_H