/*
* 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 SERVERCONNECTIONFACTORY_H
#define SERVERCONNECTIONFACTORY_H

#include <memory>
#include <string>
#include <list>
#include "dynamiclibloader.h"

namespace java
{
namespace push
{

class ServerConnection;
class ConnectionListener;
class ServerConnectionFactory;
class PendingConnectionListener;

typedef ServerConnectionFactory& (*GetServerConnectionFactory)();

/**
 * This interface provides functionality to create/get and delete Server Connection.
 * Each Server Connection Plugin must implement this interface.
 * Note: Server Connection Plugin can use default implementation of this interface
 *       if it does not need any special implementation for functionality of this interface.
 *       ServerConnectionFactoryBase class provides default implementation for this interface.
 */

class ServerConnectionFactory
{
public:

    virtual ~ServerConnectionFactory() {}

    /**
     * User should not used this operation. This operation has been reserved for internal
     * usage of push framework.
     * This method creates ServerConnection for push registration. Type of connection is changed to PUSH
     * if normal server connection already exists with same URI.
     * Note: This method does not validate arguments. Validation must be done using PushValidator
     *       java framework before calling this operation.
     * @param aUri    Push connection URI.
     * @param aFilter Connection URI which is used to check whether senders are allowed to cause
     *                the MIDlet to be launched.
     * @param aListener Listener object. Ownership of the listener is not given to the implementation
     *                  of the ServerConnectionFactory interface.
     * @param aPendingConnListener Listener object. Ownership of the listener is not given to the
     *                             implementation of the ServerConnectionFactory interface.
     * @throws  PushException with following error codes:
     *          COMMON_SRV_CONN_PLUGIN_ERROR:
     *          Reserved for other errors in the creation of ServerConnection object.
     *          PUSH_CONNECTION_ALREADY_EXISTS:
     *          Other push connection with same URI already exists.
     *          Note: this does not concern normal server connection.
     */
    virtual ServerConnection& createPushServerConn(const std::wstring& aUri,
            const std::wstring& aFilter,
            ConnectionListener* aListener,
            PendingConnectionListener* aPendingConnListener) = 0;

    /**
     * User must use this operation to get ServerConnection object.
     * This operation creates an normal ServerConnection object or returns push ServerConnection
     * object. Note: ServerConnection object can be retrieved only once by this operation if
     * protocol does not support multiple instances for the same connection.
     * Existing object is returned otherwise.
     * @param aUri    Push connection URI.
     * @throws PushException with following error codes:
     *         PUSH_CONNECTION_ALREADY_EXISTS:
     *         If normal ServerConnection already exists or if ServerConnection object is retrieved
     *         more than once from this operation.
     * @return Ownership of the return value is not given to the user.
     */
    virtual ServerConnection* create(const std::wstring& aUri) = 0;

    /**
     * This operation populates aUriList output argument with active or all push
     * connection URIs of the MIDlet depending value of the aAvailable argument.
     * @param aAvailable 'true' means that only active push connections are returned.
     *                   Active push connection means connection where msg has been arrived.
     *                   'false' means that all push connections of the MIDlet is returned.
     * @param aUriList Output argument. Push connection URIs are populated into this list.
     * @throws This operation does not throw exceptions.
     */
    virtual void getPushConnections(bool aAvailable,std::list<std::wstring>& aUriList) = 0;

    /**
     * This operation calls ServerConnection::close() operation for each connection object.
     * This operation does not throw exceptions.
     */
    virtual void closeAllConnections() = 0;

    /**
     * NOTE: Usage of this operation is reserved only for the push framework.
     * This operation calls close() operation for ServerConnection object, removes
     * object from the container and delete it. This operation does not do anything
     * if ServerConnection object is not found.
     */
    virtual void deletePushConnection(const std::wstring& aUri) = 0;

    /**
     * This operation return push ServerConnection object.
     * @param aUri Push connection URI.
     * @throws This operation does not throw exceptions.
     * @return Push ServerConnection object. Ownership of the returned object is not given to the user.
     *         Returns NULL if ServerConnection is not found by URI or if ServerConnection
     *         is not push connection.
     */
    virtual ServerConnection* getPushConnection(const std::wstring& aUri) = 0;

    /**
     * Releases a server connection depending state of the connection.
     * Nothing is done if ServerConnection object by URI is not found.
     * Push capable protocol MUST use this operation to release ServerConnection object.
     * Logic of this operation:
     * [Server connection is non-push connection]
     *    First this operation calls close() to the ServerConnection object and after that
     *    object is removed from the container and deleted.
     * [Server connection is push connection listened by MIDlet]
     *    First this operation calls close() to the ServerConnection object and after that
     *    it changed type of the ServerConnection to 'push'.
     * @throws This operation does not throw exceptions.
     */
    virtual void releaseConnection(const std::wstring& aUri) = 0;

    /**
     * This operation loads Server Connection plugin and returns ServerConnectionFactory
     * object. Note: ServerConnectionFactory must be singleton object in the process.
     * @param aDllName name of the dll.
     * @param aLoader Output parameter. This object manages loading Server Connection Plugin
     *                dll and creation of ServerConnectionFactory object. Note: Deleting this object
     *                unloads Server Connection Plugin dll (if this dll has been loaded only once).
     *                I.e. this object have to be alive until this plugin is not used.
     * @throws        LibraryLoaderException with following error codes:
     *                OPENING_LIBRARY_FAILED:
     *                opening a Server Connection Plugin failed.
     *                E.g. in the situation where certain protocol is not supported.
     *                CANNOT_FIND_FUNCTION_FAILURE:
     *                Function by "getServerConnectionFactory"
     *                name is not found from ServerConnection Plugin.
     */
    static ServerConnectionFactory&
    getServerConnectionFactory(const std::string& aDllName,
                               std::auto_ptr<java::util::DynamicLibLoader>& aLoader);
};

inline ServerConnectionFactory&
ServerConnectionFactory::getServerConnectionFactory(const std::string& aDllName,
        std::auto_ptr<java::util::DynamicLibLoader>& loader)
{
    //A function pointer to the factory method.
    if (0 == loader.get())
    {
        loader.reset(new java::util::DynamicLibLoader(aDllName.c_str(),false));
    }

    //Cast the function ptr
    GetServerConnectionFactory getServerConnFactory =
        reinterpret_cast<GetServerConnectionFactory>(loader->getFunction("getServerConnectionFactory"));

    return getServerConnFactory();
}

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

#endif // SERVERCONNECTIONFACTORY_H