|
1 /* |
|
2 * Copyright (c) 2002-2004 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: For adding content to be synchronized. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef __SMLDATAPROVIDER_H__ |
|
20 #define __SMLDATAPROVIDER_H__ |
|
21 // |
|
22 #include <SyncMLDef.h> |
|
23 #include <SyncMLDataFilter.h> |
|
24 #include <syncml/SmlDataSyncDefs.h> |
|
25 #include <SmlDataFormat.h> |
|
26 // |
|
27 /** |
|
28 @publishedPartner |
|
29 |
|
30 Plug-in Data Provider API. |
|
31 */ |
|
32 |
|
33 /** The parent uid to be used for the root */ |
|
34 const TSmlDbItemUid KDbItemUidRoot = -1; |
|
35 |
|
36 /* |
|
37 UIDs for use with CSmlDataProvider::SupportsOperation. |
|
38 Other optional features are specified in the CSmlDataStoreFormat object |
|
39 obtained from the Data Provider. |
|
40 */ |
|
41 /** |
|
42 This UID identifies optional support for transaction operations. |
|
43 For a DBA implementation to support this operation, it must be possible to add, change, and delete items within an atomic transaction. |
|
44 */ |
|
45 const TUid KUidSmlSupportTransaction = { 0x10009FC6 }; |
|
46 /** |
|
47 This UID identifies optional support for suspend and resume operations. |
|
48 For a DBA implementation to support this operation, it must be possible to to mark individual items as being 'in-sync', while other |
|
49 items remain 'out-of-sync'. |
|
50 */ |
|
51 const TUid KUidSmlSupportSuspendResume = { 0x10009FC7 }; |
|
52 const TUid KUidSmlSupportBatch = { 0x10009FC8 }; |
|
53 const TUid KUidSmlSupportMultipleStores = { 0x10009FC9 }; |
|
54 const TUid KUidSmlSupportsUserSelectableMatchType = { 0x10009FCA }; |
|
55 |
|
56 /** |
|
57 Set of Data Item LUIDs. |
|
58 */ |
|
59 class MSmlDataItemUidSet |
|
60 { |
|
61 public: |
|
62 /** |
|
63 Returns the number of items in the set. |
|
64 */ |
|
65 IMPORT_C TInt ItemCount() const; |
|
66 /** |
|
67 Returns the index of the specified item UID in the set, or -1 if the item UID is not present. |
|
68 */ |
|
69 IMPORT_C TInt ItemIndex(TSmlDbItemUid aItemId) const; |
|
70 /** |
|
71 Retuns the item UID at the specified index in the set. |
|
72 */ |
|
73 IMPORT_C TSmlDbItemUid ItemAt(TInt aIndex) const; |
|
74 public: |
|
75 IMPORT_C void ExternalizeL(RWriteStream& aStream) const; |
|
76 protected: |
|
77 // hide the virtual methods from the public interface to enable future extension without breaking BC |
|
78 virtual TInt DoItemCount() const = 0; |
|
79 virtual TInt DoItemIndex(TSmlDbItemUid aItemId) const = 0; |
|
80 virtual TSmlDbItemUid DoItemAt(TInt aIndex) const = 0; |
|
81 virtual void DoExternalizeL(RWriteStream& aStream) const = 0; |
|
82 }; |
|
83 |
|
84 |
|
85 /** |
|
86 Data Store interface. |
|
87 */ |
|
88 class CSmlDataStore : public CBase |
|
89 { |
|
90 public: |
|
91 /** |
|
92 Opens the data store specified by aStoreName asynchronously. |
|
93 @param aStoreName The name of the data store to open. |
|
94 @param aContext Identifies the specific synchronisation relationship to use for the synchronisation. |
|
95 @param aStatus On completion of the open, contains the result code. |
|
96 */ |
|
97 IMPORT_C void OpenL(const TDesC& aStoreName, MSmlSyncRelationship& aContext, TRequestStatus& aStatus); |
|
98 /** |
|
99 Cancel the current asynchronous request, including open. Only one asynchronous request may be outstanding at any one time. |
|
100 */ |
|
101 IMPORT_C void CancelRequest(); |
|
102 public: |
|
103 /** |
|
104 Returns the name of the open data store. |
|
105 */ |
|
106 IMPORT_C const TDesC& StoreName() const; |
|
107 public: |
|
108 /** |
|
109 BeginTransactionL() starts the transaction mode. During this mode calls to CreateItemL, ReplaceItemL, |
|
110 WriteItemL, CommitItemL, MoveItemL, DeleteItemL and SoftDeleteItemL will be part of this transaction. |
|
111 Their RequestStatus must be completed, even if the change is not yet really executed in the Data Store. |
|
112 If a RequestStatus is completed with an error code, the transaction has failed and a rollback must be |
|
113 done. In this case RevertTransaction will be called. |
|
114 */ |
|
115 IMPORT_C void BeginTransactionL(); |
|
116 /** |
|
117 CommitTransactionL() will be called at the end of a successful transaction. At this point in time the |
|
118 operations within the transaction are applied to the Data Store in an atomic way. If all operations |
|
119 succeed, the RequestStatus must be completed with KErrNone. If an operation fails, a rollback must be |
|
120 done and the RequestStatus must be completed with an appropriate error code. |
|
121 */ |
|
122 IMPORT_C void CommitTransactionL(TRequestStatus& aStatus); |
|
123 /** |
|
124 RevertTransaction() will be called to abort an ongoing transaction. None of the operations already |
|
125 submitted may be applied to the Data Store. The RequestStatus must be completed with KErrNone as a revert |
|
126 cannot fail. |
|
127 */ |
|
128 IMPORT_C void RevertTransaction(TRequestStatus& aStatus); |
|
129 |
|
130 public: |
|
131 /** |
|
132 BeginBatchL() starts the batch mode. During this mode calls to CreateItemL, ReplaceItemL, |
|
133 WriteItemL, CommitItemL, MoveItemL, DeleteItemL and SoftDeleteItemL will be part of this batch. |
|
134 Their RequestStatus must be completed with KErrNone, which only signals acceptance of the operation |
|
135 for batch processing. |
|
136 */ |
|
137 IMPORT_C void BeginBatchL(); |
|
138 /** |
|
139 CommitBatchL() will be called at the end of the batch mode. This tells the Data Store to |
|
140 process the batched operations (in the order they were submitted), and to append the error code |
|
141 for each operation to aResultArray. |
|
142 The error codes in aResultArray are only valid if the RequestStatus is completed with KErrNone. |
|
143 If the RequestStatus is completed with an error code none of the operations in the batch mode |
|
144 were applied to the Data Store. |
|
145 */ |
|
146 IMPORT_C void CommitBatchL(RArray<TInt>& aResultArray, TRequestStatus& aStatus); |
|
147 /** |
|
148 CancelBatch() will be called to abort an ongoing batch mode. None of the operations already |
|
149 submitted may be applied to the Data Store. |
|
150 */ |
|
151 IMPORT_C void CancelBatch(); |
|
152 |
|
153 public: |
|
154 /** |
|
155 Sets the SyncML server Data Format - this may optionally be used by the Data Provider to filter out |
|
156 properties that the server does not support, and should be used to avoid deleting these properties |
|
157 in case the server sends a changed item to the Data Provider |
|
158 */ |
|
159 IMPORT_C void SetRemoteStoreFormatL(const CSmlDataStoreFormat& aServerDataStoreFormat); |
|
160 /** |
|
161 Sets the SyncML server maximum object size - this may optionally be used by the Data Provider to not send |
|
162 items to the server exceeding its maximum size. 0 means there is no limit. |
|
163 */ |
|
164 IMPORT_C void SetRemoteMaxObjectSize(TInt aServerMaxObjectSize); |
|
165 /** |
|
166 Gets the Data Store maximum object size which is reported to the SyncML server. 0 means there is no limit. |
|
167 */ |
|
168 IMPORT_C TInt MaxObjectSize() const; |
|
169 |
|
170 IMPORT_C void OpenItemL(TSmlDbItemUid aUid, TBool& aFieldChange, TInt& aSize, TSmlDbItemUid& aParent, TDes8& aMimeType, TDes8& aMimeVer, TRequestStatus& aStatus); |
|
171 IMPORT_C void CreateItemL(TSmlDbItemUid& aUid, TInt aSize, TSmlDbItemUid aParent, const TDesC8& aMimeType, const TDesC8& aMimeVer, TRequestStatus& aStatus); |
|
172 IMPORT_C void ReplaceItemL(TSmlDbItemUid aUid, TInt aSize, TSmlDbItemUid aParent, TBool aFieldChange, TRequestStatus& aStatus); |
|
173 IMPORT_C void ReadItemL(TDes8& aBuffer); |
|
174 IMPORT_C void WriteItemL(const TDesC8& aData); |
|
175 IMPORT_C void CommitItemL(TRequestStatus& aStatus); |
|
176 IMPORT_C void CloseItem(); |
|
177 IMPORT_C void MoveItemL(TSmlDbItemUid aUid, TSmlDbItemUid aNewParent, TRequestStatus& aStatus); |
|
178 IMPORT_C void DeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus); |
|
179 IMPORT_C void SoftDeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus); |
|
180 IMPORT_C void DeleteAllItemsL(TRequestStatus& aStatus); |
|
181 public: |
|
182 IMPORT_C TBool HasSyncHistory() const; |
|
183 IMPORT_C const MSmlDataItemUidSet& AddedItems() const; |
|
184 IMPORT_C const MSmlDataItemUidSet& DeletedItems() const; |
|
185 IMPORT_C const MSmlDataItemUidSet& SoftDeletedItems() const; |
|
186 IMPORT_C const MSmlDataItemUidSet& ModifiedItems() const; |
|
187 IMPORT_C const MSmlDataItemUidSet& MovedItems() const; |
|
188 IMPORT_C void ResetChangeInfoL(TRequestStatus& aStatus); |
|
189 IMPORT_C void CommitChangeInfoL(TRequestStatus& aStatus, const MSmlDataItemUidSet& aItems); |
|
190 IMPORT_C void CommitChangeInfoL(TRequestStatus& aStatus); |
|
191 |
|
192 protected: |
|
193 // hide the virtual methods from the public interface to enable future extension without breaking BC |
|
194 virtual void DoOpenL(const TDesC& aStoreName, MSmlSyncRelationship& aContext, TRequestStatus& aStatus) = 0; |
|
195 virtual void DoCancelRequest() = 0; |
|
196 virtual const TDesC& DoStoreName() const = 0; |
|
197 virtual void DoBeginTransactionL() = 0; |
|
198 virtual void DoCommitTransactionL(TRequestStatus& aStatus) = 0; |
|
199 virtual void DoRevertTransaction(TRequestStatus& aStatus) = 0; |
|
200 virtual void DoBeginBatchL() = 0; |
|
201 virtual void DoCommitBatchL(RArray<TInt>& aResultArray, TRequestStatus& aStatus) = 0; |
|
202 virtual void DoCancelBatch() = 0; |
|
203 virtual void DoSetRemoteStoreFormatL(const CSmlDataStoreFormat& aServerDataStoreFormat) = 0; |
|
204 virtual void DoSetRemoteMaxObjectSize(TInt aServerMaxObjectSize) = 0; |
|
205 virtual TInt DoMaxObjectSize() const = 0; |
|
206 |
|
207 virtual void DoOpenItemL(TSmlDbItemUid aUid, TBool& aFieldChange, TInt& aSize, TSmlDbItemUid& aParent, TDes8& aMimeType, TDes8& aMimeVer, TRequestStatus& aStatus) = 0; |
|
208 virtual void DoCreateItemL(TSmlDbItemUid& aUid, TInt aSize, TSmlDbItemUid aParent, const TDesC8& aMimeType, const TDesC8& aMimeVer, TRequestStatus& aStatus) = 0; |
|
209 virtual void DoReplaceItemL(TSmlDbItemUid aUid, TInt aSize, TSmlDbItemUid aParent, TBool aFieldChange, TRequestStatus& aStatus) = 0; |
|
210 virtual void DoReadItemL(TDes8& aBuffer) = 0; |
|
211 virtual void DoWriteItemL(const TDesC8& aData) = 0; |
|
212 virtual void DoCommitItemL(TRequestStatus& aStatus) = 0; |
|
213 virtual void DoCloseItem() = 0; |
|
214 virtual void DoMoveItemL(TSmlDbItemUid aUid, TSmlDbItemUid aNewParent, TRequestStatus& aStatus) = 0; |
|
215 virtual void DoDeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus) = 0; |
|
216 virtual void DoSoftDeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus) = 0; |
|
217 virtual void DoDeleteAllItemsL(TRequestStatus& aStatus) = 0; |
|
218 |
|
219 virtual TBool DoHasSyncHistory() const = 0; |
|
220 virtual const MSmlDataItemUidSet& DoAddedItems() const = 0; |
|
221 virtual const MSmlDataItemUidSet& DoDeletedItems() const = 0; |
|
222 virtual const MSmlDataItemUidSet& DoSoftDeletedItems() const = 0; |
|
223 virtual const MSmlDataItemUidSet& DoModifiedItems() const = 0; |
|
224 virtual const MSmlDataItemUidSet& DoMovedItems() const = 0; |
|
225 virtual void DoResetChangeInfoL(TRequestStatus& aStatus) = 0; |
|
226 virtual void DoCommitChangeInfoL(TRequestStatus& aStatus, const MSmlDataItemUidSet& aItems) = 0; |
|
227 virtual void DoCommitChangeInfoL(TRequestStatus& aStatus) = 0; |
|
228 }; |
|
229 |
|
230 |
|
231 enum TSmlFrameworkEvent |
|
232 { |
|
233 ESmlFrameworkTaskDeleted |
|
234 }; |
|
235 |
|
236 |
|
237 /** |
|
238 ECom Data Provider interface. |
|
239 */ |
|
240 class CSmlDataProvider : public CBase |
|
241 { |
|
242 public: |
|
243 IMPORT_C static CSmlDataProvider* NewL(TSmlDataProviderId aId); |
|
244 IMPORT_C virtual ~CSmlDataProvider(); |
|
245 IMPORT_C TSmlDataProviderId Identifier() const; |
|
246 public: |
|
247 IMPORT_C void OnFrameworkEvent(TSmlFrameworkEvent, TInt aParam1, TInt aParam2); |
|
248 IMPORT_C TBool SupportsOperation(TUid aOpId) const; |
|
249 IMPORT_C const CSmlDataStoreFormat& StoreFormatL(); |
|
250 IMPORT_C CDesCArray* ListStoresLC(); |
|
251 IMPORT_C const TDesC& DefaultStoreL(); |
|
252 IMPORT_C CSmlDataStore* NewStoreInstanceLC(); |
|
253 public: |
|
254 /** |
|
255 This method returns the set of filters that can be used to send to the SyncML server. |
|
256 */ |
|
257 IMPORT_C const RPointerArray<CSyncMLFilter>& SupportedServerFiltersL(); |
|
258 |
|
259 /** |
|
260 This method checks what filters are supported by server. |
|
261 @param aServerDataStoreFormat The store format of server |
|
262 @param aFilters The array that includes filters |
|
263 @param aChangeInfo The change information about changes that data provider did |
|
264 */ |
|
265 IMPORT_C void CheckSupportedServerFiltersL(const CSmlDataStoreFormat& aServerDataStoreFormat, RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo); |
|
266 |
|
267 /** |
|
268 This method updates dynamic filters up-to-date. |
|
269 @param aFilters The array that includes filters |
|
270 @param aChangeInfo The change information about changes that data provider did |
|
271 */ |
|
272 IMPORT_C void CheckServerFiltersL(RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo); |
|
273 |
|
274 /** |
|
275 This method generates a record filter query to be sent to the SyncML server for the provided filters. |
|
276 @param aFilters The filters to be used for the query generation |
|
277 @param aMatch The filter match type to be used |
|
278 @param aFilterMimeType The mime type of the returned filter query |
|
279 @param TSyncMLFilterType The filter type of the returned filter query |
|
280 @param aStoreName The name of used store |
|
281 @return The record filter query to be sent to the SyncML server - empty if no record filter involved |
|
282 for this specific filter |
|
283 */ |
|
284 IMPORT_C HBufC* GenerateRecordFilterQueryLC(const RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterMatchType aMatch, TDes& aFilterMimeType, TSyncMLFilterType& aFilterType, TDesC& aStoreName); |
|
285 |
|
286 /** |
|
287 This method generates a field filter query to be sent to the SyncML server for the provided filters. |
|
288 NOTE: this method isn't finalised - still thinking of a way to make it SyncML DS 1.2 independent |
|
289 @param aFilters The filters to be used for the query generation |
|
290 @param aFilterMimeType The mime type of the returned filter query |
|
291 @param aProperties The field filter query to be sent to the SyncML server - empty if no field filter involved |
|
292 for this specific filter |
|
293 @param aStoreName The name of used store |
|
294 */ |
|
295 IMPORT_C void GenerateFieldFilterQueryL(const RPointerArray<CSyncMLFilter>& aFilters, TDes& aFilterMimeType, RPointerArray<CSmlDataProperty>& aProperties, TDesC& aStoreName); |
|
296 |
|
297 protected: |
|
298 // hide the virtual methods from the public interface to enable future extension without breaking BC |
|
299 virtual void DoOnFrameworkEvent(TSmlFrameworkEvent, TInt aParam1, TInt aParam2) = 0; |
|
300 virtual TBool DoSupportsOperation(TUid aOpId) const = 0; |
|
301 virtual const CSmlDataStoreFormat& DoStoreFormatL() = 0; |
|
302 virtual CDesCArray* DoListStoresLC() = 0; |
|
303 virtual const TDesC& DoDefaultStoreL() = 0; |
|
304 virtual CSmlDataStore* DoNewStoreInstanceLC() = 0; |
|
305 |
|
306 virtual const RPointerArray<CSyncMLFilter>& DoSupportedServerFiltersL() = 0; |
|
307 virtual void DoCheckSupportedServerFiltersL(const CSmlDataStoreFormat& aServerDataStoreFormat, RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo) = 0; |
|
308 virtual void DoCheckServerFiltersL(RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo) = 0; |
|
309 virtual HBufC* DoGenerateRecordFilterQueryLC(const RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterMatchType aMatch, TDes& aFilterMimeType, TSyncMLFilterType& aFilterType, TDesC& aStoreName) = 0; |
|
310 virtual void DoGenerateFieldFilterQueryL(const RPointerArray<CSyncMLFilter>& aFilters, TDes& aFilterMimeType, RPointerArray<CSmlDataProperty>& aProperties, TDesC& aStoreName) = 0; |
|
311 |
|
312 private: |
|
313 TUid iEComTag; |
|
314 TSmlDataProviderId iDPId; |
|
315 }; |
|
316 |
|
317 |
|
318 /////////////////////////////////////////////////////////////////////////////// |
|
319 /////////////////////////////////////////////////////////////////////////////// |
|
320 /////////////////////////////////////////////////////////////////////////////// |
|
321 #endif |