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_ITEM 00037 #define INCL_SYNC_ITEM 00038 /** @cond DEV */ 00039 00040 #include "base/fscapi.h" 00041 #include "base/constants.h" 00042 #include "base/util/ArrayElement.h" 00043 #include "spds/constants.h" 00044 #include "spds/SyncStatus.h" 00045 00046 #include <string.h> 00047 #include "base/globalsdef.h" 00048 00049 BEGIN_NAMESPACE 00050 00051 typedef enum { 00052 SYNC_STATE_NEW = 'N', 00053 SYNC_STATE_UPDATED = 'U', 00054 SYNC_STATE_DELETED = 'D', 00055 SYNC_STATE_NONE = ' ' 00056 } SyncState; 00057 00058 class SyncItem : public ArrayElement { 00059 00060 private: 00061 00062 char* data; 00063 char* encoding; 00064 long size; 00065 00066 WCHAR key[DIM_KEY]; 00067 WCHAR type[DIM_MIME_TYPE]; 00068 00069 long lastModificationTime; 00070 SyncState state; 00071 00072 WCHAR* targetParent; 00073 WCHAR* sourceParent; 00074 00075 /** 00076 * Initializes private members 00077 */ 00078 void initialize(); 00079 00080 public: 00081 /* 00082 * Default constructor 00083 */ 00084 SyncItem(); 00085 00086 ~SyncItem(); 00087 00088 /* 00089 * Constructs a new SyncItem identified by the given key. The key must 00090 * not be longer than DIM_KEY (see SPDS Constants). 00091 * 00092 * @param key - the key 00093 */ 00094 SyncItem(const WCHAR* key); 00095 00096 /* 00097 * Returns the SyncItem's key. If key is NULL, the internal buffer is 00098 * returned; if key is not NULL, the value is copied in the caller 00099 * allocated buffer and the given buffer pointer is returned. 00100 * 00101 * @param key - buffer where the key will be stored 00102 */ 00103 const WCHAR* getKey() const; 00104 00105 /* 00106 * Changes the SyncItem key. The key must not be longer than DIM_KEY 00107 * (see SPDS Constants). 00108 * 00109 * @param key - the key 00110 */ 00111 void setKey(const WCHAR* key); 00112 00113 /* 00114 * Sets the SyncItem modification timestamp. timestamp is a milliseconds 00115 * timestamp since a reference time (which is platform specific). 00116 * 00117 * @param timestamp - last modification timestamp 00118 */ 00119 void setModificationTime(long timestamp); 00120 00121 /* 00122 * Returns the SyncItem modeification timestamp. The returned value 00123 * is a milliseconds timestamp since a reference time (which is 00124 * platform specific). 00125 */ 00126 long getModificationTime() const; 00127 00128 /* 00129 * Sets the SyncItem content data. The passed data is copied into an 00130 * internal buffer so that the caller can release the buffer after 00131 * calling setData(). 00132 * 00133 * Data which is to be sent as it is currently cannot contain nul-bytes 00134 * because it is treated like a C-style string. The size parameter should 00135 * not include the nul-byte which terminates C strings, so 00136 * pass size==0 for an empty string. A nul-byte is always 00137 * appended at the end of the data automatically. 00138 * 00139 * Binary data can be sent if it is encoded during transmission. The client 00140 * can decide which encoding to use like this: 00141 * - setData() with binary data 00142 * - changeEncoding(SyncItem::encodings::...) 00143 * or 00144 * - setData() with data that is already encoded in some way 00145 * - setDataEncoding(<the encoding name>) 00146 * 00147 * If the client neither changes nor sets the encoding, then 00148 * the default encoding specified in the SyncSource's 00149 * configuration is automatically applied by the client 00150 * library. 00151 * 00152 * @param data memory to be copied, may be NULL; in that case an empty buffer is allocated 00153 * @param size length of the given data or, if data is NULL, the desired buffer size 00154 */ 00155 void* setData(const void* data, long size); 00156 00157 /* 00158 * Returns the SyncItem data buffer, in read-write mode. 00159 * 00160 * There is guaranteed to be a nul-byte after the data which 00161 * is not included in the data size. 00162 */ 00163 void* getData() const; 00164 00165 /* 00166 * Returns the amount of bytes stored in the item, 00167 * excluding the implicit nul-byte after the real data. 00168 */ 00169 long getDataSize() const; 00170 00171 /* 00172 * Sets the SyncItem data size without changing the data buffer. 00173 * 00174 * @param s the new size 00175 */ 00176 void setDataSize(long s); 00177 00178 /** 00179 * Sets the encoding of the data _without_ changing the data itself. 00180 * The only use of calling this directly in a SyncML client is to 00181 * send data in an encoding that the library itself does not support. 00182 * Otherwise changeDataEncoding() should be used if the default behavior 00183 * is not sufficient. 00184 * 00185 * @param encoding this string is sent to the server and must be 00186 * supported by it, see the constants in SyncItem::encoding 00187 * for supported values; NULL means plain data 00188 */ 00189 void setDataEncoding(const char* encoding); 00190 00191 /** 00192 * Gets the encoding of the data. May return NULL if none has been set. 00193 * 00194 * Note that for incoming items the client library automatically converts 00195 * to plain encoding unless the server uses an unknown encoding. 00196 */ 00197 const char* getDataEncoding() const; 00198 00199 /** 00200 * Changes the encoding and the data currently stored in the item. 00201 * Transformation to and from the encodings listed in SyncItem::encoding 00202 * are supported. 00203 * 00204 * Some encodings may require additional information (TBD). 00205 * 00206 * @param encoding see SyncItem::encoding for valid encodings 00207 * @param encryption if not NULL, this is the encryption to be used. Encrypted data 00208 * is then encoded in base64 to be sent in syncML messages, so if 00209 * this value is not NULL the 'encoding' parameter is ignored. 00210 * Actually the only valid value is "des". 00211 * @param credentialInfo optional additional information: password for DES encryption 00212 * @return error code, usually caused by unsupported encoding either of 00213 * the current data or the requested new encoding 00214 */ 00215 int changeDataEncoding(const char* encoding, const char* encryption, const char* credentialInfo = NULL); 00216 00217 /* 00218 * Sets the SyncItem data mime type 00219 * 00220 * @param - type the content mimetype 00221 */ 00222 void setDataType(const WCHAR* type); 00223 00224 /* 00225 * Returns the SyncItem data mime type. 00226 */ 00227 const WCHAR* getDataType() const; 00228 00229 /* 00230 * Sets the SyncItem state 00231 * 00232 * @param state the new SyncItem state 00233 */ 00234 void setState(SyncState newState); 00235 00236 /* 00237 * Gets the SyncItem state 00238 */ 00239 SyncState getState() const; 00240 00241 /** 00242 * Returns the SyncItem targetParent 00243 * 00244 * @return the SyncItem target parent 00245 */ 00246 const WCHAR* getTargetParent() const; 00247 00248 /** 00249 * Sets the SyncItem targetParent 00250 * 00251 * @param parent the target parent 00252 * 00253 */ 00254 void setTargetParent(const WCHAR* parent); 00255 00256 /** 00257 * Returns the SyncItem sourceParent 00258 * 00259 * @return the SyncItem source parent 00260 */ 00261 const WCHAR* getSourceParent() const; 00262 00263 /** 00264 * Sets the SyncItem sourceParent 00265 * 00266 * @param parent the source parent 00267 * 00268 */ 00269 void setSourceParent(const WCHAR* parent); 00270 00271 /** 00272 * Creates a new instance of SyncItem from the content of this 00273 * object. The new instance is created the the C++ new operator and 00274 * must be removed with the C++ delete operator. 00275 */ 00276 ArrayElement* clone(); 00277 00278 /** 00279 * valid encodings for changeDataEncoding() and some helper functions 00280 */ 00281 struct encodings { 00282 static const char* const plain; /**< data is transferred as it is */ 00283 static const char* const escaped; /**< base64 encoded during transfer */ 00284 static const char* const des; /**< encrypted with DES and then base64 encoded; beware, 00285 non-standard and only supported by some servers */ 00286 00287 /** helper function which turns NULL into plain */ 00288 static const char* encodingString(const char* encoding) { 00289 return encoding ? encoding : plain; 00290 } 00291 00292 /** returns true if and only if the encoding is one of the supported ones */ 00293 static const bool isSupported(const char* encoding) { 00294 const char* enc = encodingString(encoding); 00295 return !strcmp(enc, plain) || 00296 !strcmp(enc, escaped) || 00297 !strcmp(enc, des); 00298 } 00299 }; 00300 00301 private: 00302 /** encode or decode the item's data with the named transformation */ 00303 int transformData(const char* name, bool encode, const char* password); 00304 }; 00305 00306 00307 END_NAMESPACE 00308 00309 /** @endcond */ 00310 #endif