qthighway/xqservice/src/xqappmgr.cpp
branchRCL_3
changeset 9 5d007b20cfd0
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/qthighway/xqservice/src/xqappmgr.cpp	Tue Aug 31 16:02:37 2010 +0300
@@ -0,0 +1,566 @@
+/*
+* 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
+    \brief Factory class to list interface descriptors and create interworking objects (XQAiwRequest)
+    
+    XQApplicationManager lists interface descriptors by interface and /or service name. It is also used to
+    create interworking objects (XQAiwRequest).
+    
+    This class is a part of API to be used by the applications instead of using XQServiceRequest directly.
+    
+    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.
+    - Launched service provider application (.exe) if not already running when client makes service call to it.
+    - List and discover services dynamically.
+    - Apply UI related options upon service launch, like "launch as embedded", "launch to foreground" and "launch to backround".
+    - Opening files to be viewed by a file viewing interface.
+    - 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
+        // Later on when caching of services
+        // 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.
+            request = mAiwMgr.create("Interface", "functionName2(QString, int)", embedded);
+
+            // If dedicated service is wanted, apply this 
+            // request = mAiwMgr.create("Service", "Interface", 
+            //                          "functionName2(QString, int)", embedded);
+
+            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
+    
+    The XQApplicationManager supports opening activity (see Terminology) URIs (appto scheme) as fire-and-forget mannner:
+    \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;
+        args << uri.toSring();
+        request->setArguments(args);
+
+        // Send the request
+        bool res = request.send();
+        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
+               (the same as applie to e.g. create(QFile))
+         
+    \param uri The URI to be viewed
+    \param embedded True if embedded (window groups chained) call, false otherwise
+    \return The application interworking request instance, or NULL if no URI viewer found.
+    \sa xqaiwdecl.h for constants values
+*/
+XQAiwRequest* XQApplicationManager::create( const QUrl &uri, bool embedded)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(url)");
+    return d->create(uri, NULL, embedded);
+}
+
+/*!
+    Creates AIW request to view the given URI by service implementation.
+    The interface name applied implicitly is the XQI_URI_VIEW (from xqaiwdecl.h),
+    unless there is custom handling attached to URI scheme.
+    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.
+    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
+               (the same as applie to e.g. create(QFile))
+
+    \param uri The URI to be viewed
+    \param embedded True if embedded (window groups chained) call, false otherwise
+    \param implementation Valid interface descriptor obtained by the "list(QUrl)" call.
+    \return The application interworking request instance, or NULL if no URI viewer found.
+    \sa xqaiwdecl.h for constants values
+*/
+XQAiwRequest* XQApplicationManager::create(
+    const QUrl &uri, const XQAiwInterfaceDescriptor& implementation, bool embedded)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(uri+impl)");
+    return d->create(uri, &implementation, embedded);
+}
+
+/*!
+    Create AIW requests to view the given file and having the MIME type attached.
+    The interface name applied implicitly is declared by the constant XQI_FILE_VIEW
+    The first found service implementation is applied.
+    \param file The file to be viewed
+    \param embedded True if embedded (window groups chained) call, false otherwise
+    \return The application interworking request instance, or NULL if no viewer found.
+    \sa xqaiwdecl.h for constants values
+*/
+XQAiwRequest* XQApplicationManager::create( const QFile &file, bool embedded)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(file)");
+    return d->create(file, NULL, embedded);
+}
+
+/*!
+    Same as basic create(const QFile &file, bool embedded), but applies the interface descriptor to select the dedicated implementation.
+    \param file The file to be viewed
+    \param implementation Valid interface descriptor obtained by the list(const QFile &file) call.
+    \param embedded True if embedded (window groups chained) call, false otherwise
+    \return The application interworking request instance, or NULL if no viewer found.
+    \sa xqaiwdecl.h for constants values
+*/
+XQAiwRequest* XQApplicationManager::create(
+    const QFile &file, const XQAiwInterfaceDescriptor& implementation, bool embedded)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(file+impl)");
+    return d->create(file, &implementation, embedded);
+}
+
+
+/*!
+    List implementations that support handling the URI scheme of the given uri.
+    The interface name applied implicitly is declared by the constant XQI_URI_VIEW.
+    \param uri The URI scheme that should be matched to the interface
+    \return List of found interface descriptors that matched to the URI scheme, otherwise empty list.
+    \sa list(const QString &interface, const QString &operation)
+*/
+
+QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(const QUrl &uri)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::list(uri)");
+    return d->list(uri);
+}
+
+/*!
+    List implementations that support handling the MIME type of the given file.
+    The interface name applied implicitly is declared by the constant XQI_FILE_VIEW.
+    \param file File which MIME type should be supported by the interface.
+    \return List of found interface descriptors for applications that can handle the file, otherwise empty list.
+    \sa list(const QString &interface, const QString &operation)
+*/
+QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(const QFile &file)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::list(file)");
+    return d->list(file);
+}
+
+/*!
+    List implementations that support handling the MIME type of of the given sharable file.
+    The interface name applied implicitly is declared by the constant XQI_FILE_VIEW.
+    \param file Sharable file which MIME type should be supported by the interface.
+    \return List of found interface descriptors for applications that can handle the file, otherwise empty list.
+    \sa list(const QString &interface, const QString &operation)
+*/
+QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(const XQSharableFile &file)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::list(XQSharableFile)");
+    return d->list(file);
+}
+
+/*!
+    Create AIW request for the given file and the MIME type attached to the sharable file
+    The interface name applied implicitly is declared by the constant XQI_FILE_VIEW
+    By default, the operation name declared by constant XQOP_FILE_VIEW_SHARABLE is used.
+    \param file The sharable file to be viewed
+    \param embedded True if embedded (window groups chained) call, false otherwise
+    \return The application interworking request instance, or NULL if no viewer found.
+*/
+XQAiwRequest* XQApplicationManager::create(const XQSharableFile &file, bool embedded)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(XQSharableFile)");
+    return d->create(file, NULL, embedded);
+}
+
+/*!
+    Same as basic create(const XQSharableFile &file, bool embedded), but applies the interface descriptor to select the dedicated implementation.
+    \param file The sharable file to be viewed
+    \param implementation Valid interface descriptor obtained by the list(const XQSharableFile &file) call.
+    \param embedded True if embedded (window groups chained) call, false otherwise
+    \return The application interworking request instance, or NULL if no viewer found.
+    \sa xqaiwdecl.h for constants values
+*/
+XQAiwRequest* XQApplicationManager::create(
+    const XQSharableFile &file, const XQAiwInterfaceDescriptor& implementation, bool embedded)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(XQSharableFile+impl)");
+    return d->create(file, &implementation, embedded);
+}
+
+/*!
+    Returns error code of the last performed operation.
+    \return Error code of the last operation, 0 if no error occured.
+*/
+int XQApplicationManager::lastError() const
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::lastError");
+    return d->lastError();
+}
+
+/*!
+    Tests whether given implementation is running. That is, the service provider has published
+    the full service name attached to the given interface descriptor.
+    \param implementation Interface that is tested for being run.
+    \return True if the implementation is running, false otherwise.
+*/
+bool XQApplicationManager::isRunning(const XQAiwInterfaceDescriptor& implementation) const
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::isRunning");
+    return d->isRunning(implementation);
+}
+
+/*!
+    Gets the values of the DRM related \a attributeNames, like "IsProtected",
+    "IsForwardable", "MimeType" for a given \a file.
+    \param file File for which DRM attributes are retrieved
+    \param attributeNames List of attributes that should be retrieved (check #DrmAttribute)
+    \param attributeValues On success fills this list whith values, where each value is QVariant of the integer or string type.
+                           If attribute value does not exists or other error occurs when reading the attribute, the invalid QVariant
+                           value is returned.
+    \return True on success, upon error returns false (e.g file does not exists or other general error).
+*/
+bool XQApplicationManager::getDrmAttributes(const QFile &file, const QList<int> &attributeNames, QVariantList &attributeValues)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::drmAttributes (file)");
+    return d->getDrmAttributes(file, attributeNames, attributeValues);
+}
+
+/*!
+    Gets the values of the DRM related \a attributeNames, like "IsProtected",
+    "IsForwardable", "MimeType" for a given sharable file.
+    \param file Sharable file for which DRM attributes are retrieved
+    \param attributeNames List of attributes that should be retrieved (check #DrmAttribute)
+    \param attributeValues On success fills this list whith values, where each value is QVariant of the integer or string type.
+                           If attribute value does not exists or other error occurs when reading the attribute, the invalid QVariant
+                           value is returned.
+    \return True on success, upon error returns false (e.g file does not exists or other general error).
+*/
+bool XQApplicationManager::getDrmAttributes(const XQSharableFile &file, const QList<int> &attributeNames, QVariantList &attributeValues)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::drmAttributes (XQSharableFile)");
+    return d->getDrmAttributes(file, attributeNames, attributeValues);
+}
+
+/*!
+    Checks the status of the given service interface.
+    \param implementation Interface which status is being checked.
+    \return Status of the service.
+*/
+XQApplicationManager::ServiceStatus XQApplicationManager::status(const XQAiwInterfaceDescriptor& implementation)
+{
+    XQSERVICE_DEBUG_PRINT("XQApplicationManager::status");
+    return (ServiceStatus)d->status(implementation);
+}
+
+