|
1 /* |
|
2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Implementation of interface for Collection Utility |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef CMPXCOLLECTIONUTILITY_H |
|
21 #define CMPXCOLLECTIONUTILITY_H |
|
22 |
|
23 |
|
24 #include <mpxcollectionobserver.h> |
|
25 #include <mpxcollectionmessage.h> |
|
26 #include <mpxsession.h> |
|
27 #include <mpxmessageobserver.h> |
|
28 |
|
29 #include "mpxcollectionserverdefs.h" |
|
30 #include "mpxcollectionutility.h" |
|
31 |
|
32 class CMPXMessageMonitor; |
|
33 class CMPXTaskQueue; |
|
34 class CMPXMsgBuf; |
|
35 class CMPXMedia; |
|
36 |
|
37 /** |
|
38 * Implementation of collection utility interface |
|
39 */ |
|
40 NONSHARABLE_CLASS(CMPXCollectionUtility) : public CActive, |
|
41 public MMPXCollectionUtility, |
|
42 public MMPXMessageObserver, |
|
43 public MMPXCollection |
|
44 |
|
45 { |
|
46 public: |
|
47 /** |
|
48 * Two-phased constructor |
|
49 * |
|
50 * @param aObs observer |
|
51 * @param aModeId collection mode id |
|
52 * @return object of constructed |
|
53 */ |
|
54 static CMPXCollectionUtility* NewL(const TUid& aModeId, |
|
55 MMPXCollectionObserver* aObs); |
|
56 |
|
57 /** |
|
58 * Destructor |
|
59 */ |
|
60 ~CMPXCollectionUtility(); |
|
61 |
|
62 private: |
|
63 /** |
|
64 * C++ constructor |
|
65 */ |
|
66 CMPXCollectionUtility(MMPXCollectionObserver* aObs); |
|
67 |
|
68 /** |
|
69 * Second phase constructor |
|
70 * |
|
71 * @param aModeId collection mode id |
|
72 */ |
|
73 void ConstructL(const TUid& aModeId); |
|
74 |
|
75 public: |
|
76 |
|
77 /** |
|
78 * From MMPXCollectionUtility |
|
79 * The collection. |
|
80 * |
|
81 * @return the collection |
|
82 */ |
|
83 MMPXCollection& Collection(); |
|
84 |
|
85 /** |
|
86 * From MMPXCollectionUtility |
|
87 * Retrieves the ID of the collection plugin which matched aUids best. |
|
88 * If multiple plugins match the aUids, the only one with high priority will |
|
89 * be returned |
|
90 * |
|
91 * @param aUids, selection criteria |
|
92 * @return TUid containing the implementation UID of the collection that |
|
93 * would be selected |
|
94 */ |
|
95 TUid CollectionIDL(const TArray<TUid>& aUids); |
|
96 |
|
97 /** |
|
98 * From MMPXCollectionUtility |
|
99 * Frees up client side resources only; a collection is freed when there are no |
|
100 * clients using it, and all resources are freed when the last client closes |
|
101 */ |
|
102 void Close(); |
|
103 |
|
104 /** |
|
105 * From MMPXCollection |
|
106 * Opens the collection in its current state |
|
107 * |
|
108 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
109 * with ID KMPXMediaIdContainer, i.e.contains other media objects |
|
110 * |
|
111 * @param aMode, open mode |
|
112 */ |
|
113 |
|
114 void OpenL(TMPXOpenMode aMode=EMPXOpenDefault); |
|
115 |
|
116 /** |
|
117 * From MMPXCollection |
|
118 * Opens the collection at a specific index |
|
119 * |
|
120 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
121 * with ID KMPXMediaIdContainer, i.e.contains other media objects |
|
122 * |
|
123 * @param aIndex, the index into the currently opened item list |
|
124 * @param aMode, type of open mode |
|
125 */ |
|
126 void OpenL(TInt aIndex,TMPXOpenMode aMode=EMPXOpenDefault); |
|
127 |
|
128 /** |
|
129 * From MMPXCollection |
|
130 * Opens the collection at a specific level |
|
131 * |
|
132 * @param aPath, the path of the collection |
|
133 * @param aMode, open mode |
|
134 * |
|
135 * Calls back MMPXCollectionObserver::HandleOpenL() |
|
136 */ |
|
137 void OpenL(const CMPXCollectionPath& aPath, |
|
138 TMPXOpenMode aMode=EMPXOpenDefault); |
|
139 |
|
140 /** |
|
141 * From MMPXCollection |
|
142 * Opens the collection at a specific index |
|
143 * |
|
144 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
145 * with ID KMPXMediaIdContainer, i.e.contains other media objects which will |
|
146 * contain the attribute values specified by aAttrs |
|
147 * |
|
148 * @param aIndex, the index into the currently opened item list |
|
149 * @param aAttrs, attributes requested. |
|
150 * @param aMode, type of open mode |
|
151 */ |
|
152 void OpenL(TInt aIndex,const TArray<TMPXAttribute>& aAttrs, |
|
153 TMPXOpenMode aMode=EMPXOpenDefault); |
|
154 |
|
155 /** |
|
156 * From MMPXCollection |
|
157 * Opens the collection at a specific level |
|
158 * |
|
159 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
160 * with ID KMPXMediaIdContainer, i.e.contains other media objects which will |
|
161 * contain the attribute values specified by aAttrs |
|
162 * |
|
163 * @param aPath, the path of the collection |
|
164 * @param aAttrs, attributes requested. |
|
165 * @param aMode, type of open mode required |
|
166 */ |
|
167 void OpenL(const CMPXCollectionPath& aPath, |
|
168 const TArray<TMPXAttribute>& aAttrs, |
|
169 TMPXOpenMode aMode=EMPXOpenDefault); |
|
170 |
|
171 /** |
|
172 * From MMPXCollection |
|
173 * Opens the collection with a list of implementation uids to be matched. |
|
174 * if current context matches the criteria, it will return existing browsing |
|
175 * media; otherwise it will be back to root level and only plug-ins which |
|
176 * match all provided uids will be returned, in priority order. |
|
177 * |
|
178 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
179 * with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin |
|
180 * priority if mulitple plugins support aUids. |
|
181 * |
|
182 * @param aUids, array of UIDs used to select collection plugins based on |
|
183 * supported uids in plugin resource file. |
|
184 * @param aMode, open mode |
|
185 */ |
|
186 void OpenL(const TArray<TUid>& aUids, |
|
187 TMPXOpenMode aMode=EMPXOpenDefault); |
|
188 |
|
189 /** |
|
190 * From MMPXCollection |
|
191 * Opens the collection with an uid to be matched. |
|
192 * if current context matches the criteria, it will return existing browsing |
|
193 * media; otherwise it will be back to root level and only plug-ins which |
|
194 * match the uid will be returned, in priority order. |
|
195 * |
|
196 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
197 * with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin |
|
198 * priority if mulitple plugins support the uid. |
|
199 * |
|
200 * @param aUid, single UID used to select a collection |
|
201 * @param aMode, open mode |
|
202 */ |
|
203 void OpenL(const TUid& aUid, |
|
204 TMPXOpenMode aMode=EMPXOpenDefault); |
|
205 |
|
206 /** |
|
207 * From MMPXCollection |
|
208 * Apply a filter to collection browsing; all subsequent calls |
|
209 * to OpenL() will have this filter applied. |
|
210 * |
|
211 * @param aFilter, the filter to apply, or NULL to remove current |
|
212 * filter |
|
213 */ |
|
214 void SetFilterL(CMPXFilter* aFilter); |
|
215 |
|
216 /** |
|
217 * From MMPXCollection |
|
218 * Current filter that is applied to collection browsing, i.e. results |
|
219 * returned through MMPXCollectionObserver::HandleOpenL() callback from |
|
220 * OpenL() |
|
221 * |
|
222 * @return filter applied to browsing, or NULL if no filter applied |
|
223 */ |
|
224 CMPXFilter* FilterL(); |
|
225 |
|
226 /** |
|
227 * From MMPXCollection |
|
228 * Returns current collection plugin implementation UID |
|
229 * |
|
230 * @return UID of the collection |
|
231 */ |
|
232 TUid UidL() const; |
|
233 |
|
234 /** |
|
235 * From MMPXCollection |
|
236 * The path of the collection in its current state |
|
237 * |
|
238 * @return the path of the collection |
|
239 */ |
|
240 CMPXCollectionPath* PathL(); |
|
241 |
|
242 /** |
|
243 * From MMPXCollection |
|
244 * Navigates back to the container of the current items |
|
245 * Calls back MMPXCollectionObserver::HandleOpenL() |
|
246 */ |
|
247 void BackL(); |
|
248 |
|
249 /** |
|
250 * From MMPXCollection |
|
251 * Is this path on a 'remote' collection |
|
252 * |
|
253 * @aParam aPath, the collection path |
|
254 * @return ETrue if is remote collection, otherwise EFalse |
|
255 */ |
|
256 TBool IsRemote(const CMPXCollectionPath& aPath); |
|
257 |
|
258 /** |
|
259 * From MMPXCollection |
|
260 * Stops any async operations that are currently under way |
|
261 */ |
|
262 void CancelRequest(); |
|
263 |
|
264 /** |
|
265 * From MMPXCollection |
|
266 * Adds item(s) to the collection |
|
267 * |
|
268 * @param aNewProperties, Properties of the item |
|
269 */ |
|
270 void AddL(const CMPXMedia& aNewProperties); |
|
271 |
|
272 /** |
|
273 * From MMPXCollection |
|
274 * Remove an item (or items under a group) from the collection |
|
275 * |
|
276 * @param aPath, item(s) to remove |
|
277 * @param aObs, observer callback for items deleted (Optional) |
|
278 */ |
|
279 void RemoveL(const CMPXCollectionPath& aPath, |
|
280 MMPXCollectionRemoveObserver* aObs = NULL ); |
|
281 |
|
282 /** |
|
283 * From MMPXCollection |
|
284 * Removes item(s) to the collection |
|
285 * |
|
286 * @param aProperties, Properties of the item |
|
287 */ |
|
288 void RemoveL(const CMPXMedia& aProperties); |
|
289 |
|
290 /** |
|
291 * From MMPXCollection |
|
292 * |
|
293 * Sets/updates the media for the item |
|
294 * Callback via EMediaChanged message if currently opened |
|
295 * |
|
296 * @param aMedia, updated item |
|
297 * |
|
298 */ |
|
299 void SetSyncL(const CMPXMedia& aMedia); |
|
300 |
|
301 /** |
|
302 * From MMPXCollection |
|
303 * |
|
304 * Sets/updates the media for the item, Asynchronous |
|
305 * Callback via HandleCollectionMessage, AsyncOp complete |
|
306 * |
|
307 * @param aMedia, new value |
|
308 * |
|
309 */ |
|
310 void SetL(const CMPXMedia& aMedia); |
|
311 |
|
312 /** |
|
313 * Find a list of media properties based on a search criteria |
|
314 * The types of supported "queries" are plugin dependent |
|
315 * |
|
316 * @param aMedia, criteria to search on |
|
317 * @param aAttrs, attributes to return |
|
318 * @param aObs, observer for find callback |
|
319 * Callback via MMPXCollectionFindObserver::HandleFindL(); |
|
320 */ |
|
321 void FindAllL(const CMPXMedia& aMedia, |
|
322 const TArray<TMPXAttribute>& aAttrs, |
|
323 MMPXCollectionFindObserver& aObs); |
|
324 |
|
325 /** |
|
326 * Find a list of media properties based on a search criteria |
|
327 * The types of supported "queries" are plugin dependent |
|
328 * This is a SYNCHRONOUS METHOD, use only if necessary. |
|
329 * @param aMedia, criteria to search on |
|
330 * @param aAttrs, attributes to return |
|
331 */ |
|
332 CMPXMedia* FindAllL(const CMPXMedia& aMedia, |
|
333 const TArray<TMPXAttribute>& aAttrs); |
|
334 |
|
335 /** |
|
336 * From MMPXCollection |
|
337 * Retrieve media for the item specified in the path |
|
338 * Note: if selection is set in aPath, HandleMedia will return an array of |
|
339 * media of current selected items. |
|
340 * if no selection is set in aPath, HandleMedia will return media |
|
341 * properities of current item. |
|
342 * |
|
343 * @param aPath, the path of the collection |
|
344 * @param aAttrs, attributes requested. |
|
345 * @aParam aSpecs, specifications for attributes |
|
346 * @param aFilter, filter to apply |
|
347 * |
|
348 * Calls back MMPXCollectionObserver::HandleMediaL() |
|
349 */ |
|
350 void MediaL(const CMPXCollectionPath& aPath, |
|
351 const TArray<TMPXAttribute>& aAttrs, |
|
352 CMPXAttributeSpecs* aSpecs=NULL, |
|
353 CMPXFilter* aFilter=NULL); |
|
354 |
|
355 /** |
|
356 * From MMPXCollection |
|
357 * Broadcasts an event to all observers |
|
358 * @param aMsg event to broadcast |
|
359 * @param aData data to accompany the event |
|
360 */ |
|
361 void NotifyL( TMPXCollectionBroadCastMsg aMsg, TInt aData ); |
|
362 |
|
363 /** |
|
364 * From MMPXCollection |
|
365 * Send a Command to the collection server |
|
366 * aCmd, command to handle |
|
367 * aData, some data about event (event specific, optional) |
|
368 */ |
|
369 void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0); |
|
370 |
|
371 /** |
|
372 * From MMPXCollection |
|
373 * Send a command to the collection server |
|
374 * |
|
375 * @param aCmd, command to handle |
|
376 */ |
|
377 void CommandL(CMPXCommand& aCmd); |
|
378 |
|
379 /** |
|
380 * From MMPXCollection |
|
381 * Retrieves the set of supported file types |
|
382 * @param aArray Array to fill with the data |
|
383 */ |
|
384 void GetSupportedTypesL( RPointerArray<CMPXCollectionType>& aArray ); |
|
385 |
|
386 /** |
|
387 * From MMPXCollection |
|
388 * Retrieves the capabilities for the current collection context |
|
389 * @arg aCapability, bitmask of the capabilities supported. |
|
390 */ |
|
391 void GetSupportedCapabilitiesL(TCollectionCapability& aCapability); |
|
392 |
|
393 /** |
|
394 * From MMPXCollection |
|
395 * Retrieves the real collection UID based on a predefined UID |
|
396 * @param aCollection, UID for lookup, defined in "mpxcollectionframeworkdefs.h" |
|
397 * @return TUid containing the real implementation UID |
|
398 */ |
|
399 TUid CollectionIDL(TUid& aCollection); |
|
400 |
|
401 /** |
|
402 * From MMPXCollection |
|
403 * Adds a message subscription for this client. |
|
404 * @param aSubscription subscription to be added |
|
405 */ |
|
406 void AddSubscriptionL(const CMPXSubscription& aSubscription); |
|
407 |
|
408 /** |
|
409 * From MMPXCollection |
|
410 * Removes a message subscription for this client. |
|
411 * @param aSubscription subscription to be removed. |
|
412 */ |
|
413 void RemoveSubscriptionL(const CMPXSubscription& aSubscription); |
|
414 |
|
415 /** |
|
416 * From MMPXCollection |
|
417 * Removes all message subscriptions for this client. |
|
418 */ |
|
419 void ClearSubscriptionsL(); |
|
420 |
|
421 /** |
|
422 * From MMPXMessageObserver |
|
423 * Message received |
|
424 * @param aMsgData message data |
|
425 * @param aError error code |
|
426 */ |
|
427 void MessageReceived(TInt aMsgData, TInt aError); |
|
428 |
|
429 /** |
|
430 * From CActive |
|
431 * Handles an active object's request completion event |
|
432 */ |
|
433 void RunL(); |
|
434 |
|
435 /** |
|
436 * From CActive |
|
437 * Implements cancellation of an outstanding request. |
|
438 */ |
|
439 void DoCancel(); |
|
440 |
|
441 /** |
|
442 * From CActive |
|
443 * Handles a leave occurring in the request completion event handler RunL() |
|
444 * |
|
445 * @param aError error code |
|
446 */ |
|
447 TInt RunError(TInt aError); |
|
448 |
|
449 private: |
|
450 |
|
451 /** |
|
452 * Add a request to the task queue and run the next queue if no outstanding |
|
453 * task |
|
454 * |
|
455 * @param aFunction function code |
|
456 * @param aObs, observer to callback asynchronously |
|
457 * @param aParamData data |
|
458 * @param aBuf, extra data in buffer, ownership transferred. |
|
459 * @param aPtr, pointer to a object |
|
460 * @param aAlivePtr1, object to keep alive for a task |
|
461 ownership transferred |
|
462 * @param aAlivePtr2, same as aAlivePtr1 |
|
463 */ |
|
464 void AddRequestL(TMPXCollectionServerOp aFunction, |
|
465 TAny* aObs, |
|
466 TInt aParamData=0, |
|
467 CBufBase* aBuf=NULL, |
|
468 TAny* aPtr=NULL, |
|
469 CBase* aAlivePtr1=NULL, |
|
470 CBase* aAlivePtr2=NULL); |
|
471 |
|
472 /** |
|
473 * Send next request to server |
|
474 */ |
|
475 void ExecuteNextRequest(); |
|
476 |
|
477 /** |
|
478 * Handle message from message queue |
|
479 * @param aMsgData message data |
|
480 * @param aError error code |
|
481 */ |
|
482 void HandleMessageL(TInt aMsgData, TInt aError); |
|
483 |
|
484 /** |
|
485 * Handles error in RunL |
|
486 * |
|
487 * @param aError error code |
|
488 */ |
|
489 void HandleRunErrorL(TInt aError); |
|
490 |
|
491 #ifdef _ENABLE_GUARD_TIMER |
|
492 /** |
|
493 * Gaurd timer callback |
|
494 * |
|
495 * @param aPtr pointer the this |
|
496 */ |
|
497 static TInt GuardTimerCallback(TAny* aPtr); |
|
498 #endif |
|
499 |
|
500 private: |
|
501 MMPXCollectionObserver* iObserver; |
|
502 CMPXMessageMonitor* iMsgMonitor; |
|
503 CMPXTaskQueue* iTaskQueue; |
|
504 RMPXSession iMcs; |
|
505 CMPXMedia* iCurrentEntries; |
|
506 |
|
507 CBufBase* iBuffer; |
|
508 CArrayFixBase* iArray; |
|
509 TPckgBuf<TInt> iSizePckg; |
|
510 TPckgBuf<TInt> iSelectionPckg; |
|
511 TPckgBuf<TInt> iCompletePckg; |
|
512 TPckgBuf<TInt> iPropertiesSizePckg; |
|
513 TInt iSelection; |
|
514 TBool iCallbackOngoing; // is client processing callback? |
|
515 // Keep alive pointers on global heap |
|
516 CMPXMedia* iMedia; |
|
517 CMPXMedia* iMediaOnError; // media object while handling error |
|
518 #ifdef _ENABLE_GUARD_TIMER |
|
519 CPeriodic* iGuardTimer; //guard timer for async request |
|
520 #endif |
|
521 }; |
|
522 |
|
523 #endif // CMPXCOLLECTIONUTILITY_H |