/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/

#ifndef SERVERCONNECTION_H
#define SERVERCONNECTION_H

#include <string>

namespace java
{
namespace push
{

class ConnectionListener;

/**
 * This interface provides functionality open and get/set information related to
 * protocol connection. Each push capable protocol must implement this interface.
 */

class ServerConnection
{
public:

    virtual ~ServerConnection() {}

    /**
     * This operation set listener and opens physical protocol connection. Code execution must not
     * return from this operation before connection is physically opened. I.e. this method opens
     * connection synchronously.
     * Implementation of this operation must prepare situation wherein this operation is called
     * more than once after connection is already established. In this situation implementation of
     * this operation must only update a listener. This happens e.g. when push framework
     * takes listening responsible of the connection from the MIDlet(MIDlet has called
     * Connection.close() for a server connection).
     * @param aListener This operation does not take ownership of this pointer.
     * @throws PushException with COMMON_SRV_CONN_PLUGIN_ERROR error code if
     *         creation of the connection fails.
     */
    virtual void open(ConnectionListener* aListener) = 0;

    /**
     * This operation closes physical protocol connection. Closing a connection must be done
     * synchronously. I.e. code execution must not return from this operation before connection
     * is physically opened.
     * Note: ServerConnection must be closed by ServerConnectionFactory::releaseConnection() operation.
     * This operation does not throw an exception.
     */
    virtual void close() = 0;

    /**
     * @return connection URI.
     */
    virtual std::wstring getUri() const = 0;

    /**
     * @return filter URI of the push connection. Empty string is returned in the normal
     *         ServerConnection case.
     */
    virtual std::wstring getFilter() const = 0;

    /**
     * Sets 'filter' argument for the connection. This method is needed in the situation where
     * 'normal' ServerConnection has been created before dynamic push registration.
     */
    virtual void setFilter(const std::wstring& aFilter) = 0;

};

}//end namespace push
}//end namespace java

#endif // SERVERCONNECTION_H