26 #include <QByteArray> |
26 #include <QByteArray> |
27 |
27 |
28 #include <xqserviceadaptor.h> |
28 #include <xqserviceadaptor.h> |
29 //#include <xqserviceservice.h> |
29 //#include <xqserviceservice.h> |
30 #include <xqserviceutil.h> |
30 #include <xqserviceutil.h> |
|
31 #include "xqrequestutil.h" |
31 |
32 |
32 /*! |
33 /*! |
33 \class ServiceAdaptorProxy |
34 \class ServiceAdaptorProxy |
34 \brief Proxy class for converting signal and slot members into IPC message names |
35 \brief Proxy class for converting signal and slot members into IPC message names |
35 */ |
36 */ |
104 |
105 |
105 /*! |
106 /*! |
106 \class XQServiceProvider |
107 \class XQServiceProvider |
107 \inpublicgroup QtBaseModule |
108 \inpublicgroup QtBaseModule |
108 |
109 |
109 \brief The XQServiceProvider class provides an interface to messages on a XQService service |
110 \brief Base class of the Qt Extension's service framework for implementing out-of-process service providers. |
110 which simplifies remote slot invocations |
111 It supports implementing out-of-process slots that can be invoked from remote service clients |
111 |
112 |
|
113 See \ref terminology for terms used in this documentation. |
|
114 |
112 Service messages consist of a service name, a message name, and a list of parameter values. |
115 Service messages consist of a service name, a message name, and a list of parameter values. |
113 Qt extension dispatches service messages to the applications associated with the service |
116 Qt extension dispatches service messages to the applications associated with the service |
114 name, on the application's \c{QPE/Application/appname} channel, where |
117 name, on the application's \c{QPE/Application/appname} channel, where |
115 \c{appname} is the application's name. |
118 \c{appname} is the application's name. |
116 |
119 |
117 <b>Service registration</b> \n |
120 <b>Service registration</b> \n |
118 Service provider need to register it's service into the system before they can be used by |
121 Service provider need to register it's service into the system before they can be used by |
119 the service client. Registration is done by creating a XML formatted service configuration |
122 the service client. Registration is done by creating a XML formatted service configuration |
120 file and defining the service in the provider's .pro-file. QMake will notice service provider |
123 file and defining the service in the provider's .pro-file. QMake will notice service provider |
121 from the .pro-file, with help of the service.prf file, and generate a make file that uses |
124 from the .pro-file, with help of the service.prf file, and generate necessary resources for |
122 a helper application xqsreg.exe. The helper application sqsreg.exe will generate an application |
125 the Symbian application registry. The helper application sqsreg.exe will generate an application |
123 registration resource file ( _reg.rss) from the configuration-file and provider's definitions |
126 registration resource file ( _reg.rss) from the configuration-file and provider's definitions |
124 that include the needed declarations for the services provided. |
127 that include the needed declarations for the services provided. |
125 |
128 |
126 <b>Service Names Allocation</b> \n |
129 <b>Service Names Allocation</b> \n |
127 The harmonize service and interface names the Symba specific names and guidelines can be found |
130 The harmonize service and interface names the Symba specific names and guidelines can be found |
171 <ELEMENT version ( #PCDATA ) > |
174 <ELEMENT version ( #PCDATA ) > |
172 <ELEMENT customproperty ( #CDATA ) > |
175 <ELEMENT customproperty ( #CDATA ) > |
173 <ATTLIST customproperty key NMTOKEN #REQUIRED > |
176 <ATTLIST customproperty key NMTOKEN #REQUIRED > |
174 \endcode |
177 \endcode |
175 |
178 |
176 Also the old format described below is supported, With old format you can not have custom properties, which |
|
177 for example are used for AIW purposes. |
|
178 \code |
|
179 <ELEMENT service ( description?, interface+ ) > |
|
180 <ATTLIST service name #CDATA #REQUIRED > |
|
181 <ATTLIST service filepath #CDATA #REQUIRED > |
|
182 <ELEMENT description ( #CDATA ) > |
|
183 <ELEMENT interface ( description? ) > |
|
184 <ATTLIST interface '''name''' #CDATA #REQUIRED > |
|
185 <ATTLIST interface version #CDATA #REQUIRED > |
|
186 <ATTLIST interface capabilities #CDATA #REQUIRED > |
|
187 \endcode |
|
188 |
|
189 <b>Changing service or interface names</b> \n |
179 <b>Changing service or interface names</b> \n |
190 Before you think about changing the name of the already released and used service implementation, read this |
180 Before you think about changing the name of the already released and used service implementation, read this |
191 http://s60wiki.nokia.com/S60Wiki/QtFw_for_S60_coding_conventions/Service_name_registry#About_changing_service_or_interface_names |
181 http://s60wiki.nokia.com/S60Wiki/QtFw_for_S60_coding_conventions/Service_name_registry#About_changing_service_or_interface_names |
192 first. |
182 first. |
193 |
183 |
194 The basic message is the service name, interface name and operation (message) slot signatures for the API. And for API changes you have to apply development time API deprecation process. |
184 The basic message is the service name, interface name and operation (message) slot signatures for the API. And for API changes you have to apply development time API deprecation process. |
195 |
185 |
196 <b>Service Registration tools</b> \n |
186 <b>Service Registration tools</b> \n |
197 The needed utility files for service registration: |
187 The needed utility files for service registration: |
198 - xqsreg.exe should be in \epoc32\tools or some other directory that can be found from the path |
188 - xqsreg.exe should be in \epoc32\tools or some other directory that can be found from the path |
199 - service.prf should be in \epoc32\tools\qt\mkspecs\features\symbian directory. |
|
200 |
189 |
201 If necessary you can copy those files to target directories from qthighway/bin. |
190 If necessary you can copy those files to target directories from qthighway/bin. |
202 |
|
203 Sources for the xqsreg.exe can be found from the qthighway\xqsreg and it is also possible to compile it. |
|
204 - cd \qthighway\xqsreg |
|
205 - qmake -platform win32-mwc |
|
206 - make |
|
207 |
191 |
208 Usage: \n |
192 Usage: \n |
209 How to create a simple synchronously working service provider? |
193 How to create a simple synchronously working service provider? |
210 \code |
194 \code |
211 class YourService : public XQServiceProvider |
195 class YourService : public XQServiceProvider |
431 return; |
415 return; |
432 } |
416 } |
433 |
417 |
434 // Set function parameters |
418 // Set function parameters |
435 QList<QVariant> args; |
419 QList<QVariant> args; |
436 args << uri.toSring(); |
420 args << uri.toString(); |
437 request->setArguments(args); |
421 request->setArguments(args); |
438 |
422 |
439 // Send the request |
423 // Send the request |
440 bool res = request.send(); |
424 bool res = request->send(); |
441 if (!res) |
425 if (!res) |
442 { |
426 { |
443 // Request failed. |
427 // Request failed. |
444 int error = request->lastError(); |
428 int error = request->lastError(); |
445 // Handle error |
429 // Handle error |
637 */ |
621 */ |
638 |
622 |
639 /*! |
623 /*! |
640 \fn void XQServiceProvider::returnValueDelivered() |
624 \fn void XQServiceProvider::returnValueDelivered() |
641 |
625 |
642 This signal is emitted when asynchronous request has been completed and its |
626 This signal is emitted when request has been completed and its return value has been |
643 return value has been delivered to the service client. |
627 delivered to the service client. Synchronous request get completed upon returning |
|
628 from slot call, asynchronous gets completed when completeRequest is called. |
644 */ |
629 */ |
645 |
630 |
646 /*! |
631 /*! |
647 \fn void XQServiceProvider::clientDisconnected() |
632 \fn void XQServiceProvider::clientDisconnected() |
648 |
633 |
649 This signal is emitted if client accessing a service application terminates. |
634 This signal is emitted if there is on-going request and client destroys |
650 The counterpart in client side (when service application terminates) is |
635 the XQAiwRequest for some reason, e.g when exiting the client process. |
651 the error XQService::EConnectionClosed. |
|
652 */ |
636 */ |
653 |
637 |
654 /*! |
638 /*! |
655 Construct a remote service object for \a service and attach it to \a parent. |
639 Construct a remote service object for \a service and attach it to \a parent. |
656 \param service Defines the full service name that is implemented. |
640 \param service Defines the full service name that is implemented. |
698 m_data->m_adaptor->publishAll(this,XQServiceProvider::staticMetaObject.methodCount(),XQServiceAdaptor::Slots); |
682 m_data->m_adaptor->publishAll(this,XQServiceProvider::staticMetaObject.methodCount(),XQServiceAdaptor::Slots); |
699 } |
683 } |
700 else { |
684 else { |
701 m_data->m_adaptor->publishAll(m_data->plugin, 0, XQServiceAdaptor::Slots); |
685 m_data->m_adaptor->publishAll(m_data->plugin, 0, XQServiceAdaptor::Slots); |
702 } |
686 } |
|
687 |
|
688 if (XQServiceUtil::isEmbedded()) |
|
689 XQServiceUtils::closeWhenClientClosed(); |
703 } |
690 } |
704 |
691 |
705 /*! |
692 /*! |
706 Sets current request to asynchronous mode so that provider can complete the |
693 Sets current request to asynchronous mode so that provider can complete the |
707 request later via the completeRequest() call. |
694 request later via the completeRequest() call. |
709 \note There can be several clients accessing the same service at the same time. Avoid saving |
696 \note There can be several clients accessing the same service at the same time. Avoid saving |
710 the index to XQServiceProvider instance as member variable as when another new request |
697 the index to XQServiceProvider instance as member variable as when another new request |
711 comes in, it will have different index and you will potentially override the index of |
698 comes in, it will have different index and you will potentially override the index of |
712 the first request. You should ensure the completeRequest() gets the correct index e.g. |
699 the first request. You should ensure the completeRequest() gets the correct index e.g. |
713 by attaching the index as user data to data object maintain a map of indexes based on |
700 by attaching the index as user data to data object maintain a map of indexes based on |
714 some key. |
701 some key. \n |
|
702 <b> This should be used for a request set asynchronous by client only. This has no |
|
703 impact to the client side behaviour. For the synchronous request client side "send" |
|
704 will wait for the completion. For the asyncronous request the client side gets |
|
705 signalled when the completion happens. </b> |
715 */ |
706 */ |
716 int XQServiceProvider::setCurrentRequestAsync() |
707 int XQServiceProvider::setCurrentRequestAsync() |
717 { |
708 { |
718 XQSERVICE_DEBUG_PRINT("XQServiceProvider::setCurrentRequestAsync"); |
709 XQSERVICE_DEBUG_PRINT("XQServiceProvider::setCurrentRequestAsync"); |
719 return m_data->m_adaptor->setCurrentRequestAsync(); |
710 return m_data->m_adaptor->setCurrentRequestAsync(); |