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 <QObject>

    23 #include <qglobal.h>

    24 

    25 #include "xqservicelog.h"

    26 #include "xqaiwservicedriver.h"

    27 #include "xqaiwfiledriver.h"

    28 #include "xqaiwuridriver.h"

    29 #include "xqaiwrequest.h"

    30 

    31 /*!

    32     \class XQAiwRequest

    33     \inpublicgroup QtBaseModule

    34 

    35     \ingroup ipc

    36     \brief Encapsulates the core functionality of the interworking requests

    37     

    38     The XQAiwRequest class encapsulates the core functionality of the interworking requests and hides the implementation details. 

    39     This object is created by the XQApplicationManager::create factory method.

    40     

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

    42     

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

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

    45       control comes back to requesting client.

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

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

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

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

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

    51     - List and discover services dynamically.

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

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

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

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

    56     

    57     See the "examples/appmgrclient" included in the QtHighway release for usage examples.

    58     

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

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

    61     and non-embedded usage.

    62     \code

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

    64         // Later on when caching of services

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

    66         class Client

    67         {

    68 

    69         public:

    70              // Service access

    71             bool accessService(void);

    72 

    73         private slots:

    74                 void handleOk(const QVariant &result);

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

    76         private:

    77               XQApplicationManager mAiwMgr;

    78         };

    79 

    80 

    81         //  In client.cpp

    82         bool Client::accessService(void)

    83         {

    84             QString parameter1("+3581234567890");

    85             int parameter2 = 3;

    86 

    87             bool embedded=true;  // or false

    88 

    89             XQAiwRequest *request;

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

    91             // applied.

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

    93 

    94             // If dedicated service is wanted, apply this 

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

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

    97 

    98             if (request == NULL)

    99             {

   100                 // Service not found 

   101                 return false;

   102             }

   103 

   104             // Connect result handling signal

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

   106             // Connect error handling signal or apply lastError function instead.

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

   108 

   109             // Set function parameters

   110            QList<QVariant> args;

   111            args << parameter1;

   112            args << parameter2;

   113            request->setArguments(args);

   114 

   115            // In this example, request embedded launch (window groups chained)

   116            request->setEmbedded(true);

   117 

   118            // Send the request

   119            bool res = request.send();

   120            if  (!res) 

   121            {

   122                // Request failed. 

   123               return false;

   124            }

   125          

   126            // If making multiple requests to same service, you can save the request as member variable

   127            // In this example all done.

   128            delete request;

   129            return true;

   130         }

   131 

   132         void Client::handleOk(const QVariant& result)

   133         {

   134            // Handle result here or just save them.

   135            // Result could be a service specific error code also.

   136            // 

   137         }

   138 

   139         void Client::handleError(int errorCode, const QString& errorMessage)

   140         {

   141            // Handle error

   142         }

   143     \endcode

   144     

   145     \sa XQApplicationManager

   146 */

   147 

   148 /*!

   149     Constructs interworking request to service application by the given interface \a descriptor

   150     which points to the dedicated implementation. The service application is not started during

   151     creation of the request.

   152     \param descriptor Points to the dedicated service implementation. Obtained via the XQApplicationManager::list function.

   153     \param operation Service function to be called, equals \a message parameter in XQServiceRequest.

   154     \param embedded True if window groups should be chained, false otherwise

   155     \return Constructed interworking request to service application object.

   156 */

   157 XQAiwRequest::XQAiwRequest(const XQAiwInterfaceDescriptor& descriptor, const QString &operation, bool embedded)

   158     : QObject(),

   159       currentRequest(NULL),

   160       errorMsg(),

   161       errorCode(0),

   162       completeSignalConnected(false),

   163       errorSignalConnected(false)

   164 {

   165 

   166     XQSERVICE_DEBUG_PRINT("XQAiwRequest::XQAiwRequest: %s %s,%d,%x",

   167                           qPrintable(descriptor.interfaceName()),

   168                           qPrintable(operation),

   169                           embedded,

   170                           descriptor.property(XQAiwInterfaceDescriptor::ImplementationId).toInt());

   171     

   172     // Initialize service request

   173     // The XQServiceRequest should actually accept service descriptor as input....

   174     currentRequest = new XQAiwServiceDriver(descriptor, operation);

   175     if (currentRequest)

   176     {

   177         currentRequest->setEmbedded(embedded);

   178     }

   179 }

   180 

   181 /*!

   182     Constructs interworking request to service application by the given uri and the interface \a descriptor

   183     which points to the dedicated implementation. The service application is not started during

   184     creation of the request.

   185     \param uri Uri for the given interworking request to service application.

   186     \param descriptor Points to the dedicated service implementation. Obtained via the XQApplicationManager::list function.

   187     \param operation Service function to be called, equals \a message parameter in XQServiceRequest.

   188     \return Constructed interworking request to service application object.

   189 */

   190 XQAiwRequest::XQAiwRequest(

   191     const QUrl &uri, const XQAiwInterfaceDescriptor& descriptor, const QString &operation)

   192     : QObject(),

   193       currentRequest(NULL),

   194       errorMsg(),

   195       errorCode(0),

   196       completeSignalConnected(false),

   197       errorSignalConnected(false)

   198 {

   199     XQSERVICE_DEBUG_PRINT("XQAiwRequest::XQAiwRequest (uri): %s %s,%x",

   200                           qPrintable(descriptor.interfaceName()),

   201                           qPrintable(operation),

   202                           descriptor.property(XQAiwInterfaceDescriptor::ImplementationId).toInt());

   203 

   204     if (XQAiwUriDriver::hasCustomHandler(uri))

   205     {

   206         // Custom handling goes via URI driver

   207         currentRequest = new XQAiwUriDriver(uri, descriptor, operation);

   208     }

   209     else

   210     {

   211         // Otherwise, apply service based URI access

   212         currentRequest = new XQAiwServiceDriver(descriptor, operation);

   213     }

   214     

   215 }

   216 

   217 

   218 /*!

   219     Constructs interworking request to service application by the file and the interface \a descriptor

   220     which points to the dedicated implementation. The service application is not started during

   221     creation of the request.

   222     \param file File for the given interworking request to service application.

   223     \param descriptor Points to the dedicated service implementation. Obtained via the XQApplicationManager::list function.

   224     \param operation Service function to be called, equals \a message parameter in XQServiceRequest.

   225     \return Constructed interworking request to service application object.

   226 */

   227 XQAiwRequest::XQAiwRequest(

   228     const QFile &file, const XQAiwInterfaceDescriptor& descriptor, const QString &operation)

   229     : QObject(),

   230      currentRequest(NULL),

   231       errorMsg(),

   232       errorCode(0),

   233       completeSignalConnected(false),

   234       errorSignalConnected(false)

   235 {

   236 

   237    XQSERVICE_DEBUG_PRINT("XQAiwRequest::XQAiwRequest (file): %s %x",

   238                           qPrintable(file.fileName()),

   239                           descriptor.property(XQAiwInterfaceDescriptor::ImplementationId).toInt());

   240 

   241     // Initialize file service request

   242    if (!descriptor.interfaceName().isEmpty())

   243    {

   244        // Apply normal service request

   245        XQSERVICE_DEBUG_PRINT("Apply service driver");

   246        currentRequest = new XQAiwServiceDriver(descriptor, operation);

   247    }

   248    else 

   249    {

   250        // The is no service provider for the file.

   251        // So as backup plan, apply file driver to handle non-service file launches

   252        XQSERVICE_DEBUG_PRINT("Apply file driver");

   253        currentRequest = new XQAiwFileDriver(file, descriptor, operation);

   254    }

   255        

   256 }

   257 

   258 /*!

   259     Constructs interworking request to service application by the sharable file and the interface \a descriptor

   260     which points to the dedicated implementation. The service application is not started during

   261     creation of the request.

   262     \param file Sharable file for the given interworking request to service application.

   263     \param descriptor Points to the dedicated service implementation. Obtained via the XQApplicationManager::list function.

   264     \param operation Service function to be called, equals \a message parameter in XQServiceRequest.

   265     \return Constructed interworking request to service application object.

   266 */

   267 XQAiwRequest::XQAiwRequest(

   268      const XQSharableFile &file, const XQAiwInterfaceDescriptor& descriptor, const QString &operation)

   269     : QObject(),

   270       currentRequest(NULL),

   271       errorMsg(),

   272       errorCode(0),

   273       completeSignalConnected(false),

   274       errorSignalConnected(false)

   275 {

   276 

   277     XQSERVICE_DEBUG_PRINT("XQAiwRequest::XQAiwRequest (file handle): %x",

   278                           descriptor.property(XQAiwInterfaceDescriptor::ImplementationId).toInt());

   279 

   280     // Initialize file service request

   281     if (!descriptor.interfaceName().isEmpty())

   282     {

   283        // Apply normal service request

   284         XQSERVICE_DEBUG_PRINT("Apply service driver");

   285         currentRequest = new XQAiwServiceDriver(descriptor, operation);

   286     }

   287     else 

   288     {

   289        // The is no service provider for the file.

   290        // So as backup plan, apply file driver to handle non-service file launches

   291         XQSERVICE_DEBUG_PRINT("Apply file driver");

   292         currentRequest = new XQAiwFileDriver(file, descriptor, operation);

   293     }

   294 

   295 }

   296 

   297 

   298 XQAiwRequest::~XQAiwRequest()

   299 {

   300     XQSERVICE_DEBUG_PRINT("~XQAiwRequest::XQAiwRequest");

   301 

   302     // Disconnect signals

   303     if (completeSignalConnected)

   304     {

   305         disconnect(currentRequest, SIGNAL(requestOk(const QVariant&)), this, SLOT(handleAsyncResponse(const QVariant&)));

   306     }

   307     if (errorSignalConnected)

   308     {

   309         disconnect(currentRequest, SIGNAL(requestError(int,const QString&)), this, SLOT(handleAsyncError(int)));

   310     }

   311     

   312     delete currentRequest; // Destructor cancels the async request

   313     

   314     for (int i=0; i<actionList.size(); i++)

   315     {

   316         delete actionList[i];

   317     }

   318 }

   319 

   320 /*!

   321     Create a QAction related to request from the registration data. Caller can

   322     add the action to wanted UI widget. When the action  is triggered the XQAiwRequest

   323     emits triggered() signal for caller.

   324     The XQAiwRequest owns the action (caller shall not delete the action object).

   325     \return QAction object, if there was action attached to request. Otherwise 0.

   326 */

   327 QAction *XQAiwRequest::createAction()

   328 {

   329     XQSERVICE_DEBUG_PRINT("XQAiwRequest::createAction");

   330 

   331     QAction * action = currentRequest->createAction();

   332     if (action)

   333     {

   334         if (!connect(action, SIGNAL(triggered(bool)), this, SLOT(sendFromAction(bool)))) {

   335             XQSERVICE_CRITICAL_PRINT("Failed to connect QAction triggered signal to XQAiwRequest.");

   336         }

   337         actionList.append(action);

   338         return action; 

   339     }

   340     

   341     return NULL;

   342 }

   343 

   344 /*!

   345     Set arguments for the request. This shall be called before sending

   346     add the action to wanted UI widget. For the attached action, the

   347     triggered() signal emitted by the request is the last chance to

   348     add aguments.

   349     \param arguments List of arguments that will be transferred to service provider function

   350                      to be called

   351 */

   352 void XQAiwRequest::setArguments(const QList<QVariant> &arguments)

   353 {

   354     XQSERVICE_DEBUG_PRINT("XQAiwRequest::setArguments");

   355     currentRequest->setArguments(arguments);

   356 }

   357 

   358 

   359 /*!

   360     Returns the last error code occured.

   361     IPC errors:

   362         - ENoError          = 0

   363         - EConnectionError  = -5000,  (Server might be busy)

   364         - EConnectionClosed = -4999,  

   365         - EServerNotFound   = -4998,

   366         - EIPCError         = -4997,

   367         - EUnknownError     = -4996,

   368         - ERequestPending   = -4995,  (already pending request exists)

   369         - EMessageNotFound  = -4994,

   370         - EArgumentError    = -4993

   371     \return Error code as integer value.

   372     \sa xqserviceglobal.h for error codes

   373 

   374 */

   375 int XQAiwRequest::lastError() const

   376 {

   377     int err = currentRequest->lastError();

   378     XQSERVICE_DEBUG_PRINT("XQAiwRequest::lastError %d", err);

   379     return err;

   380 }

   381 

   382 /*!

   383     Returns the last error as text for debugging purposes.

   384     The content and details of the text may vary over API

   385     development time evolution.

   386     \return Error code as QString value.

   387 */

   388 const QString& XQAiwRequest::lastErrorMessage() const

   389 {

   390     XQSERVICE_DEBUG_PRINT("XQAiwRequest::lastErrorMessage");

   391     return currentRequest->lastErrorMessage();

   392 }

   393 

   394 

   395 /*!

   396     Returns the implementation descriptor of a service attached to request.

   397     Caller can check meta-data information of the request.

   398     \return Implementation descriptor attached to the request.

   399 */

   400 const XQAiwInterfaceDescriptor &XQAiwRequest::descriptor() const 

   401 {

   402     XQSERVICE_DEBUG_PRINT("XQAiwRequest::descriptor");

   403     return currentRequest->descriptor();

   404 }

   405 

   406 /*!

   407     Starts the service application if necessary and sends request on-ward.

   408     The results are delivered via requestOk() and requestError() signals.

   409     If the request is synchronous, the client application is blocked until

   410     service provider completes the request.

   411     \return True on success, false otherwise

   412 */

   413 bool XQAiwRequest::send()

   414 {

   415     XQSERVICE_DEBUG_PRINT("XQAiwRequest::send");

   416 

   417     // do request

   418     if (sendExecute())

   419     {

   420         if (currentRequest->isSynchronous())

   421         {

   422             XQSERVICE_DEBUG_PRINT("XQAiwRequest::emit requestOk");

   423             emit requestOk(result);

   424             result.clear();

   425         }

   426         return true;

   427     } else

   428     {

   429         XQSERVICE_DEBUG_PRINT("XQAiwRequest::emit requestError");

   430         emit requestError(lastError(), lastErrorMessage());

   431         return false;

   432     }

   433 }

   434 

   435 

   436 /*!

   437     Convinience method for sending a synchronous request on-ward.

   438     The returnValue delivered via the output parameter.

   439     \return True on success, false otherwise

   440 */

   441 bool XQAiwRequest::send(QVariant &returnValue)

   442 {

   443 

   444     XQSERVICE_DEBUG_PRINT("XQAiwRequest::send(retValue)");

   445 

   446     // do request

   447     if (sendExecute())

   448     {

   449         if (currentRequest->isSynchronous())

   450         {

   451             XQSERVICE_DEBUG_PRINT("XQAiwRequest::set retValue ");

   452             // Do not emit requestOk as return value delivered directly

   453             returnValue = result; // Copy return value

   454             result.clear();

   455         }

   456         return true;

   457     } else

   458     {

   459         XQSERVICE_DEBUG_PRINT("XQAiwRequest::emit requestError");

   460         emit requestError(lastError(), lastErrorMessage());

   461         return false;

   462     }

   463    

   464 }

   465 

   466 /*!

   467     Request service application to be launched in embedded mode.

   468     \param embedded If set to true, service application will be launched

   469                     in embedded mode

   470 */

   471 void XQAiwRequest::setEmbedded(bool embedded)

   472 {

   473     XQSERVICE_DEBUG_PRINT("XQAiwRequest::setEmbedded=%d",embedded);

   474     currentRequest->setEmbedded(embedded);

   475 }

   476 

   477 /*!

   478     Get the value of embedded option of the request.

   479     \return True if request is set to launch service application in embedded

   480             mode, false otherwise

   481 */

   482 bool XQAiwRequest::isEmbedded() const

   483 {

   484     XQSERVICE_DEBUG_PRINT("XQAiwRequest::isEmbedded");

   485     return currentRequest->isEmbedded();

   486 }

   487 

   488 /*!

   489     Sets service operation. The XQApplicationManager::create() functions for

   490     files and URLs set the default operation, but it can be overriden using

   491     this function.

   492     \param operation Operation to be set to the request.

   493 */

   494 void XQAiwRequest::setOperation(const QString &operation)

   495 {

   496     XQSERVICE_DEBUG_PRINT("XQAiwRequest::setOperation");

   497     currentRequest->setOperation(operation);

   498 }

   499 

   500 /*!

   501     Returns operation attached to the request.

   502     \return Operation attached to the request

   503 */

   504 const QString &XQAiwRequest::operation() const

   505 {

   506     XQSERVICE_DEBUG_PRINT("XQAiwRequest::operation");

   507     return currentRequest->operation();

   508 }

   509 

   510 /*!

   511     Sets request as synchronous or asynchronous, based on the \a synchronous value.

   512     \param synchronous If set to true, request will be synchronous.

   513                        If set to false, request will be asynchronous

   514 */

   515 void XQAiwRequest::setSynchronous(bool synchronous)

   516 {

   517     XQSERVICE_DEBUG_PRINT("XQAiwRequest::setSynchronous=%d", synchronous);

   518     currentRequest->setSynchronous(synchronous);

   519 }

   520 

   521 /*!

   522     Returns the value of the synchronous option.

   523     \return True if request is synchronous, false otherwise

   524 */

   525 bool XQAiwRequest::isSynchronous() const

   526 {

   527     XQSERVICE_DEBUG_PRINT("XQAiwRequest::isSynchronous");

   528     return currentRequest->isSynchronous();

   529 }

   530 

   531 /*!

   532     Requests service application to be launched to background initially,

   533     or if already running, to go to background.

   534     \param background If set to true, service application will be launched

   535                       to background

   536 */

   537 void XQAiwRequest::setBackground(bool background )

   538 {

   539     XQSERVICE_DEBUG_PRINT("XQAiwRequest::setbackground=%d", background);

   540     currentRequest->setBackground(background);

   541 }

   542 

   543 /*!

   544     Returns the value of the background option.

   545     \return True if request is set to launch service

   546                  application to background

   547 */

   548 bool XQAiwRequest::isBackground() const

   549 {

   550     XQSERVICE_DEBUG_PRINT("XQAiwRequest::isBackground");

   551     return currentRequest->isBackground();

   552 }

   553 

   554 /*!

   555     Used to set additional UI behavior type options to the request.

   556     Embedded and background options are handled by their own functions.

   557     This function should not be used to implement additional data

   558     parameters for operations!

   559     \param info UI bahavior type option to be set to the request.

   560 */

   561 void XQAiwRequest::setInfo(const XQRequestInfo &info)

   562 {

   563     XQSERVICE_DEBUG_PRINT("XQAiwRequest::setInfo");

   564     return currentRequest->setInfo(info);

   565 }

   566 

   567 /*!

   568     Returns additional options attached to the request.

   569     \return Additional options attached to the request.

   570 */

   571 XQRequestInfo XQAiwRequest::info() const

   572 {

   573     XQSERVICE_DEBUG_PRINT("XQAiwRequest::info");

   574     return currentRequest->info();

   575 }

   576 

   577 

   578 

   579 const QVariant &XQAiwRequest::results() const

   580 {

   581     XQSERVICE_DEBUG_PRINT("XQAiwRequest::results");

   582     return result;

   583 }

   584 

   585 

   586 void XQAiwRequest::sendFromAction(bool checked)

   587 {

   588     Q_UNUSED(checked);

   589     

   590     XQSERVICE_DEBUG_PRINT("XQAiwRequest::sendFromAction");

   591     

   592     emit triggered(); // Last chance to setup request parameters

   593 

   594     // do request

   595     if (sendExecute())

   596     {

   597         if (isSynchronous())

   598         {

   599             emit requestOk(result);

   600             result.clear();

   601         }

   602     } else

   603     {

   604         emit requestError(lastError(), lastErrorMessage());

   605     }

   606 }

   607 

   608 bool XQAiwRequest::sendExecute()

   609 {

   610     XQSERVICE_DEBUG_PRINT("XQAiwRequest::sendExecute>>>");

   611 

   612     QStringList list;

   613     bool res = true;

   614     if (!isSynchronous() && !completeSignalConnected)

   615     {

   616         // Set async request signals once

   617         XQSERVICE_DEBUG_PRINT("request::async send");

   618         connect(currentRequest, SIGNAL(requestOk(const QVariant&)), this, SLOT(handleAsyncResponse(const QVariant&)));

   619         completeSignalConnected = true;

   620     }

   621     if (!errorSignalConnected)

   622     {

   623         // Connect always error signal  once

   624         connect(currentRequest, SIGNAL(requestError(int,const QString&)), this, SLOT(handleAsyncError(int)));

   625         errorSignalConnected = true;

   626     }

   627     

   628     XQSERVICE_DEBUG_PRINT("request::send>>>");

   629     res = currentRequest->send(result);  // Result is valid for sync request only    

   630     XQSERVICE_DEBUG_PRINT("request::send: %d<<<", res);

   631     

   632     errorCode = currentRequest->lastError(); // ask always

   633     if (errorCode || !res)

   634     {

   635         res = false;

   636     }

   637     

   638     XQSERVICE_DEBUG_PRINT("XQAiwRequest::sendExecute: %d<<<", res);

   639     

   640     return res;

   641 

   642 }

   643 

   644 

   645 

   646 void XQAiwRequest::handleAsyncResponse(const QVariant& value)

   647 {

   648     XQSERVICE_DEBUG_PRINT("XQAiwRequest::handleAsyncResponse");

   649     emit requestOk(value);

   650 }

   651 

   652 void XQAiwRequest::handleAsyncError(int err)

   653 {

   654    XQSERVICE_DEBUG_PRINT("XQAiwRequest::handleAsyncError");

   655    errorCode = err;

   656    emit requestError(lastError(), lastErrorMessage());

   657 }