/*

* 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:  HsService Finder

*

*/

#ifndef SERVICEFINDER_H

#define SERVICEFINDER_H

#include <QObject>

#include "serviceinterfaceid.h"

#include "hsiserviceprovider.h"

#include "servicemodel_global.h"

class IHsServiceBase;

class HsServiceFinderPrivate;

class HsService;

/**

 * @ingroup group_hsservicemodel group_service_api_candidates

 * @brief Helper class to search and create services.

 * HsService adapter is the component to find different platform service implementations

 * and offer interface to use services.

 */

class HSSERVICEMODEL_EXPORT HsServiceFinder : public QObject

{

	Q_OBJECT

public:

    /**

     * Constructor.

     * @since S60 ?S60_version.

     * @param aPluginManifestDirectory Directory that contains plugin manifests.

     * @param aPluginDirectory Directory that contains plugin binaries.

     * @param aParent Parent object.

     */

    HsServiceFinder(const QString& aPluginManifestDirectory,

                  const QString& aPluginDirectory,

                  QObject* aParent = 0);

    /**

    * Destructor    

    */

    virtual ~HsServiceFinder();

public:

    /**

     * Get list of all services in the device implemented according the service architecture.

     * @return list of services (empty list if no services in the device).

     */

    QList<HsServiceToken> getServiceList();

    /**

     * Get list of all services in the device implemented according the service architecture.

     * @param aService for example 'BackupService'

     * @return list of matched services (empty list if no services in the device).

     * @code

     * if (!mServiceFinder)

     *     {

     *     mServiceFinder = new HsServiceFinder("c:/hsplugins","c:/hsplugins",this);

     *     }

     * IBackupService* service = 0;

     * QList<HsServiceToken> serviceList = mServiceFinder->getServiceList(IBackupService::type().mImplementationId );

     * if ( serviceList.count() )

     *     {

     *     // use first found service

     *     service = mServiceFinder->getService<IBackupService>(IBackupService::type(), serviceList.at(0));

     *     }

     *

     * @endcode

     */

    QList<HsServiceToken> getServiceList(const QString &aService);

    /**

     * Get service. This method returns the service as a QObject.

     * @param aService for example 'HsService.Messaging'

     * @param aInterface for example 'IMessaging'

     * @return pointer to HsService object. Ownership is NOT transferred to caller.

     * @see releaseService

     * @code

     * if (!mServiceFinder)

     *     {

     *     mServiceFinder = new HsServiceFinder("c:/hsplugins","c:/hsplugins",this);

     *     }

     * HsService* servicePtr = mServiceFinder->getService("HsService.Messaging", "IMessaging");

     * @endcode

     */

    HsService *getService(const QString &aService, const QString &aInterface);

    /**

     * Get service. This method returns the service as an abstract interface.

     * @param aInterfaceId service interface identifier

     * @param aPluginName which plugin implements this service, if empty, then first found interface is used.

     * @return pointer to service interface object. Ownership is NOT transferred to caller.

     *

     * Example in source code:

     * @code

     * if (!mServiceFinder)

     *     {

     *     mServiceFinder = new HsServiceFinder("c:/hsplugins","c:/hsplugins",this);

     *     }

     * IBackupService* service = 0;

     * service = mServiceFinder->getService<IBackupService>(IBackupService::type(), "backupservice");

     * if ( service )

     *     {

     *     service->backupPage();

     *     }

     * @endcode

     * where IBackupService is defined in header file:

     * @code

     * static const HsServiceInterfaceId Identifier=

     *     {

     *     0,"persistanceservice"

     *     };

     *

     * class IBackupService: public IHsServiceBase

     * {

     * public:

     * static inline const HsServiceInterfaceId& type()

     *     {

     *     return Identifier;

     *     }

     * public:

     * virtual void backupPage() = 0;

     * virtual IHsServiceBase* resolveService(const HsServiceInterfaceId& aType) = 0;

     * ... other possible API functions

     * @endcode

     * @see more details in example backupservice implementation, IBackupService, PersistanceService...

     */

    template<class T> T *getService(const HsServiceInterfaceId &aInterfaceId, const QString &aPluginName)

    {

        return static_cast<T*>(getService(aInterfaceId, aPluginName));

    }

    /**

     * Get service. This method returns the service as an abstract interface.

     * @param aInterfaceId service interface identifier

     * @param aToken which plugin implements this service

     * @return pointer to service interface object. Ownership is NOT transferred to caller.

     *

     * @code

     * if (!mServiceFinder)

     *     {

     *     mServiceFinder = new HsServiceFinder("c:/hsplugins","c:/hsplugins",this);

     *     }

     * IBackupService* service = 0;

     * QList<HsServiceToken> serviceList = mServiceFinder->getServiceList(IBackupService::type().mImplementationId);

     * if ( serviceList.count() )

     *     {

     *     // use first found service

     *     service = mServiceFinder->getService<IBackupService>(IBackupService::type(), serviceList.at(0));

     *     }

     * if ( service )

     *     {

     *     service->backupPage();

     *     }

     * @endcode

     */

    template<class T> T *getService(const HsServiceInterfaceId &aInterfaceId, const HsServiceToken &aToken)

    {

        return static_cast<T*>(getService(aInterfaceId, aToken));

    }

    /**

     * Get service. This method returns the service as an Base interface of the all services.

     * @param aInterfaceId service interface identifier

     * @param aPluginName which plugin implements this service

     * @return pointer to service interface object. Ownership is NOT transferred to caller.

     */

    IHsServiceBase *getService(const HsServiceInterfaceId &aInterfaceId, const QString &aPluginName);

    /**

     * Get service. This method returns the service as an Base interface of the all services.

     * @param aInterfaceId service interface identifier

     * @param aToken which plugin implements this service

     * @return pointer to service interface object. Ownership is NOT transferred to caller.

     */

    IHsServiceBase *getService(const HsServiceInterfaceId &aInterfaceId, const HsServiceToken &aToken);

    /**

     * Release service

     * @param aService service to be released and deleted. HsService is QObject based service.

     */

    void releaseService(HsService *aService);

    /**

     * Cancels asynchronous service requests.

     * @param aService QObject based service.

     */

    void cancel(HsService *aService);

private:

    /**

     * The private implementation.

     */

    HsServiceFinderPrivate *mServiceFinderPrivate;

};

#endif