|
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: Interface to collections |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef MMPXCOLLECTIONUTILITY_H |
|
20 #define MMPXCOLLECTIONUTILITY_H |
|
21 |
|
22 #include <mpxcollectionframeworkdefs.h> |
|
23 #include <mpxcommonframeworkdefs.h> |
|
24 #include <mpxcollectionobserver.h> |
|
25 #include <mpxattribute.h> |
|
26 #include <mpxfilter.h> |
|
27 #include <mpxcommand.h> |
|
28 #include <mpxsearchcriteria.h> |
|
29 #include <mpxattributespecs.h> |
|
30 |
|
31 #include <badesca.h> |
|
32 |
|
33 class CMPXCollectionPath; |
|
34 class CMPXCollectionType; |
|
35 class MMPXCollection; |
|
36 class MMPXCollectionFindObserver; |
|
37 class CMPXSubscription; |
|
38 |
|
39 /******************************************************************************** |
|
40 * |
|
41 * Note: |
|
42 * |
|
43 * ** remove void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0) |
|
44 * |
|
45 * ** remove TUid CollectionIDL(TUid& aCollection) |
|
46 * |
|
47 * ** all methods which do not (necessarily) operate on current collection |
|
48 * should be moved from MMPXCollection to MMPXCollectionUtility |
|
49 * |
|
50 * |
|
51 *********************************************************************************/ |
|
52 |
|
53 /** |
|
54 * Main client interface for collections. Some terms used in the documentation of |
|
55 * this interface: |
|
56 * |
|
57 * Context - represents the 'state' of the collection, i.e. the current |
|
58 * browse path (encapsulated in CMPXCollectionPath) and filter applied |
|
59 * (encapsulated in CMPXFilter) |
|
60 * |
|
61 * Playlist - an abstract list of songs. A collection path allows the client |
|
62 * to cross reference the playlist with a collection, for example to |
|
63 * iterate through the playlist, extract user-supplied metadata etc. |
|
64 * |
|
65 * @lib mpxcollectionutility.lib |
|
66 */ |
|
67 class MMPXCollectionUtility |
|
68 { |
|
69 public: |
|
70 /** |
|
71 * Creates the interface for the client. This interface is bound to (i.e. |
|
72 * controls and receives events from) either an existing context or a new |
|
73 * one, according to: |
|
74 * |
|
75 * aModeId=KMcModeDefault - bound to the same context as any other client |
|
76 * running in the same thread, or KMcModeIsolated |
|
77 * context created if the first client in the thread |
|
78 * aModeId=KMcModeIsolated - new context created specifically for client, |
|
79 * may be shared later |
|
80 * aModeId=<UID> - bound to the same context as other clients which have |
|
81 * supplied the same UID. Most common case is application UID |
|
82 * so that clients in external processes can easily bind to |
|
83 * a specific application context |
|
84 * |
|
85 * @since S60 3.2.3 |
|
86 * @param aObs collection observer |
|
87 * @param aModeId collection mode id |
|
88 * @return collection utility object |
|
89 */ |
|
90 IMPORT_C static MMPXCollectionUtility* NewL( |
|
91 MMPXCollectionObserver* aObs = NULL, |
|
92 const TUid& aModeId = KMcModeDefault); |
|
93 |
|
94 /** |
|
95 * The collection. |
|
96 * |
|
97 * @since S60 3.2.3 |
|
98 * @return the collection |
|
99 */ |
|
100 virtual MMPXCollection& Collection() = 0; |
|
101 |
|
102 /** |
|
103 * Retrieves the ID of the collection plugin which matched aUids best. |
|
104 * If multiple plugins match the aUids, the only one with high priority will |
|
105 * be returned. |
|
106 * |
|
107 * @since S60 3.2.3 |
|
108 * @param aUids selection criteria |
|
109 * @return TUid containing the implementation UID of the collection that |
|
110 * would be selected |
|
111 */ |
|
112 virtual TUid CollectionIDL(const TArray<TUid>& aUids) = 0; |
|
113 |
|
114 /** |
|
115 * Frees up client side resources only. A collection is freed when there are no |
|
116 * clients using it, and all resources are freed when the last client closes. |
|
117 * |
|
118 * @since S60 3.2.3 |
|
119 */ |
|
120 virtual void Close() = 0; |
|
121 }; |
|
122 |
|
123 /** |
|
124 * MPXCollection |
|
125 * |
|
126 * @lib mpxcollectionutility.lib |
|
127 */ |
|
128 class MMPXCollection |
|
129 { |
|
130 public: |
|
131 /** |
|
132 * Opens the collection in its current state. |
|
133 * |
|
134 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
135 * with ID KMPXMediaIdContainer, i.e.contains other media objects. |
|
136 * |
|
137 * @since S60 3.2.3 |
|
138 * @param aMode open mode |
|
139 */ |
|
140 virtual void OpenL(TMPXOpenMode aMode=EMPXOpenDefault) = 0; |
|
141 |
|
142 /** |
|
143 * Opens the collection at a specific index. |
|
144 * |
|
145 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
146 * with ID KMPXMediaIdContainer, i.e.contains other media objects. |
|
147 * |
|
148 * @since S60 3.2.3 |
|
149 * @param aIndex the index into the currently opened item list |
|
150 * @param aMode type of open mode |
|
151 */ |
|
152 virtual void OpenL(TInt aIndex,TMPXOpenMode aMode=EMPXOpenDefault) = 0; |
|
153 |
|
154 /** |
|
155 * Opens the collection at a specific level. |
|
156 * |
|
157 * @since S60 3.2.3 |
|
158 * @param aPath the path of the collection |
|
159 * @param aMode type of open mode required |
|
160 * |
|
161 * Calls back MMPXCollectionObserver::HandleOpenL() |
|
162 */ |
|
163 virtual void OpenL(const CMPXCollectionPath& aPath, |
|
164 TMPXOpenMode aMode=EMPXOpenDefault) = 0; |
|
165 |
|
166 /** |
|
167 * Opens the collection at a specific index. |
|
168 * |
|
169 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
170 * with ID KMPXMediaIdContainer, i.e.contains other media objects which will |
|
171 * contain the attribute values specified by aAttrs. |
|
172 * |
|
173 * @since S60 3.2.3 |
|
174 * @param aIndex the index into the currently opened item list |
|
175 * @param aAttrs attributes requested |
|
176 * @param aMode type of open mode |
|
177 */ |
|
178 virtual void OpenL(TInt aIndex, |
|
179 const TArray<TMPXAttribute>& aAttrs, |
|
180 TMPXOpenMode aMode=EMPXOpenDefault) = 0; |
|
181 |
|
182 /** |
|
183 * Opens the collection at a specific level. |
|
184 * |
|
185 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
186 * with ID KMPXMediaIdContainer, i.e.contains other media objects which will |
|
187 * contain the attribute values specified by aAttrs. |
|
188 * |
|
189 * @since S60 3.2.3 |
|
190 * @param aPath the path of the collection |
|
191 * @param aAttrs attributes requested |
|
192 * @param aMode type of open mode required |
|
193 */ |
|
194 virtual void OpenL(const CMPXCollectionPath& aPath, |
|
195 const TArray<TMPXAttribute>& aAttrs, |
|
196 TMPXOpenMode aMode=EMPXOpenDefault) = 0; |
|
197 |
|
198 /** |
|
199 * Opens the collection with a list of implementation uids to be matched. |
|
200 * If current context matches the criteria, it will return existing browsing |
|
201 * media; otherwise it will be back to root level and only plug-ins which |
|
202 * match all provided uids will be returned, in priority order. |
|
203 * |
|
204 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
205 * with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin |
|
206 * priority if mulitple plugins support aUids. |
|
207 * |
|
208 * @since S60 3.2.3 |
|
209 * @param aUids array of UIDs used to select collection plugins based on |
|
210 * supported uids in plugin resource file. |
|
211 * @param aMode open mode |
|
212 */ |
|
213 virtual void OpenL(const TArray<TUid>& aUids, |
|
214 TMPXOpenMode aMode=EMPXOpenDefault) = 0; |
|
215 |
|
216 /** |
|
217 * Opens the collection with an uid to be matched. |
|
218 * If current context matches the criteria, it will return existing browsing |
|
219 * media; otherwise it will be back to root level and only plug-ins which |
|
220 * match the uid will be returned, in priority order. |
|
221 * |
|
222 * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object |
|
223 * with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin |
|
224 * priority if mulitple plugins support the uid. |
|
225 * |
|
226 * @since S60 3.2.3 |
|
227 * @param aUid single UID used to select a collection |
|
228 * @param aMode open mode |
|
229 */ |
|
230 virtual void OpenL(const TUid& aUid, |
|
231 TMPXOpenMode aMode=EMPXOpenDefault) = 0; |
|
232 |
|
233 /** |
|
234 * Apply a filter to collection browsing. All subsequent calls |
|
235 * to OpenL() will have this filter applied. |
|
236 * |
|
237 * @since S60 3.2.3 |
|
238 * @param aFilter the filter to apply, or NULL to remove current |
|
239 * filter |
|
240 */ |
|
241 virtual void SetFilterL(CMPXFilter* aFilter) = 0; |
|
242 |
|
243 /** |
|
244 * Current filter that is applied to collection browsing. i.e. results |
|
245 * returned through MMPXCollectionObserver::HandleOpenL() callback from |
|
246 * OpenL(). |
|
247 * |
|
248 * @since S60 3.2.3 |
|
249 * @return filter applied to browsing, or NULL if no filter applied |
|
250 */ |
|
251 virtual CMPXFilter* FilterL() = 0; |
|
252 |
|
253 /** |
|
254 * Returns current collection plugin implementation UID. |
|
255 * |
|
256 * @since S60 3.2.3 |
|
257 * @return UID of the collection, or KNullUid if no collection opened |
|
258 */ |
|
259 virtual TUid UidL() const=0; |
|
260 |
|
261 /** |
|
262 * The path of the collection in its current state. |
|
263 * Ownsership transferred. |
|
264 * |
|
265 * @since S60 3.2.3 |
|
266 * @return the path of the collection |
|
267 */ |
|
268 virtual CMPXCollectionPath* PathL() = 0; |
|
269 |
|
270 /** |
|
271 * Navigates back to the container of the current items. |
|
272 * Calls back MMPXCollectionObserver::HandleOpenL(). |
|
273 * |
|
274 * @since S60 3.2.3 |
|
275 */ |
|
276 virtual void BackL() = 0; |
|
277 |
|
278 /** |
|
279 * Is this path on a 'remote' collection. |
|
280 * |
|
281 * @since S60 3.2.3 |
|
282 * @aParam aPath the collection path |
|
283 * @return ETrue if is remote collection, otherwise EFalse |
|
284 */ |
|
285 virtual TBool IsRemote(const CMPXCollectionPath& aPath) = 0; |
|
286 |
|
287 /** |
|
288 * Stops any async operations that are currently under way. |
|
289 * |
|
290 * @since S60 3.2.3 |
|
291 */ |
|
292 virtual void CancelRequest() = 0; |
|
293 |
|
294 /** |
|
295 * Adds item(s) to the collection. |
|
296 * |
|
297 * @since S60 3.2.3 |
|
298 * @param aNewMedia new item(s) to add |
|
299 */ |
|
300 virtual void AddL(const CMPXMedia& aNewMedia) = 0; |
|
301 |
|
302 /** |
|
303 * Remove an item (or items under a group) from the collection |
|
304 * |
|
305 * @param aPath, item(s) to remove |
|
306 * @param aObs, observer to this operation, Optional callback. |
|
307 * @deprecated please use CommandL (CMPXCommand) |
|
308 */ |
|
309 virtual void RemoveL(const CMPXCollectionPath& aPath, |
|
310 MMPXCollectionRemoveObserver* aObs = NULL ) = 0; |
|
311 |
|
312 /** |
|
313 * Removes item(s) from the collection. |
|
314 * |
|
315 * @since S60 3.2.3 |
|
316 * @param aMedia item(s) to remove |
|
317 */ |
|
318 virtual void RemoveL(const CMPXMedia& aMedia) = 0; |
|
319 |
|
320 /** |
|
321 * Sets/updates the media for the item. |
|
322 * Callback via EMediaChanged message if currently opened. |
|
323 * |
|
324 * @since S60 3.2.3 |
|
325 * @param aMedia updated item |
|
326 * |
|
327 */ |
|
328 virtual void SetSyncL(const CMPXMedia& aMedia) = 0; |
|
329 |
|
330 /** |
|
331 * |
|
332 * Sets/updates the item specified in the path, Aynchronous |
|
333 * Callback for completion with HandleCollectionMessageL() |
|
334 * event: TMPXCollectionMessage::EAsyncOpComplete |
|
335 * type: EMcsSetMediaAsync |
|
336 * data: error code |
|
337 * |
|
338 * @param aMedia, updated item |
|
339 * @deprecated, please use CommandL(CMPXCommand& aCmd) |
|
340 */ |
|
341 virtual void SetL(const CMPXMedia& aMedia) = 0; |
|
342 |
|
343 /** |
|
344 * Find a list of media properties based on a search criteria. |
|
345 * The types of supported "queries" are collection dependent. |
|
346 * Callback via MMPXCollectionFindObserver::HandleFindL(); |
|
347 * |
|
348 * @since S60 3.2.3 |
|
349 * @param aCriteria criteria to search on |
|
350 * @param aAttrs attributes to return |
|
351 * @param aObs observer for find callback |
|
352 * |
|
353 */ |
|
354 virtual void FindAllL(const CMPXSearchCriteria& aCriteria, |
|
355 const TArray<TMPXAttribute>& aAttrs, |
|
356 MMPXCollectionFindObserver& aObs) = 0; |
|
357 |
|
358 /** |
|
359 * Find a list of media properties based on a search criteria. |
|
360 * The types of supported "queries" are collection dependent. |
|
361 * This is a SYNCHRONOUS METHOD, use only if necessary. |
|
362 * |
|
363 * @since S60 3.2.3 |
|
364 * @param aCriteria criteria to search on |
|
365 * @param aAttrs attributes to return |
|
366 * @return search results maching the given criteria |
|
367 */ |
|
368 virtual CMPXMedia* FindAllL(const CMPXSearchCriteria& aCriteria, |
|
369 const TArray<TMPXAttribute>& aAttrs) = 0; |
|
370 |
|
371 /** |
|
372 * Retrieve media for the item specified in the path. |
|
373 * Note: if selection is set in aPath, HandleMedia will return an array of |
|
374 * media of current selected items. |
|
375 * if no selection is set in aPath, HandleMedia will return media |
|
376 * properities of current item. |
|
377 * Calls back MMPXCollectionObserver::HandleMediaL() |
|
378 * |
|
379 * @since S60 3.2.3 |
|
380 * @param aPath the path of the collection |
|
381 * @param aAttrs attributes requested. |
|
382 * @param aSpecs specifications for attributes, Ownership not transferred |
|
383 * @param aFilter filter to apply, Ownership not transferred |
|
384 * |
|
385 */ |
|
386 virtual void MediaL(const CMPXCollectionPath& aPath, |
|
387 const TArray<TMPXAttribute>& aAttrs, |
|
388 CMPXAttributeSpecs* aSpecs=NULL, |
|
389 CMPXFilter* aFilter=NULL) = 0; |
|
390 |
|
391 /** |
|
392 * Broadcasts an event to all clients or plugins. |
|
393 * |
|
394 * @since S60 3.2.3 |
|
395 * @param aMsg event to broadcast |
|
396 * @param aData data to accompany the event |
|
397 */ |
|
398 virtual void NotifyL(TMPXCollectionBroadCastMsg aMsg, TInt aData) = 0; |
|
399 |
|
400 /** |
|
401 * Send a command to the collection server |
|
402 * |
|
403 * @param aCmd, command to handle |
|
404 * @param aData, some data about event (event specific, optional) |
|
405 * @deprecated use CommandL(CMPXCommand& aCmd) |
|
406 */ |
|
407 virtual void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0) = 0; |
|
408 |
|
409 /** |
|
410 * Send a command to the collection server. |
|
411 * |
|
412 * @since S60 3.2.3 |
|
413 * @param aCmd command to handle |
|
414 */ |
|
415 virtual void CommandL(CMPXCommand& aCmd) = 0; |
|
416 |
|
417 /** |
|
418 * Retrieves the list of supported types. |
|
419 * |
|
420 * @since S60 3.2.3 |
|
421 * @param aArray On return, array will be filled with collection type items |
|
422 */ |
|
423 virtual void GetSupportedTypesL(RPointerArray<CMPXCollectionType>& aArray) = 0; |
|
424 |
|
425 /** |
|
426 * Fetches the capabilities supported by the current collection context. |
|
427 * |
|
428 * @since S60 3.2.3 |
|
429 * @param aCapability bitmask of the capabilities supported. |
|
430 */ |
|
431 virtual void GetSupportedCapabilitiesL(TCollectionCapability& aCapability) = 0; |
|
432 |
|
433 /** |
|
434 * |
|
435 * Retrieves the real collection UID based on a predefined UID |
|
436 * @param aCollection, UID for lookup, defined in "mpxcollectionframeworkdefs.h" |
|
437 * @return TUid containing the real implementation UID |
|
438 * @deprecated use MMPXCollectionUtility::CollectionIDL |
|
439 */ |
|
440 virtual TUid CollectionIDL(TUid& aCollection) = 0; |
|
441 |
|
442 /** |
|
443 * Adds a message subscription for this client. |
|
444 * |
|
445 * @since S60 3.2.3 |
|
446 * @param aSubscription subscription to be added |
|
447 */ |
|
448 virtual void AddSubscriptionL(const CMPXSubscription& aSubscription) = 0; |
|
449 |
|
450 /** |
|
451 * Removes a message subscription for this client. |
|
452 * |
|
453 * @since S60 3.2.3 |
|
454 * @param aSubscription subscription to be removed. |
|
455 */ |
|
456 virtual void RemoveSubscriptionL(const CMPXSubscription& aSubscription) = 0; |
|
457 |
|
458 /** |
|
459 * Removes all message subscriptions for this client. |
|
460 * |
|
461 * @since S60 3.2.3 |
|
462 */ |
|
463 virtual void ClearSubscriptionsL() = 0; |
|
464 }; |
|
465 |
|
466 #endif // MMPXCOLLECTIONUTILITY_H |
|
467 |