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_SYNCCLIENT 00037 #define INCL_SYNCCLIENT 00038 /** @cond API */ 00039 /** @addtogroup Client */ 00040 /** @{ */ 00041 00042 #include "base/fscapi.h" 00043 #include "base/Log.h" 00044 #include "spds/AbstractSyncConfig.h" 00045 #include "spds/SyncSource.h" 00046 #include "spds/constants.h" 00047 #include "spds/SyncReport.h" 00048 #include "base/globalsdef.h" 00049 00050 BEGIN_NAMESPACE 00051 00052 /** 00053 * This class wraps the common operations executed by a typical 00054 * client. It contains default implementations for calls invoked 00055 * by the library core to parameterize or control the 00056 * synchronization. A client can override these calls by 00057 * subclassing SyncClient and using an instance of its own class 00058 * instead. 00059 * 00060 * Warning: the library contains global data in several different 00061 * places. Therefore it is not possible to execute multiple 00062 * sessions in parallel. 00063 */ 00064 class SyncClient { 00065 public: 00066 00067 SyncClient(); 00068 virtual ~SyncClient(); 00069 00070 /* 00071 * Execute a synchronization on the specified sources. 00072 * The sources will be configured automatically using the 00073 * client configuration set in the constructor. 00074 * 00075 * @param config - the configuration to be used for this sync 00076 * @param sources - NULL terminated array of sources to sync. 00077 * 00078 * @return - 0 on success, an error otherwise 00079 */ 00080 virtual int sync(AbstractSyncConfig& config, SyncSource** sources); 00081 00082 /** 00083 * Execute a synchronization with sources that are chosen based 00084 * on the sourceNames param or, if sourceNames is NULL, based 00085 * on the configuration: in this case all available sources will be used. 00086 * 00087 * - calls prepareSync() to give a derived class the chance to 00088 * setup syncing and get ready for creating sources 00089 * - iterates over sources to sync, asks for the corresponding 00090 * client source with createSource() 00091 * - calls beginSync() to give the derived class a class to do 00092 * after all sources have been configured successfully 00093 * - executes the synchronization: call sync(sources**) 00094 * 00095 * This version of the call is easier to use for clients whose 00096 * sync sources are determined by the configuration or by an array 00097 * of desired sources to sync 00098 * 00099 * @param config: the configuration to be used for this sync 00100 * @param sourceNames: optional, a NULL terminated array of source names that 00101 * we want to sync. If NULL, sources to sync are chosen 00102 * from the configuration. 00103 * @return 0 on success, an error otherwise 00104 */ 00105 virtual int sync(AbstractSyncConfig& config, char** sourceNames = NULL); 00106 00107 /* 00108 * Returns a pointer to the internal syncReport. 00109 * Used to get detailed results on the executed synchronization. 00110 * Must be called after sync() method. 00111 */ 00112 SyncReport* getSyncReport(); 00113 00114 00115 protected: 00116 /** 00117 * A callback into a derived class which is called after 00118 * reading the SyncML configuration and before creating sources. 00119 * Not used by the sync(SyncSource**) call. 00120 * 00121 * @param config a reference to SyncManager configuration 00122 * can be used to read client specific properties 00123 * @return 0 for success, an error code otherwise - an error code 00124 * aborts the whole synchronization 00125 */ 00126 virtual int prepareSync(AbstractSyncConfig& /* config */) { 00127 return ERR_NONE; 00128 } 00129 00130 /** 00131 * A factory method that is used by the sync() call to create 00132 * the sync sources that are to be synchronized. Not used by the 00133 * sync(SyncSource**) call. 00134 * 00135 * @param name name of the sync source 00136 * @param pos position of the SyncSource in the SSConfig array 00137 * (index: 0 - numSources-1) 00138 * @param config a pointer to the source's configuration: this 00139 * includes all properties that the client library 00140 * knows and uses itself (only valid during this call) 00141 * This pointer is owned by AbstractSyncConfig, sources uses it 00142 * to initialize the internal config by reference. 00143 * @retval source the sync source created by the client or NULL if 00144 * there is no sync source currently associated with 00145 * the config or it is inactive; instance is a new SyncSource* 00146 * and it's freed by the caller (see finally) 00147 * @return 0 for success, an error code otherwise - an error code 00148 * aborts the whole synchronization and the value of *source is 00149 * ignored 00150 */ 00151 virtual int createSyncSource(const char * /* name */, const int /* pos */, 00152 AbstractSyncSourceConfig* /* config */, 00153 SyncSource **source) { 00154 *source = NULL; 00155 return ERR_UNSPECIFIED; 00156 } 00157 00158 /** 00159 * Callback invoked after creating all sources. 00160 * @return 0 for success, an error code otherwise - an error code stops 00161 * immediately 00162 */ 00163 virtual int beginSync(SyncSource ** /* source */) { 00164 return ERR_NONE; 00165 } 00166 00167 /** 00168 * Callback invoked after the sync process. 00169 * @return: 0 for success, an error code otherwise 00170 */ 00171 virtual int endSync(SyncSource ** /* source */) { 00172 return ERR_NONE; 00173 } 00174 00175 /** 00176 * Callback invoked after the prepareSync function. 00177 * @return 0 for success, an error code otherwise - an error code stops 00178 * immediately 00179 */ 00180 virtual int continueAfterPrepareSync() { 00181 return ERR_NONE; 00182 } 00183 00184 /** 00185 * Callback invoked after the sync function. 00186 * @return: 0 for success, an error code otherwise 00187 */ 00188 virtual int continueAfterSync() { 00189 return ERR_NONE; 00190 } 00191 00192 // The report of the synchronization process. 00193 // Sources reports are initializated during sync(sources**) call. 00194 SyncReport syncReport; 00195 }; 00196 00197 00198 END_NAMESPACE 00199 00200 /** @} */ 00201 /** @endcond */ 00202 #endif 00203