--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javacommons/gcfbase/inc/serverconnectionfactory.h Tue Apr 27 16:30:29 2010 +0300
@@ -0,0 +1,185 @@
+/*
+* 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