31 /*! |
31 /*! |
32 \class XQAiwRequest |
32 \class XQAiwRequest |
33 \inpublicgroup QtBaseModule |
33 \inpublicgroup QtBaseModule |
34 |
34 |
35 \ingroup ipc |
35 \ingroup ipc |
36 \brief Encapsulates the core functionality of the interworking requests |
36 \brief Encapsulates the core functionality of the application interworking requests for service clients |
|
37 |
|
38 See \ref terminology for terms used in this documentation. |
37 |
39 |
38 The XQAiwRequest class encapsulates the core functionality of the interworking requests and hides the implementation details. |
40 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. |
41 This object is created by the XQApplicationManager::create factory method. |
40 |
42 |
41 This class is a part of API to be used by the applications instead of using XQServiceRequest directly. |
43 This class is a part of Application Manager API to be used by the applications instead of using XQServiceRequest directly. |
42 |
44 |
43 The Application Manager API offers centric place for applications UIs to handle application to application interworking use cases, like: |
45 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 |
46 - 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. |
47 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. |
48 - 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). |
49 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. |
50 - 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. |
51 - 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. |
52 - Launch service provider application (.exe) if not already running when client makes service call to it. |
51 - List and discover services dynamically. |
53 - List and discover services dynamically. Both normal and sharable (data-caged) files are supported. |
52 - Apply UI related options upon service launch, like "launch as embedded", "launch to foreground" and "launch to backround". |
54 - 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. |
55 - 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. |
56 - Open 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. |
57 - Miscellanous AIW support, like get service stasus or get DRM attributes. |
56 |
58 |
57 See the "examples/appmgrclient" included in the QtHighway release for usage examples. |
59 See the "examples/appmgrclient" included in the QtHighway release for usage examples. |
58 |
60 |
59 <b>Example usage:</b> \n |
61 <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 |
62 The usage pattern for all the XQAiwRequest variants implemented as service providers , interface, QUrl, QFile, is similar both embedded |
61 and non-embedded usage. |
63 and non-embedded usage. |
62 \code |
64 \code |
63 // Recommended way is to add XQApplicationManager as member variable to class |
65 // 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 // You can use the class also as local variable. |
66 class Client |
67 class Client |
67 { |
68 { |
68 |
69 |
69 public: |
70 public: |
87 bool embedded=true; // or false |
88 bool embedded=true; // or false |
88 |
89 |
89 XQAiwRequest *request; |
90 XQAiwRequest *request; |
90 // Create request by interface name, the very first service implementation |
91 // Create request by interface name, the very first service implementation |
91 // applied. |
92 // applied. |
92 request = mAiwMgr.create("Interface", "functionName2(QString, int)", embedded); |
93 request = mAiwMgr.create("Interface", "functionName2(QString,int)", embedded); |
93 |
94 |
94 // If dedicated service is wanted, apply this |
95 // If dedicated service is wanted, apply this |
95 // request = mAiwMgr.create("Service", "Interface", |
96 // request = mAiwMgr.create("Service", "Interface", |
96 // "functionName2(QString, int)", embedded); |
97 // "functionName2(QString,int)", embedded); |
97 |
98 |
98 if (request == NULL) |
99 if (request == NULL) |
99 { |
100 { |
100 // Service not found |
101 // Service not found |
101 return false; |
102 return false; |
139 void Client::handleError(int errorCode, const QString& errorMessage) |
140 void Client::handleError(int errorCode, const QString& errorMessage) |
140 { |
141 { |
141 // Handle error |
142 // Handle error |
142 } |
143 } |
143 \endcode |
144 \endcode |
|
145 |
|
146 <b>Problem solutions</b> \n |
|
147 Making QtHighway to produce traces helps sorting out the typical problems detected so far: |
|
148 |
|
149 <b><i> You get lines like *PlatSec* ERROR - Capability check failed - A Message (function number=0x00000200) |
|
150 from Thread ... line upon otherwise successful request. </i></b> |
|
151 - This is not an error. QTHighway collects available client capabilities into QSet and tests |
|
152 for each capability using the RMessage2::HasCapability() function. The trace line is output |
|
153 by that function. |
|
154 |
|
155 <b><i>Null XQAiwReuest is returned meaning a service not found form Apparch service registry. |
|
156 The trace has line "Discover error -1" or indications of XML parsing errors. </i></b> |
|
157 Check the following just in case: |
|
158 - The XML file syntax is OK ( from trace you should see XML parsing error). |
|
159 - After changing the XML you have run the qmake again. Otherwise changes in XML do not get visible. |
|
160 - The generated application registration (*_reg.rss) contains the data as mentioned in the registration XML file. |
|
161 - The compiled application registration file (*_reg.rsc) exists in "\epoc32\data\z\private\10003a3f\import\Apps" |
|
162 and contains the same XML dat. |
|
163 - In .iby file, the compiled application registration file (*_reg.rsc) has been copied to "\private\10003a3f\import\Apps". |
|
164 - In .iby file, the standard application resource file referred from the *_reg.rss has been copied |
|
165 to directory pointed using the macro S60_APP_RESOURCE or to directory referred by the macro |
|
166 APP_RESOURCE_DIR (the macro from epoc32\include\data_caging_paths_for_iby.hrh). |
|
167 - wk18 MCL specific: Looks like you need to get directories "\epoc32\winscw\c\sys\install" deleted (in emulator) |
|
168 to get any changes noticed by apparch. This looks like Apparch problem. |
|
169 |
|
170 <b><i> Service is found, but request returns an error "EMessageNotFound". </i></b> |
|
171 Check the following: |
|
172 - Check that slot signatures match in calling side and in service side and they follow Qt slot naming. |
|
173 - The slot signature does not contain extra spaces and does not contain reference (&) symbol. |
|
174 |
|
175 <b><i> Services get unexpected disconnet "CApaServerSymbianSession::Disconnect". </i></b> |
|
176 - This is a symptom that client request object has been deleted by code or by the GOOM FW. |
|
177 |
|
178 <b><i> Async response does not go back to client. </i></b> |
|
179 Check the following: |
|
180 - You are using the request id returned by the setCurrentRequestAsync(). |
|
181 - There are no "CApaServerSymbianSession::Disconnect" lines before calling the "complereRequest(asyncRequestIndex)". |
|
182 - The traces does not tell any "NOT FOUND" message for request (client has not beed disconnected). |
|
183 |
|
184 <b><i> Control Panel View cannot be launched using the QtHighway Service from an Indicator Plugin. </i></b> |
|
185 - See one solution from the RC case 424825. |
|
186 |
|
187 <b> How to enable log traces? </b> \n |
|
188 - You can find xqservicelog.h from the top level inc-directory of the QtHighway. There are |
|
189 two flags controlling QtHighway logging facilities. Both are disabled by default. |
|
190 To enable logging, see the file /sf/qtextensions/qthighway//inc/xqservicelog.h. \n\n |
|
191 <table border="2"> |
|
192 <tr> |
|
193 <td><b>Flag in the xqservicelogs.h</b></td> |
|
194 <td><b>Description</b></td> |
|
195 </tr> |
|
196 <tr> |
|
197 <td><i>XQSERVICE_DEBUG</i></td> |
|
198 <td> |
|
199 Main flag that enables logging using default Qt logging facilities. This turn on qDebug() |
|
200 traces from the QtHighway which are pretty handy to check. After defining the flag, rebuild |
|
201 the qthigway folder only (no need to rebuild whole qtextensions package!). |
|
202 </td> |
|
203 </tr> |
|
204 <tr> |
|
205 <td><i>XQSERVICE_DEBUG_FILE</i></td> |
|
206 <td> |
|
207 <b>This has not been used nor tested!</b> \n |
|
208 Flag that enables file logging mode to XqServiceMessageHandler. This flag is dependent |
|
209 on <i>XQSERVICE_DEBUG</i> flag and can't be enabled without it been enabled. |
|
210 </td> |
|
211 </tr> |
|
212 </table> |
|
213 |
|
214 - Logging is done by using four macros \a XQSERVICE_DEBUG_PRINT, \a XQSERVICE_WARNING_PRINT, \a XQSERVICE_CRITICAL_PRINT, |
|
215 \a XQSERVICE_FATAL_PRINT corresponding to qDebug, qWarning, qCritical and qFatal functionality. |
|
216 |
|
217 - XqServiceMessageHandler-class provides QtMessageHandler-function that can be used in applications to override |
|
218 Qt default message handling functionality. To take it into use in application, install it by calling |
|
219 \code |
|
220 qInstallMsgHandler(XQSERVICEMESSAGEHANDLER); |
|
221 \endcode |
|
222 in the beginning of the applications main-function. The flags control XqServiceMessageHandler in the following way: \n\n |
|
223 <table border="2"> |
|
224 <tr> |
|
225 <td><b>Flags defined</b></td> |
|
226 <td><b>Functionality</b></td> |
|
227 </tr> |
|
228 <tr> |
|
229 <td><i>None</i></td> |
|
230 <td> |
|
231 XqServiceMessageHandler-class doesn't exist. |
|
232 </td> |
|
233 </tr> |
|
234 <tr> |
|
235 <td><i>XQSERVICE_DEBUG</i></td> |
|
236 <td> |
|
237 XqServiceMessageHandler-class exists and uses RDebug to print all Qt messages. |
|
238 </td> |
|
239 </tr> |
|
240 <tr> |
|
241 <td><i>XQSERVICE_DEBUG</i> and <i>XQSERVICE_DEBUG_FILE</i></td> |
|
242 <td> |
|
243 XqServiceMessageHandler-class exists and uses RFileLogger to write all Qt messages to a file. |
|
244 To enable file logging, c:\logs\qt directory must exist. Log file is xqservice.log. Please |
|
245 notice that RFileLogger depends on flogger.lib. |
|
246 </td> |
|
247 </tr> |
|
248 </table> |
144 |
249 |
145 \sa XQApplicationManager |
250 \sa XQApplicationManager |
146 */ |
251 */ |
147 |
252 |
148 /*! |
253 /*! |
320 /*! |
425 /*! |
321 Create a QAction related to request from the registration data. Caller can |
426 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 |
427 add the action to wanted UI widget. When the action is triggered the XQAiwRequest |
323 emits triggered() signal for caller. |
428 emits triggered() signal for caller. |
324 The XQAiwRequest owns the action (caller shall not delete the action object). |
429 The XQAiwRequest owns the action (caller shall not delete the action object). |
|
430 The localized QAction text is constructed from the the following custom properties |
|
431 in the registration XML file: |
|
432 - \b aiw_action_text_file which tell the .qm file which contains the text ID identified |
|
433 by the "aiw_action_text". If no paths present in the the file name, default path |
|
434 is constructed as follows |
|
435 \code |
|
436 qApp->applicationFilePath().left(2) + "/resource/qt/translations/" + textFile; |
|
437 \endcode |
|
438 - \b aiw_action_text contains the text ID which contains the translated text present in the .qm file identified by the aiw_action_text_file |
|
439 - \b aiw_action_icon contain the name of QIcon resource created by the QIcon::addFile function. <b> NOTE ! *This is experimental property* ! </b> |
|
440 |
325 \return QAction object, if there was action attached to request. Otherwise 0. |
441 \return QAction object, if there was action attached to request. Otherwise 0. |
326 */ |
442 */ |
327 QAction *XQAiwRequest::createAction() |
443 QAction *XQAiwRequest::createAction() |
328 { |
444 { |
329 XQSERVICE_DEBUG_PRINT("XQAiwRequest::createAction"); |
445 XQSERVICE_DEBUG_PRINT("XQAiwRequest::createAction"); |