1 /*

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

     3 * All rights reserved.

     4 *

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

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

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

     8 * 

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

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

    11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    12 * GNU Lesser General Public License for more details.

    13 *

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

    15 * along with this program.  If not, 

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

    17 *

    18 * Description:

    19 *

    20 */

    21 

    22 #include "xqservicelog.h"

    23 #include "xqappmgr.h"

    24 #include <xqaiwrequest.h>

    25 #include <xqaiwinterfacedescriptor.h>

    26 #include <QList>

    27 #include "xqappmgr_p.h"

    28 

    29 /*!

    30     \class XQApplicationManager

    31     \inpublicgroup QtBaseModule

    32 

    33     \ingroup ipc

    34     \brief Factory class to list interface descriptors and create interworking objects (XQAiwRequest)

    35     

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

    37     create interworking objects (XQAiwRequest).

    38     

    39     This class is a part of API to be used by the applications instead of using XQServiceRequest directly.

    40     

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

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

    43       control comes back to requesting client.

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

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

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

    47     - 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.

    48     - Launched service provider application (.exe) if not already running when client makes service call to it.

    49     - List and discover services dynamically.

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

    51     - Opening files to be viewed by a file viewing interface.

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

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

    54     

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

    56     

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

    58     and non-embedded usage:

    59     \code

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

    61         // Later on when caching of services

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

    63         class Client

    64         {

    65 

    66         public:

    67              // Service access

    68             bool accessService(void);

    69 

    70         private slots:

    71                 void handleOk(const QVariant &result);

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

    73         private:

    74               XQApplicationManager mAiwMgr;

    75         };

    76 

    77 

    78         //  In client.cpp

    79         bool Client::accessService(void)

    80         {

    81             QString parameter1("+3581234567890");

    82             int parameter2 = 3;

    83 

    84             bool embedded=true;  // or false

    85 

    86             XQAiwRequest *request;

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

    88             // applied.

    89             request = mAiwMgr.create("Interface", "functionName2(QString, int)", embedded);

    90 

    91             // If dedicated service is wanted, apply this 

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

    93             //                          "functionName2(QString, int)", embedded);

    94 

    95             if (request == NULL)

    96             {

    97                 // Service not found 

    98                 return false;

    99             }

   100             // ... Perform further processing

   101         }

   102     \endcode

   103     

   104     Access service by descriptor:

   105     \code

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

   107 

   108        // Display service in UI and make selection possible.

   109         foreach (XQAiwInterfaceDescriptor d, implementations)

   110         {

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

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

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

   114         }

   115 

   116 

   117         // Select correct implementation

   118         XQAiwInterfaceDescriptor selectedImpl = doSelectService();

   119 

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

   121         // via application mgr.

   122 

   123         // ...See previous example

   124         request = mAiwMgr.create(selectedImpl, embedded);

   125         // ....See previous example

   126     \endcode

   127     

   128     The XQApplicationManager supports opening activity (see Terminology) URIs (appto scheme) as fire-and-forget mannner:

   129     \code

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

   131 

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

   133         // via application mgr.

   134         request = mAiwMgr.create(url);

   135         if (request == NULL)

   136         {

   137             // No handlers for the URI

   138             return;

   139         }

   140 

   141         // Set function parameters

   142         QList<QVariant> args;

   143         args << uri.toSring();

   144         request->setArguments(args);

   145 

   146         // Send the request

   147         bool res = request.send();

   148         if  (!res) 

   149         {

   150             // Request failed. 

   151             int error = request->lastError();

   152             // Handle error

   153         }

   154      

   155        // All done.

   156        delete request;

   157     \endcode

   158     

   159     \sa XQAiwRequest

   160 */

   161 

   162 XQApplicationManager::XQApplicationManager()

   163 {

   164     XQSERVICE_DEBUG_PRINT("XQApplicationManager::XQApplicationManager");

   165     d = new XQApplicationManagerPrivate();

   166     

   167 }

   168 XQApplicationManager::~XQApplicationManager()

   169 {

   170     XQSERVICE_DEBUG_PRINT("XQApplicationManager::~XQApplicationManager");

   171     delete d;

   172 };

   173 

   174 /*!

   175     Creates AIW request by interface and operation name.

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

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

   178     to select the correct implementation. 

   179     

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

   181                      Apply the xqaiwdecl.h file for common constants.

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

   183                      Can be set later via XQAiwRequest::setOperation.

   184                      Apply the xqaiwdecl.h file for common constants.

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

   186                     Can be set later via XQAiwRequest::setEmbedded.

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

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

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

   190     \sa xqaiwdecl.h for constants values

   191     

   192     Example usage:

   193     \code

   194     #include <xqaiwdecl.h>

   195     #include <xqapplicationmanager.h>

   196     

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

   198     

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

   200     if (req)

   201     {

   202         // There was service available

   203         QList<QVariant> args;

   204         args << folder;

   205         args << previewOn;

   206         req->setArguments(args);

   207         

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

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

   210 

   211         req->send();

   212     }

   213     \endcode

   214 */

   215 XQAiwRequest* XQApplicationManager::create(

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

   217 {

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

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

   220 }

   221 

   222 

   223 /*!

   224     Creates AIW request by interface implementation descriptor and operation name.

   225     The descriptor is got from the list() call.

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

   227     the descriptor points to one implementation and thus selects correct

   228     implementation.

   229     

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

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

   232                      Can be set later via XQAiwRequest::setOperation.

   233                      Apply the xqaiwdecl.h file for common constants.

   234     \param embedded True if embedded call, false otherwise.

   235                      Can be set later via XQAiwRequest::setEmbedded.

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

   237     \sa list()

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

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

   240     \sa xqaiwdecl.h for constants values

   241 

   242     Example usage:

   243     \code

   244     #include <xqaiwdecl.h>

   245     #include <xqapplicationmanager.h>

   246     

   247     XQApplicationManager appMgr;  // Prefer one instance only 

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

   249     //

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

   251     // ... 

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

   253     //

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

   255     //

   256     \endcode

   257 */

   258 XQAiwRequest* XQApplicationManager::create(

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

   260 {

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

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

   263 }

   264 

   265 

   266 /*!

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

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

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

   270     implementation.

   271     

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

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

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

   275                      Can be set later via XQAiwRequest::setOperation.

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

   277                      Can be set later via XQAiwRequest::setEmbedded.

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

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

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

   281     \sa xqaiwdecl.h for constants values

   282 

   283     Example usage:

   284     \code

   285     #include <xqaiwdecl.h>

   286     #include <xqapplicationmanager.h>

   287 

   288     #include <xqappmgr.h>;

   289     #include "componentglobal.h";

   290 

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

   292 

   293     // Use embedded call.

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

   295     if (req)

   296     {

   297         ...

   298     }

   299     \endcode

   300 */

   301 XQAiwRequest* XQApplicationManager::create(

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

   303 {

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

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

   306 }

   307 

   308 /*!

   309     List implementation descriptors by interface name.

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

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

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

   313     \sa xqaiwdecl.h for constants values

   314 

   315     Example usage:

   316     \code

   317     #include <xqaiwdecl.h>

   318     #include <xqapplicationmanager.h>

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

   320     //

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

   322     // ... 

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

   324     //

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

   326     //

   327     \endcode

   328 */

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

   330 {

   331     XQSERVICE_DEBUG_PRINT("XQApplicationManager::list");

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

   333 }

   334 

   335 /*!

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

   337     The \a operation is reserved for future use.

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

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

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

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

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

   343 */

   344 QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(

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

   346 {

   347     XQSERVICE_DEBUG_PRINT("XQApplicationManager::list");

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

   349 }

   350 

   351 /*!

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

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

   354     unless there is custom handling attached to URI scheme.

   355     The first found service implementation is applied.

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

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

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

   359     Custom handling for certainsoverride the default service handling:

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

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

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

   363                (the same as applie to e.g. create(QFile))

   364          

   365     \param uri The URI to be viewed

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

   367     \return The application interworking request instance, or NULL if no URI viewer found.

   368     \sa xqaiwdecl.h for constants values

   369 */

   370 XQAiwRequest* XQApplicationManager::create( const QUrl &uri, bool embedded)

   371 {

   372     XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(url)");

   373     return d->create(uri, NULL, embedded);

   374 }

   375 

   376 /*!

   377     Creates AIW request to view the given URI by service implementation.

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

   379     unless there is custom handling attached to URI scheme.

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

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

   382     Custom handling for certainsoverride the default service handling:

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

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

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

   386                (the same as applie to e.g. create(QFile))

   387 

   388     \param uri The URI to be viewed

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

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

   391     \return The application interworking request instance, or NULL if no URI viewer found.

   392     \sa xqaiwdecl.h for constants values

   393 */

   394 XQAiwRequest* XQApplicationManager::create(

   395     const QUrl &uri, const XQAiwInterfaceDescriptor& implementation, bool embedded)

   396 {

   397     XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(uri+impl)");

   398     return d->create(uri, &implementation, embedded);

   399 }

   400 

   401 /*!

   402     Create AIW requests to view the given file and having the MIME type attached.

   403     The interface name applied implicitly is declared by the constant XQI_FILE_VIEW

   404     The first found service implementation is applied.

   405     \param file The file to be viewed

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

   407     \return The application interworking request instance, or NULL if no viewer found.

   408     \sa xqaiwdecl.h for constants values

   409 */

   410 XQAiwRequest* XQApplicationManager::create( const QFile &file, bool embedded)

   411 {

   412     XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(file)");

   413     return d->create(file, NULL, embedded);

   414 }

   415 

   416 /*!

   417     Same as basic create(const QFile &file, bool embedded), but applies the interface descriptor to select the dedicated implementation.

   418     \param file The file to be viewed

   419     \param implementation Valid interface descriptor obtained by the list(const QFile &file) call.

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

   421     \return The application interworking request instance, or NULL if no viewer found.

   422     \sa xqaiwdecl.h for constants values

   423 */

   424 XQAiwRequest* XQApplicationManager::create(

   425     const QFile &file, const XQAiwInterfaceDescriptor& implementation, bool embedded)

   426 {

   427     XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(file+impl)");

   428     return d->create(file, &implementation, embedded);

   429 }

   430 

   431 

   432 /*!

   433     List implementations that support handling the URI scheme of the given uri.

   434     The interface name applied implicitly is declared by the constant XQI_URI_VIEW.

   435     \param uri The URI scheme that should be matched to the interface

   436     \return List of found interface descriptors that matched to the URI scheme, otherwise empty list.

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

   438 */

   439 

   440 QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(const QUrl &uri)

   441 {

   442     XQSERVICE_DEBUG_PRINT("XQApplicationManager::list(uri)");

   443     return d->list(uri);

   444 }

   445 

   446 /*!

   447     List implementations that support handling the MIME type of the given file.

   448     The interface name applied implicitly is declared by the constant XQI_FILE_VIEW.

   449     \param file File which MIME type should be supported by the interface.

   450     \return List of found interface descriptors for applications that can handle the file, otherwise empty list.

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

   452 */

   453 QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(const QFile &file)

   454 {

   455     XQSERVICE_DEBUG_PRINT("XQApplicationManager::list(file)");

   456     return d->list(file);

   457 }

   458 

   459 /*!

   460     List implementations that support handling the MIME type of of the given sharable file.

   461     The interface name applied implicitly is declared by the constant XQI_FILE_VIEW.

   462     \param file Sharable file which MIME type should be supported by the interface.

   463     \return List of found interface descriptors for applications that can handle the file, otherwise empty list.

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

   465 */

   466 QList<XQAiwInterfaceDescriptor> XQApplicationManager::list(const XQSharableFile &file)

   467 {

   468     XQSERVICE_DEBUG_PRINT("XQApplicationManager::list(XQSharableFile)");

   469     return d->list(file);

   470 }

   471 

   472 /*!

   473     Create AIW request for the given file and the MIME type attached to the sharable file

   474     The interface name applied implicitly is declared by the constant XQI_FILE_VIEW

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

   476     \param file The sharable file to be viewed

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

   478     \return The application interworking request instance, or NULL if no viewer found.

   479 */

   480 XQAiwRequest* XQApplicationManager::create(const XQSharableFile &file, bool embedded)

   481 {

   482     XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(XQSharableFile)");

   483     return d->create(file, NULL, embedded);

   484 }

   485 

   486 /*!

   487     Same as basic create(const XQSharableFile &file, bool embedded), but applies the interface descriptor to select the dedicated implementation.

   488     \param file The sharable file to be viewed

   489     \param implementation Valid interface descriptor obtained by the list(const XQSharableFile &file) call.

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

   491     \return The application interworking request instance, or NULL if no viewer found.

   492     \sa xqaiwdecl.h for constants values

   493 */

   494 XQAiwRequest* XQApplicationManager::create(

   495     const XQSharableFile &file, const XQAiwInterfaceDescriptor& implementation, bool embedded)

   496 {

   497     XQSERVICE_DEBUG_PRINT("XQApplicationManager::create(XQSharableFile+impl)");

   498     return d->create(file, &implementation, embedded);

   499 }

   500 

   501 /*!

   502     Returns error code of the last performed operation.

   503     \return Error code of the last operation, 0 if no error occured.

   504 */

   505 int XQApplicationManager::lastError() const

   506 {

   507     XQSERVICE_DEBUG_PRINT("XQApplicationManager::lastError");

   508     return d->lastError();

   509 }

   510 

   511 /*!

   512     Tests whether given implementation is running. That is, the service provider has published

   513     the full service name attached to the given interface descriptor.

   514     \param implementation Interface that is tested for being run.

   515     \return True if the implementation is running, false otherwise.

   516 */

   517 bool XQApplicationManager::isRunning(const XQAiwInterfaceDescriptor& implementation) const

   518 {

   519     XQSERVICE_DEBUG_PRINT("XQApplicationManager::isRunning");

   520     return d->isRunning(implementation);

   521 }

   522 

   523 /*!

   524     Gets the values of the DRM related \a attributeNames, like "IsProtected",

   525     "IsForwardable", "MimeType" for a given \a file.

   526     \param file File for which DRM attributes are retrieved

   527     \param attributeNames List of attributes that should be retrieved (check #DrmAttribute)

   528     \param attributeValues On success fills this list whith values, where each value is QVariant of the integer or string type.

   529                            If attribute value does not exists or other error occurs when reading the attribute, the invalid QVariant

   530                            value is returned.

   531     \return True on success, upon error returns false (e.g file does not exists or other general error).

   532 */

   533 bool XQApplicationManager::getDrmAttributes(const QFile &file, const QList<int> &attributeNames, QVariantList &attributeValues)

   534 {

   535     XQSERVICE_DEBUG_PRINT("XQApplicationManager::drmAttributes (file)");

   536     return d->getDrmAttributes(file, attributeNames, attributeValues);

   537 }

   538 

   539 /*!

   540     Gets the values of the DRM related \a attributeNames, like "IsProtected",

   541     "IsForwardable", "MimeType" for a given sharable file.

   542     \param file Sharable file for which DRM attributes are retrieved

   543     \param attributeNames List of attributes that should be retrieved (check #DrmAttribute)

   544     \param attributeValues On success fills this list whith values, where each value is QVariant of the integer or string type.

   545                            If attribute value does not exists or other error occurs when reading the attribute, the invalid QVariant

   546                            value is returned.

   547     \return True on success, upon error returns false (e.g file does not exists or other general error).

   548 */

   549 bool XQApplicationManager::getDrmAttributes(const XQSharableFile &file, const QList<int> &attributeNames, QVariantList &attributeValues)

   550 {

   551     XQSERVICE_DEBUG_PRINT("XQApplicationManager::drmAttributes (XQSharableFile)");

   552     return d->getDrmAttributes(file, attributeNames, attributeValues);

   553 }

   554 

   555 /*!

   556     Checks the status of the given service interface.

   557     \param implementation Interface which status is being checked.

   558     \return Status of the service.

   559 */

   560 XQApplicationManager::ServiceStatus XQApplicationManager::status(const XQAiwInterfaceDescriptor& implementation)

   561 {

   562     XQSERVICE_DEBUG_PRINT("XQApplicationManager::status");

   563     return (ServiceStatus)d->status(implementation);

   564 }

   565 

   566