src/include/common/spds/SyncItem.h

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 
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 
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 
00189         void setDataEncoding(const char* encoding);
00190 
00197         const char* getDataEncoding() const;
00198 
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 
00246         const WCHAR* getTargetParent() const;
00247 
00254         void setTargetParent(const WCHAR* parent);
00255 
00261         const WCHAR* getSourceParent() const;
00262 
00269         void setSourceParent(const WCHAR* parent);
00270 
00276         ArrayElement* clone();
00277 
00281         struct encodings {
00282             static const char* const plain;      
00283             static const char* const escaped;    
00284             static const char* const des;        
00288             static const char* encodingString(const char* encoding) {
00289                 return encoding ? encoding : plain;
00290             }
00291 
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:
00303         int transformData(const char* name, bool encode, const char* password);
00304     };
00305 
00306 
00307 END_NAMESPACE
00308 
00310 #endif

Generated on Fri Jul 25 15:04:15 2008 for Funambol C++ Client Library by  doxygen 1.5.1