/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

*

* This program is free software: you can redistribute it and/or modify

* it under the terms of the GNU Lesser General Public License as published by

* the Free Software Foundation, version 2.1 of the License.

* 

* This program is distributed in the hope that it will be useful,

* but WITHOUT ANY WARRANTY; without even the implied warranty of

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

* GNU Lesser General Public License for more details.

*

* You should have received a copy of the GNU Lesser General Public License

* along with this program.  If not, 

* see "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html/".

*

* Description:

*

*/

#include "xqservicelog.h"

#include "xqappmgr.h"

#include <xqaiwrequest.h>

#include <xqaiwinterfacedescriptor.h>

#include <QList>

#include "xqappmgr_p.h"

/*!

    \class XQApplicationManager

    \inpublicgroup QtBaseModule

    \ingroup ipc

    XQApplicationManager lists interface descriptors by interface and /or service name. It is also used to

    create interworking objects (XQAiwRequest).

    The Application Manager API offers centric place for applications UIs to handle application to application interworking use cases, like:

    - Synchronous out-of-process service call from client to service provider, where service provider needs to complete the request before

      control comes back to requesting client.

    - Asynchronous out-of-process service call from client to service provider, where Service provider completes the request whenever suitable.

      The control returns back requesting as soon the service provider has received the asynchronous call (can be applied to notifications as well).

    - Embedded out-of-process service call. In this case window groups are chained and "Back" returns to client window.

    - Any named Qt type in the Qt meta-object system can be used as a service call parameter or return value. Also own, custom meta-types are supported.

    - List and discover services dynamically.

    - Apply UI related options upon service launch, like "launch as embedded", "launch to foreground" and "launch to backround".

    - Opening URI to be viewed by a URI viewing interface. Includes also launching activity URIs (appto) as fire-and-forget manner.

    - Miscellanous AIW support, like get service stasus or get DRM attributes.

    <b>Example usage:</b> \n

    The usage pattern for all the XQApplicationManager variants implemented as service providers , interface, QUrl, QFile, is similar both embedded

    and non-embedded usage:

    \code

        // Recommended way is to add XQApplicationManager as member variable to class

        // You can use the class also as local variable.

        class Client

        {

        public:

             // Service access

            bool accessService(void);

        private slots:

                void handleOk(const QVariant &result);

                void handleError(int errorCode, const QString& errorMessage);

        private:

              XQApplicationManager mAiwMgr;

        };

        //  In client.cpp

        bool Client::accessService(void)

        {

            QString parameter1("+3581234567890");

            int parameter2 = 3;

            bool embedded=true;  // or false

            XQAiwRequest *request;

            // Create request by interface name, the very first service implementation

            // applied.

            // If dedicated service is wanted, apply this 

            // request = mAiwMgr.create("Service", "Interface", 

            if (request == NULL)

            {

                // Service not found 

                return false;

            }

            // ... Perform further processing

        }

    \endcode

    Access service by descriptor:

    \code

        QList<XQAiwInterfaceDescriptor> implementations = appmgr.list("Interface");

       // Display service in UI and make selection possible.

        foreach (XQAiwInterfaceDescriptor d, implementations)

        {

            qDebug() << "Service=" << d.serviceName();

            qDebug() << "Interface=" << d.interfaceName();

            qDebug("Implementation Id=%x",d.property(XQAiwInterfaceDescriptor::ImplementationId).toInt());

        }

        // Select correct implementation

        XQAiwInterfaceDescriptor selectedImpl = doSelectService();

        // The difference to the previous example is is how request is created

        // via application mgr.

        // ...See previous example

        request = mAiwMgr.create(selectedImpl, embedded);

        // ....See previous example

    \endcode

    \code

        QUrl url("appto://10207C62?activityname=MusicMainView"); 

        // The difference to the previous example is is how request is created

        // via application mgr.

        request = mAiwMgr.create(url);

        if (request == NULL)

        {

            // No handlers for the URI

            return;

        }

        // Set function parameters

        QList<QVariant> args;

        request->setArguments(args);

        // Send the request

        if  (!res) 

        {

            // Request failed. 

            int error = request->lastError();

            // Handle error

        }

       // All done.

       delete request;

    \endcode

    \sa XQAiwRequest

*/

XQApplicationManager::XQApplicationManager()

{

    XQSERVICE_DEBUG_PRINT("XQApplicationManager::XQApplicationManager");

    d = new XQApplicationManagerPrivate();

}

XQApplicationManager::~XQApplicationManager()

{

    XQSERVICE_DEBUG_PRINT("XQApplicationManager::~XQApplicationManager");

    delete d;

};

/*!

    Creates AIW request by interface and operation name.

    The first found service implementation is returned. If you need to activate specific implementation

    you shall first list() implementations and use the overloaded create() with XQAiwInterfaceDescriptor

    to select the correct implementation. 

    \param interface Interface name as mentioned in the service registry file.

                     Apply the xqaiwdecl.h file for common constants.

    \param operation The function signature to be called via the interface.

                     Can be set later via XQAiwRequest::setOperation.

                     Apply the xqaiwdecl.h file for common constants.

    \param embedded True if embedded (window groups chained) call, false otherwise.

                    Can be set later via XQAiwRequest::setEmbedded.

    \return The application interworking request instance, NULL if no service is available

    \sa list(const QString &interface, const QString &operation)

    \sa create( const XQAiwInterfaceDescriptor &implementation, const QString &operation, bool embedded);

    \sa xqaiwdecl.h for constants values

    Example usage:

    \code

    #include <xqaiwdecl.h>

    #include <xqapplicationmanager.h>

    // XQApplicationManager mAppMgr;  // Set manager as class member

    XQAiwRequest * req = this->mAppMgr.create(XQI_IMAGE_FETCH, XQOP_IMAGE_FETCH, false);

    if (req)

    {

        // There was service available

        QList<QVariant> args;

        args << folder;

        args << previewOn;

        req->setArguments(args);

        connect(req, SIGNAL(requestOk(const QVariant&)), this, SLOT(handleOk(const QVariant&)));

        connect(req, SIGNAL(requestError(int,const QString&)), this, SLOT(handleError(int,const QString&)));

        req->send();

    }

    \endcode

*/

XQAiwRequest* XQApplicationManager::create(

    const QString &interface, const QString &operation, bool embedded)

{

    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(interface)");

    return d->create(interface, operation, embedded);

}

/*!

    Creates AIW request by interface implementation descriptor and operation name.

    The descriptor is got from the list() call.

    As combination [service,interface,version] shall be unique,

    the descriptor points to one implementation and thus selects correct

    implementation.

    \param implementation Valid interface descriptor obtained by the list() call.

    \param operation The function signature to be called via the interface.

                     Can be set later via XQAiwRequest::setOperation.

                     Apply the xqaiwdecl.h file for common constants.

    \param embedded True if embedded call, false otherwise.

                     Can be set later via XQAiwRequest::setEmbedded.

    \return The application interworking request instance, NULL if no service is available

    \sa list()

    \sa create( const QString &interface, const QString &operation, bool embedded)

    \sa create( const QString &service, const QString &interface, const QString &operation, bool embedded)

    \sa xqaiwdecl.h for constants values

    Example usage:

    \code

    #include <xqaiwdecl.h>

    #include <xqapplicationmanager.h>

    XQApplicationManager appMgr;  // Prefer one instance only 

    QList<XQAiwInterfaceDescriptor> list = appMgr.list(XQI_CAMERA_CAPTURE, "");

    //

    // Populate a user interface widget and select proper implementation via descriptor

    // ... 

    XQAiwRequest * req = appMgr.create(selectedDescriptor, XQOP_CAMERA_CAPTURE);

    //

    // ... the rest as usual...

    //

    \endcode

*/

XQAiwRequest* XQApplicationManager::create(

    const XQAiwInterfaceDescriptor &implementation, const QString &operation, bool embedded)

{

    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create (impl.)");

    return d->create(implementation, operation, embedded);

}

/*!

    Creates AIW request by service and interface name.  You should not normally use this

    overload as typically service request are done by the interface name only.

    Internally this applies list() operation and applies the first found service

    implementation.

    \param service Service name as mentioned in the service registry file

    \param interface Interface name as mentioned in the service registry file

    \param operation The function signature to be called via the interface.

                     Can be set later via XQAiwRequest::setOperation.

    \param embedded True if embedded (window groups chained) call, false otherwise.

                     Can be set later via XQAiwRequest::setEmbedded.

    \return The application interworking request instance, NULL if no service is available

    \sa XQApplicationManager::create( const QString &interface, const QString &operation, bool embedded)

    \sa create( const XQAiwInterfaceDescriptor &implementation, const QString &operation, bool embedded);

    \sa xqaiwdecl.h for constants values

    Example usage:

    \code

    #include <xqaiwdecl.h>

    #include <xqapplicationmanager.h>

    #include <xqappmgr.h>;

    #include "componentglobal.h";

    // XQApplicationManager mAppMgr;  // manager as class member

    // Use embedded call.

    XQAiwRequest * req = this->mAppMgr.create(QLatin1String("photos"), XQI_IMAGE_FETCH, XQOP_IMAGE_FETCH, true);

    if (req)

    {

        ...

    }

    \endcode

*/

XQAiwRequest* XQApplicationManager::create(

    const QString &service, const QString &interface, const QString &operation, bool embedded)

{

    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(service+interface)");

    return d->create(service, interface, operation, embedded);

}

/*!

    List implementation descriptors by interface name.

    \param interface Interface name as mentioned in the service registry file

    \param operation The operation signature to be called.  Reserved for future use.

    \return The list of implementation descriptors, or empty list if no implementations found.

    \sa xqaiwdecl.h for constants values

    Example usage:

    \code

    #include <xqaiwdecl.h>

    #include <xqapplicationmanager.h>

    QList<XQAiwInterfaceDescriptor> list = this->mAppmgr.list(XQI_IMAGE_FETCH, "");

    //

    // Populate a user interface widget and select proper implementation via descriptor

    // ... 

    XQAiwRequest * req = this->mAppMgr.create(selectedDescriptor, XQOP_IMAGE_FETCH);

    //

    // ... the rest as usual...

    //

    \endcode

*/

QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(const QString &interface, const QString &operation)

{

    XQSERVICE_DEBUG_PRINT("XQApplicationManager::list");

    return d->list(interface, operation);

}

/*!

    List available implementations for the given \a service and \a interface names from the service registry.

    The \a operation is reserved for future use.

    \param service Service name as mentioned in the service registry file

    \param interface Interface name as mentioned in the service registry file

    \param operation The operation signature to be called.  Reserved for future use.

    \return List of found interface descriptors that matched to both the \a service and \a interface names, otherwise empty list.

    \sa list(const QString &interface, const QString &operation)

*/

QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(

    const QString &service, const QString &interface, const QString &operation)

{

    XQSERVICE_DEBUG_PRINT("XQApplicationManager::list");

    return d->list(service, interface, operation);

}

/*!

    Creates AIW request to view the  given URI (having a attached scheme).

    The interface name applied implicitly is the XQI_URI_VIEW (from xqaiwdecl.h),

    unless there is custom handling attached to URI scheme.

    The first found service implementation is applied.

    A service declares support for scheme(s) (CSV list) by adding the custom property key

    (see the constant XQCUSTOM_PROP_SCHEMES value) to the service XML.

    By default, the operation name declared by constant XQOP_URI_VIEW is used.

    Custom handling for certainsoverride the default service handling:

     - "http:" and "https: schemes are handled by QDesktopServices::openUrl()

     - "appto"  URIs is handled by corresponding Activity Manager Framework

     - "file": Local file scheme is handled via the XQI_FILE_VIEW interface