1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/SmlDataProvider.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,321 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: For adding content to be synchronized.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef __SMLDATAPROVIDER_H__
1.23 +#define __SMLDATAPROVIDER_H__
1.24 +//
1.25 +#include <SyncMLDef.h>
1.26 +#include <SyncMLDataFilter.h>
1.27 +#include <syncml/SmlDataSyncDefs.h>
1.28 +#include <SmlDataFormat.h>
1.29 +//
1.30 +/**
1.31 +@publishedPartner
1.32 +
1.33 +Plug-in Data Provider API.
1.34 +*/
1.35 +
1.36 +/** The parent uid to be used for the root */
1.37 +const TSmlDbItemUid KDbItemUidRoot = -1;
1.38 +
1.39 +/*
1.40 +UIDs for use with CSmlDataProvider::SupportsOperation.
1.41 +Other optional features are specified in the CSmlDataStoreFormat object
1.42 +obtained from the Data Provider.
1.43 +*/
1.44 +/**
1.45 +This UID identifies optional support for transaction operations.
1.46 +For a DBA implementation to support this operation, it must be possible to add, change, and delete items within an atomic transaction.
1.47 +*/
1.48 +const TUid KUidSmlSupportTransaction = { 0x10009FC6 };
1.49 +/**
1.50 +This UID identifies optional support for suspend and resume operations.
1.51 +For a DBA implementation to support this operation, it must be possible to to mark individual items as being 'in-sync', while other
1.52 +items remain 'out-of-sync'.
1.53 +*/
1.54 +const TUid KUidSmlSupportSuspendResume = { 0x10009FC7 };
1.55 +const TUid KUidSmlSupportBatch = { 0x10009FC8 };
1.56 +const TUid KUidSmlSupportMultipleStores = { 0x10009FC9 };
1.57 +const TUid KUidSmlSupportsUserSelectableMatchType = { 0x10009FCA };
1.58 +
1.59 +/**
1.60 +Set of Data Item LUIDs.
1.61 +*/
1.62 +class MSmlDataItemUidSet
1.63 + {
1.64 +public:
1.65 + /**
1.66 + Returns the number of items in the set.
1.67 + */
1.68 + IMPORT_C TInt ItemCount() const;
1.69 + /**
1.70 + Returns the index of the specified item UID in the set, or -1 if the item UID is not present.
1.71 + */
1.72 + IMPORT_C TInt ItemIndex(TSmlDbItemUid aItemId) const;
1.73 + /**
1.74 + Retuns the item UID at the specified index in the set.
1.75 + */
1.76 + IMPORT_C TSmlDbItemUid ItemAt(TInt aIndex) const;
1.77 +public:
1.78 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.79 +protected:
1.80 + // hide the virtual methods from the public interface to enable future extension without breaking BC
1.81 + virtual TInt DoItemCount() const = 0;
1.82 + virtual TInt DoItemIndex(TSmlDbItemUid aItemId) const = 0;
1.83 + virtual TSmlDbItemUid DoItemAt(TInt aIndex) const = 0;
1.84 + virtual void DoExternalizeL(RWriteStream& aStream) const = 0;
1.85 + };
1.86 +
1.87 +
1.88 +/**
1.89 +Data Store interface.
1.90 +*/
1.91 +class CSmlDataStore : public CBase
1.92 + {
1.93 +public:
1.94 + /**
1.95 + Opens the data store specified by aStoreName asynchronously.
1.96 + @param aStoreName The name of the data store to open.
1.97 + @param aContext Identifies the specific synchronisation relationship to use for the synchronisation.
1.98 + @param aStatus On completion of the open, contains the result code.
1.99 + */
1.100 + IMPORT_C void OpenL(const TDesC& aStoreName, MSmlSyncRelationship& aContext, TRequestStatus& aStatus);
1.101 + /**
1.102 + Cancel the current asynchronous request, including open. Only one asynchronous request may be outstanding at any one time.
1.103 + */
1.104 + IMPORT_C void CancelRequest();
1.105 +public:
1.106 + /**
1.107 + Returns the name of the open data store.
1.108 + */
1.109 + IMPORT_C const TDesC& StoreName() const;
1.110 +public:
1.111 + /**
1.112 + BeginTransactionL() starts the transaction mode. During this mode calls to CreateItemL, ReplaceItemL,
1.113 + WriteItemL, CommitItemL, MoveItemL, DeleteItemL and SoftDeleteItemL will be part of this transaction.
1.114 + Their RequestStatus must be completed, even if the change is not yet really executed in the Data Store.
1.115 + If a RequestStatus is completed with an error code, the transaction has failed and a rollback must be
1.116 + done. In this case RevertTransaction will be called.
1.117 + */
1.118 + IMPORT_C void BeginTransactionL();
1.119 + /**
1.120 + CommitTransactionL() will be called at the end of a successful transaction. At this point in time the
1.121 + operations within the transaction are applied to the Data Store in an atomic way. If all operations
1.122 + succeed, the RequestStatus must be completed with KErrNone. If an operation fails, a rollback must be
1.123 + done and the RequestStatus must be completed with an appropriate error code.
1.124 + */
1.125 + IMPORT_C void CommitTransactionL(TRequestStatus& aStatus);
1.126 + /**
1.127 + RevertTransaction() will be called to abort an ongoing transaction. None of the operations already
1.128 + submitted may be applied to the Data Store. The RequestStatus must be completed with KErrNone as a revert
1.129 + cannot fail.
1.130 + */
1.131 + IMPORT_C void RevertTransaction(TRequestStatus& aStatus);
1.132 +
1.133 +public:
1.134 + /**
1.135 + BeginBatchL() starts the batch mode. During this mode calls to CreateItemL, ReplaceItemL,
1.136 + WriteItemL, CommitItemL, MoveItemL, DeleteItemL and SoftDeleteItemL will be part of this batch.
1.137 + Their RequestStatus must be completed with KErrNone, which only signals acceptance of the operation
1.138 + for batch processing.
1.139 + */
1.140 + IMPORT_C void BeginBatchL();
1.141 + /**
1.142 + CommitBatchL() will be called at the end of the batch mode. This tells the Data Store to
1.143 + process the batched operations (in the order they were submitted), and to append the error code
1.144 + for each operation to aResultArray.
1.145 + The error codes in aResultArray are only valid if the RequestStatus is completed with KErrNone.
1.146 + If the RequestStatus is completed with an error code none of the operations in the batch mode
1.147 + were applied to the Data Store.
1.148 + */
1.149 + IMPORT_C void CommitBatchL(RArray<TInt>& aResultArray, TRequestStatus& aStatus);
1.150 + /**
1.151 + CancelBatch() will be called to abort an ongoing batch mode. None of the operations already
1.152 + submitted may be applied to the Data Store.
1.153 + */
1.154 + IMPORT_C void CancelBatch();
1.155 +
1.156 +public:
1.157 + /**
1.158 + Sets the SyncML server Data Format - this may optionally be used by the Data Provider to filter out
1.159 + properties that the server does not support, and should be used to avoid deleting these properties
1.160 + in case the server sends a changed item to the Data Provider
1.161 + */
1.162 + IMPORT_C void SetRemoteStoreFormatL(const CSmlDataStoreFormat& aServerDataStoreFormat);
1.163 + /**
1.164 + Sets the SyncML server maximum object size - this may optionally be used by the Data Provider to not send
1.165 + items to the server exceeding its maximum size. 0 means there is no limit.
1.166 + */
1.167 + IMPORT_C void SetRemoteMaxObjectSize(TInt aServerMaxObjectSize);
1.168 + /**
1.169 + Gets the Data Store maximum object size which is reported to the SyncML server. 0 means there is no limit.
1.170 + */
1.171 + IMPORT_C TInt MaxObjectSize() const;
1.172 +
1.173 + IMPORT_C void OpenItemL(TSmlDbItemUid aUid, TBool& aFieldChange, TInt& aSize, TSmlDbItemUid& aParent, TDes8& aMimeType, TDes8& aMimeVer, TRequestStatus& aStatus);
1.174 + IMPORT_C void CreateItemL(TSmlDbItemUid& aUid, TInt aSize, TSmlDbItemUid aParent, const TDesC8& aMimeType, const TDesC8& aMimeVer, TRequestStatus& aStatus);
1.175 + IMPORT_C void ReplaceItemL(TSmlDbItemUid aUid, TInt aSize, TSmlDbItemUid aParent, TBool aFieldChange, TRequestStatus& aStatus);
1.176 + IMPORT_C void ReadItemL(TDes8& aBuffer);
1.177 + IMPORT_C void WriteItemL(const TDesC8& aData);
1.178 + IMPORT_C void CommitItemL(TRequestStatus& aStatus);
1.179 + IMPORT_C void CloseItem();
1.180 + IMPORT_C void MoveItemL(TSmlDbItemUid aUid, TSmlDbItemUid aNewParent, TRequestStatus& aStatus);
1.181 + IMPORT_C void DeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus);
1.182 + IMPORT_C void SoftDeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus);
1.183 + IMPORT_C void DeleteAllItemsL(TRequestStatus& aStatus);
1.184 +public:
1.185 + IMPORT_C TBool HasSyncHistory() const;
1.186 + IMPORT_C const MSmlDataItemUidSet& AddedItems() const;
1.187 + IMPORT_C const MSmlDataItemUidSet& DeletedItems() const;
1.188 + IMPORT_C const MSmlDataItemUidSet& SoftDeletedItems() const;
1.189 + IMPORT_C const MSmlDataItemUidSet& ModifiedItems() const;
1.190 + IMPORT_C const MSmlDataItemUidSet& MovedItems() const;
1.191 + IMPORT_C void ResetChangeInfoL(TRequestStatus& aStatus);
1.192 + IMPORT_C void CommitChangeInfoL(TRequestStatus& aStatus, const MSmlDataItemUidSet& aItems);
1.193 + IMPORT_C void CommitChangeInfoL(TRequestStatus& aStatus);
1.194 +
1.195 +protected:
1.196 + // hide the virtual methods from the public interface to enable future extension without breaking BC
1.197 + virtual void DoOpenL(const TDesC& aStoreName, MSmlSyncRelationship& aContext, TRequestStatus& aStatus) = 0;
1.198 + virtual void DoCancelRequest() = 0;
1.199 + virtual const TDesC& DoStoreName() const = 0;
1.200 + virtual void DoBeginTransactionL() = 0;
1.201 + virtual void DoCommitTransactionL(TRequestStatus& aStatus) = 0;
1.202 + virtual void DoRevertTransaction(TRequestStatus& aStatus) = 0;
1.203 + virtual void DoBeginBatchL() = 0;
1.204 + virtual void DoCommitBatchL(RArray<TInt>& aResultArray, TRequestStatus& aStatus) = 0;
1.205 + virtual void DoCancelBatch() = 0;
1.206 + virtual void DoSetRemoteStoreFormatL(const CSmlDataStoreFormat& aServerDataStoreFormat) = 0;
1.207 + virtual void DoSetRemoteMaxObjectSize(TInt aServerMaxObjectSize) = 0;
1.208 + virtual TInt DoMaxObjectSize() const = 0;
1.209 +
1.210 + virtual void DoOpenItemL(TSmlDbItemUid aUid, TBool& aFieldChange, TInt& aSize, TSmlDbItemUid& aParent, TDes8& aMimeType, TDes8& aMimeVer, TRequestStatus& aStatus) = 0;
1.211 + virtual void DoCreateItemL(TSmlDbItemUid& aUid, TInt aSize, TSmlDbItemUid aParent, const TDesC8& aMimeType, const TDesC8& aMimeVer, TRequestStatus& aStatus) = 0;
1.212 + virtual void DoReplaceItemL(TSmlDbItemUid aUid, TInt aSize, TSmlDbItemUid aParent, TBool aFieldChange, TRequestStatus& aStatus) = 0;
1.213 + virtual void DoReadItemL(TDes8& aBuffer) = 0;
1.214 + virtual void DoWriteItemL(const TDesC8& aData) = 0;
1.215 + virtual void DoCommitItemL(TRequestStatus& aStatus) = 0;
1.216 + virtual void DoCloseItem() = 0;
1.217 + virtual void DoMoveItemL(TSmlDbItemUid aUid, TSmlDbItemUid aNewParent, TRequestStatus& aStatus) = 0;
1.218 + virtual void DoDeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus) = 0;
1.219 + virtual void DoSoftDeleteItemL(TSmlDbItemUid aUid, TRequestStatus& aStatus) = 0;
1.220 + virtual void DoDeleteAllItemsL(TRequestStatus& aStatus) = 0;
1.221 +
1.222 + virtual TBool DoHasSyncHistory() const = 0;
1.223 + virtual const MSmlDataItemUidSet& DoAddedItems() const = 0;
1.224 + virtual const MSmlDataItemUidSet& DoDeletedItems() const = 0;
1.225 + virtual const MSmlDataItemUidSet& DoSoftDeletedItems() const = 0;
1.226 + virtual const MSmlDataItemUidSet& DoModifiedItems() const = 0;
1.227 + virtual const MSmlDataItemUidSet& DoMovedItems() const = 0;
1.228 + virtual void DoResetChangeInfoL(TRequestStatus& aStatus) = 0;
1.229 + virtual void DoCommitChangeInfoL(TRequestStatus& aStatus, const MSmlDataItemUidSet& aItems) = 0;
1.230 + virtual void DoCommitChangeInfoL(TRequestStatus& aStatus) = 0;
1.231 + };
1.232 +
1.233 +
1.234 +enum TSmlFrameworkEvent
1.235 + {
1.236 + ESmlFrameworkTaskDeleted
1.237 + };
1.238 +
1.239 +
1.240 +/**
1.241 +ECom Data Provider interface.
1.242 +*/
1.243 +class CSmlDataProvider : public CBase
1.244 + {
1.245 +public:
1.246 + IMPORT_C static CSmlDataProvider* NewL(TSmlDataProviderId aId);
1.247 + IMPORT_C virtual ~CSmlDataProvider();
1.248 + IMPORT_C TSmlDataProviderId Identifier() const;
1.249 +public:
1.250 + IMPORT_C void OnFrameworkEvent(TSmlFrameworkEvent, TInt aParam1, TInt aParam2);
1.251 + IMPORT_C TBool SupportsOperation(TUid aOpId) const;
1.252 + IMPORT_C const CSmlDataStoreFormat& StoreFormatL();
1.253 + IMPORT_C CDesCArray* ListStoresLC();
1.254 + IMPORT_C const TDesC& DefaultStoreL();
1.255 + IMPORT_C CSmlDataStore* NewStoreInstanceLC();
1.256 +public:
1.257 + /**
1.258 + This method returns the set of filters that can be used to send to the SyncML server.
1.259 + */
1.260 + IMPORT_C const RPointerArray<CSyncMLFilter>& SupportedServerFiltersL();
1.261 +
1.262 + /**
1.263 + This method checks what filters are supported by server.
1.264 + @param aServerDataStoreFormat The store format of server
1.265 + @param aFilters The array that includes filters
1.266 + @param aChangeInfo The change information about changes that data provider did
1.267 + */
1.268 + IMPORT_C void CheckSupportedServerFiltersL(const CSmlDataStoreFormat& aServerDataStoreFormat, RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo);
1.269 +
1.270 + /**
1.271 + This method updates dynamic filters up-to-date.
1.272 + @param aFilters The array that includes filters
1.273 + @param aChangeInfo The change information about changes that data provider did
1.274 + */
1.275 + IMPORT_C void CheckServerFiltersL(RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo);
1.276 +
1.277 + /**
1.278 + This method generates a record filter query to be sent to the SyncML server for the provided filters.
1.279 + @param aFilters The filters to be used for the query generation
1.280 + @param aMatch The filter match type to be used
1.281 + @param aFilterMimeType The mime type of the returned filter query
1.282 + @param TSyncMLFilterType The filter type of the returned filter query
1.283 + @param aStoreName The name of used store
1.284 + @return The record filter query to be sent to the SyncML server - empty if no record filter involved
1.285 + for this specific filter
1.286 + */
1.287 + IMPORT_C HBufC* GenerateRecordFilterQueryLC(const RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterMatchType aMatch, TDes& aFilterMimeType, TSyncMLFilterType& aFilterType, TDesC& aStoreName);
1.288 +
1.289 + /**
1.290 + This method generates a field filter query to be sent to the SyncML server for the provided filters.
1.291 + NOTE: this method isn't finalised - still thinking of a way to make it SyncML DS 1.2 independent
1.292 + @param aFilters The filters to be used for the query generation
1.293 + @param aFilterMimeType The mime type of the returned filter query
1.294 + @param aProperties The field filter query to be sent to the SyncML server - empty if no field filter involved
1.295 + for this specific filter
1.296 + @param aStoreName The name of used store
1.297 + */
1.298 + IMPORT_C void GenerateFieldFilterQueryL(const RPointerArray<CSyncMLFilter>& aFilters, TDes& aFilterMimeType, RPointerArray<CSmlDataProperty>& aProperties, TDesC& aStoreName);
1.299 +
1.300 +protected:
1.301 + // hide the virtual methods from the public interface to enable future extension without breaking BC
1.302 + virtual void DoOnFrameworkEvent(TSmlFrameworkEvent, TInt aParam1, TInt aParam2) = 0;
1.303 + virtual TBool DoSupportsOperation(TUid aOpId) const = 0;
1.304 + virtual const CSmlDataStoreFormat& DoStoreFormatL() = 0;
1.305 + virtual CDesCArray* DoListStoresLC() = 0;
1.306 + virtual const TDesC& DoDefaultStoreL() = 0;
1.307 + virtual CSmlDataStore* DoNewStoreInstanceLC() = 0;
1.308 +
1.309 + virtual const RPointerArray<CSyncMLFilter>& DoSupportedServerFiltersL() = 0;
1.310 + virtual void DoCheckSupportedServerFiltersL(const CSmlDataStoreFormat& aServerDataStoreFormat, RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo) = 0;
1.311 + virtual void DoCheckServerFiltersL(RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterChangeInfo& aChangeInfo) = 0;
1.312 + virtual HBufC* DoGenerateRecordFilterQueryLC(const RPointerArray<CSyncMLFilter>& aFilters, TSyncMLFilterMatchType aMatch, TDes& aFilterMimeType, TSyncMLFilterType& aFilterType, TDesC& aStoreName) = 0;
1.313 + virtual void DoGenerateFieldFilterQueryL(const RPointerArray<CSyncMLFilter>& aFilters, TDes& aFilterMimeType, RPointerArray<CSmlDataProperty>& aProperties, TDesC& aStoreName) = 0;
1.314 +
1.315 +private:
1.316 + TUid iEComTag;
1.317 + TSmlDataProviderId iDPId;
1.318 + };
1.319 +
1.320 +
1.321 +///////////////////////////////////////////////////////////////////////////////
1.322 +///////////////////////////////////////////////////////////////////////////////
1.323 +///////////////////////////////////////////////////////////////////////////////
1.324 +#endif