00001 /* 00002 * Funambol is a mobile platform developed by Funambol, Inc. 00003 * Copyright (C) 2003 - 2007 Funambol, Inc. 00004 * 00005 * This program is free software; you can redistribute it and/or modify it under 00006 * the terms of the GNU Affero General Public License version 3 as published by 00007 * the Free Software Foundation with the addition of the following permission 00008 * added to Section 15 as permitted in Section 7(a): FOR ANY PART OF THE COVERED 00009 * WORK IN WHICH THE COPYRIGHT IS OWNED BY FUNAMBOL, FUNAMBOL DISCLAIMS THE 00010 * WARRANTY OF NON INFRINGEMENT OF THIRD PARTY RIGHTS. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU Affero General Public License 00018 * along with this program; if not, see http://www.gnu.org/licenses or write to 00019 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 00020 * MA 02110-1301 USA. 00021 * 00022 * You can contact Funambol, Inc. headquarters at 643 Bair Island Road, Suite 00023 * 305, Redwood City, CA 94063, USA, or at email address info@funambol.com. 00024 * 00025 * The interactive user interfaces in modified source and object code versions 00026 * of this program must display Appropriate Legal Notices, as required under 00027 * Section 5 of the GNU Affero General Public License version 3. 00028 * 00029 * In accordance with Section 7(b) of the GNU Affero General Public License 00030 * version 3, these Appropriate Legal Notices must retain the display of the 00031 * "Powered by Funambol" logo. If the display of the logo is not reasonably 00032 * feasible for technical reasons, the Appropriate Legal Notices must display 00033 * the words "Powered by Funambol". 00034 */ 00035 00036 #ifndef INCL_SYNC_SOURCE 00037 #define INCL_SYNC_SOURCE 00038 /** @cond API */ 00039 /** @addtogroup Client */ 00040 /** @{ */ 00041 00042 #include "base/fscapi.h" 00043 #include "base/ErrorHandler.h" 00044 #include "base/util/ArrayElement.h" 00045 #include "filter/SourceFilter.h" 00046 #include "spds/constants.h" 00047 #include "spds/SyncItem.h" 00048 #include "spds/SyncStatus.h" 00049 #include "spds/AbstractSyncSourceConfig.h" 00050 #include "spds/SyncSourceReport.h" 00051 #include "base/globalsdef.h" 00052 00053 BEGIN_NAMESPACE 00054 00055 /** 00056 * This is the main API that a SyncML client developer needs to implement 00057 * to let the sync engine access the client's data. Each client may provide 00058 * access to one or more sources. 00059 */ 00060 class SyncSource { 00061 00062 private: 00063 SyncMode syncMode; 00064 unsigned long lastSync; 00065 unsigned long nextSync; 00066 WCHAR* name; 00067 00068 char next[DIM_ANCHOR]; 00069 char last[DIM_ANCHOR]; 00070 00071 SourceFilter* filter; 00072 00073 protected: 00074 AbstractSyncSourceConfig* config; 00075 SyncSourceReport* report; 00076 00077 /** 00078 * copies all elements, to be used by derived class' clone() implementation 00079 */ 00080 void assign(SyncSource& s); 00081 00082 public: 00083 00084 /** 00085 * Constructor: create a SyncSource with the specified name 00086 * 00087 * @param name the name of the SyncSource 00088 * @param sc configuration for the sync source: the instance 00089 * must remain valid throughout the lifetime of the 00090 * sync source because it keeps a reference to it 00091 * and uses it as its own. A NULL pointer is allowed 00092 * for unit testing outside of the sync framework; 00093 * the sync source then references a global config 00094 * instance to avoid crashes, but modifying that config 00095 * will not make much sense. The pointer may also be 00096 * set directly after creating the SyncSource, which 00097 * is useful when a derived class creates the config 00098 * in its own constructor. 00099 */ 00100 SyncSource(const WCHAR* name, AbstractSyncSourceConfig* sc); 00101 00102 // Destructor 00103 virtual ~SyncSource(); 00104 00105 /** 00106 * Get the source name. 00107 * 00108 * @return - the source name (a pointer to the object buffer, 00109 * will be released at object destruction) 00110 * 00111 */ 00112 const WCHAR *getName(); 00113 00114 /********************************************************** 00115 * Most of the configurable properties are read 00116 * by the client library from the config (in 00117 * SyncClient::setDMConfig()) and then copied into the 00118 * sync source. 00119 * 00120 * These properties are stored in a local copy which will not be 00121 * written back into the permanent config, with a few exceptions: 00122 * properties related to mananging sync sessions like lastAnchor 00123 * are written back into the config by the library afer a 00124 * successful synchronization. 00125 * 00126 * A client developer is not required to modify these calls, 00127 * but he can use and/or update the properties before the 00128 * synchronization starts. 00129 *********************************************************/ 00130 00131 /** 00132 * use this directly after constructing the source when passing 00133 * the configuration to the constructor directly is not possible 00134 */ 00135 void setConfig(AbstractSyncSourceConfig* sc); 00136 00137 /** read-only access to configuration */ 00138 const AbstractSyncSourceConfig& getConfig() const; 00139 /** read-write access to configuration */ 00140 AbstractSyncSourceConfig& getConfig(); 00141 00142 00143 00144 /** 00145 * Return pointer to report object. 00146 */ 00147 SyncSourceReport* getReport(); 00148 00149 /** 00150 * Set the report pointer with the given one 00151 * (no copy, only assign the pointer to the external one) 00152 * 00153 * @param sr the report for this sync source 00154 */ 00155 void setReport(SyncSourceReport* sr); 00156 00157 /** 00158 * Get & Set the preferred synchronization mode for the SyncSource. 00159 * 00160 * Taken initially from the configuration by setConfig(), it can then 00161 * be modified by the client. The code synchronization code itself 00162 * reads this value, but it doesn't modify it. 00163 */ 00164 SyncMode getPreferredSyncMode(); 00165 void setPreferredSyncMode(SyncMode syncMode); 00166 00167 /** 00168 * Get & Sets the server imposed synchronization mode for the SyncSource. 00169 * 00170 * Agreed upon with the server during the initial exchange with the server. 00171 * The SyncSource can react to it in beginSync(), in particular it must wipe 00172 * its local data during a refresh from server. 00173 */ 00174 SyncMode getSyncMode(); 00175 void setSyncMode(SyncMode syncMode); 00176 00177 /** 00178 * Get & Set the timestamp in milliseconds of the last synchronization. 00179 * The reference time of the timestamp is platform specific. 00180 */ 00181 unsigned long getLastSync(); 00182 void setLastSync(unsigned long timestamp); 00183 00184 /** 00185 * Gets & Sets the timestamp in milliseconds of the next synchronization. 00186 * The reference time of the timestamp is platform specific. 00187 */ 00188 unsigned long getNextSync(); 00189 void setNextSync(unsigned long timestamp); 00190 00191 /** 00192 * Gets & Sets the last anchor associated to the source 00193 */ 00194 void setLastAnchor(const char* last); 00195 const char* getLastAnchor(); 00196 00197 /** 00198 * Gets & Sets the next anchor associated to the source 00199 */ 00200 const char* getNextAnchor(); 00201 void setNextAnchor(const char* next); 00202 00203 /** 00204 * Gets filter 00205 */ 00206 SourceFilter* getFilter(); 00207 00208 /** 00209 * Sets filter 00210 * 00211 * @param f the new filter 00212 * 00213 */ 00214 void setFilter(SourceFilter* f); 00215 00216 /****************************************************** 00217 * The following methods are virtual because a 00218 * derived SyncSource is expected to override or 00219 * implement them. Only the pure virtual methods 00220 * really have to be implemented, the others have 00221 * reasonable defaults. 00222 *****************************************************/ 00223 00224 /** 00225 * Called by the engine from inside SyncClient::sync() 00226 * at the begin of the sync. 00227 * 00228 * The SyncSource can do every initialization it needs. 00229 * The server has been contacted, so in particular 00230 * getSyncMode() can now be used to find out what 00231 * the sync mode for this synchronization run will be. 00232 * After this call the iterators for SyncItems must return 00233 * valid results for the current sync mode. 00234 * 00235 * The synchronization stops if this function return a non-zero value. 00236 * 00237 * @return - 0 on success, an error otherwise 00238 */ 00239 virtual int beginSync(); 00240 00241 /** 00242 * Called by the engine from inside SyncClient::sync() 00243 * at the end of the sync. 00244 * 00245 * The SyncSource can do any needed commit action to save 00246 * the state of the items. The engine commits to the server 00247 * the changes applied in the transaction only if this function 00248 * return 0. 00249 * 00250 * FIXME: the return code is currently ignored by the sync engine 00251 * 00252 * @return - 0 on success, an error otherwise 00253 */ 00254 virtual int endSync(); 00255 00256 /** 00257 * called by the sync engine with the status returned by the 00258 * server for a certain item that the client sent to the server 00259 * 00260 * @param key the local key of the item 00261 * @param status the SyncML status returned by the server 00262 * @deprecated 00263 * @since SyncML API v7 00264 */ 00265 virtual void setItemStatus(const WCHAR* /* key */, int /* status */) {} 00266 00267 /** 00268 * called by the sync engine with the status returned by the 00269 * server for a certain item that the client sent to the server. 00270 * It contains also the proper command associated to the item. 00271 * 00272 * @param key the local key of the item 00273 * @param status the SyncML status returned by the server 00274 * @param command the SyncML command associated to the item 00275 00276 */ 00277 virtual void setItemStatus(const WCHAR* key, int status, 00278 const char* /* command */) { 00279 setItemStatus(key, status); 00280 } 00281 00282 /** 00283 * Indicates that all the server status of the current package 00284 * of the client items has been processed by the engine. 00285 * This signal can be useful to update the modification arrays 00286 */ 00287 virtual void serverStatusPackageEnded(); 00288 00289 /** 00290 * Indicates that all the client status of the current package 00291 * of the server items that has been processed by the client and 00292 * are going to be sent to the server. 00293 * This signal can be useful to update the modification arrays 00294 */ 00295 virtual void clientStatusPackageEnded(); 00296 00297 /** 00298 * Removes all the item of the sync source. It is called 00299 * by the engine in the case of a refresh from server to clean 00300 * all the client items before receiving the server ones. 00301 * It is called after the beginSync() method. 00302 * 00303 *@return 0 if the remote succeded. 00304 */ 00305 virtual int removeAllItems() = 0; 00306 00307 /** 00308 * Return the key of the first SyncItem of all. 00309 * It is used in case of refresh sync 00310 * and retrieve all the keys of the data source. 00311 */ 00312 virtual SyncItem* getFirstItemKey() = 0; 00313 00314 /** 00315 * Return the key of the next SyncItem of all. 00316 * It is used in case of refresh sync 00317 * and retrieve all the keys of the data source. 00318 */ 00319 virtual SyncItem* getNextItemKey() = 0; 00320 00321 /** 00322 * Return the first SyncItem of all. 00323 * It is used in case of slow sync 00324 * and retrieve the entire data source content. 00325 */ 00326 virtual SyncItem* getFirstItem() = 0; 00327 00328 /** 00329 * Return the next SyncItem of all. 00330 * It is used in case of slow sync 00331 * and retrieve the entire data source content. 00332 */ 00333 virtual SyncItem* getNextItem() = 0; 00334 00335 /** 00336 * Return the first SyncItem of new one. It is used in case of fast sync 00337 * and retrieve the new data source content. 00338 */ 00339 virtual SyncItem* getFirstNewItem() = 0; 00340 00341 /** 00342 * Return the next SyncItem of new one. It is used in case of fast sync 00343 * and retrieve the new data source content. 00344 */ 00345 virtual SyncItem* getNextNewItem() = 0; 00346 00347 /** 00348 * Return the first SyncItem of updated one. It is used in case of fast sync 00349 * and retrieve the new data source content. 00350 */ 00351 virtual SyncItem* getFirstUpdatedItem() = 0; 00352 00353 /** 00354 * Return the next SyncItem of updated one. It is used in case of fast sync 00355 * and retrieve the new data source content. 00356 */ 00357 virtual SyncItem* getNextUpdatedItem() = 0; 00358 00359 /** 00360 * Return the first SyncItem of updated one. It is used in case of fast sync 00361 * and retrieve the new data source content. 00362 */ 00363 virtual SyncItem* getFirstDeletedItem() = 0; 00364 00365 /** 00366 * Return the next SyncItem of updated one. It is used in case of fast sync 00367 * and retrieve the new data source content. 00368 */ 00369 virtual SyncItem* getNextDeletedItem() = 0; 00370 00371 /** 00372 * Called by the sync engine to add an item that the server has sent. 00373 * The sync source is expected to add it to its database, then set the 00374 * key to the local key assigned to the new item. Alternatively 00375 * the sync source can match the new item against one of the existing 00376 * items and return that key. 00377 * 00378 * @param item the item as sent by the server 00379 * @return SyncML status code 00380 */ 00381 virtual int addItem(SyncItem& item) = 0; 00382 00383 /** 00384 * Called by the sync engine to update an item that the source already 00385 * should have. The item's key is the local key of that item. 00386 * 00387 * @param item the item as sent by the server 00388 * @return SyncML status code 00389 */ 00390 virtual int updateItem(SyncItem& item) = 0; 00391 00392 /** 00393 * Called by the sync engine to update an item that the source already 00394 * should have. The item's key is the local key of that item, no data is 00395 * provided. 00396 * 00397 * @param item the item as sent by the server 00398 */ 00399 virtual int deleteItem(SyncItem& item) = 0; 00400 00401 00402 00403 }; 00404 00405 00406 END_NAMESPACE 00407 00408 /** @} */ 00409 /** @endcond */ 00410 #endif
1.5.7.1