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 
00048     typedef enum {
00049         SYNC_STATE_NEW     = 'N',
00050         SYNC_STATE_UPDATED = 'U',
00051         SYNC_STATE_DELETED = 'D',
00052         SYNC_STATE_NONE    = ' '
00053     } SyncState;
00054 
00055     class SyncItem : public ArrayElement {
00056 
00057     private:
00058 
00059         char* data;
00060         char* encoding;
00061         long size;
00062 
00063         WCHAR key[DIM_KEY];
00064         WCHAR type[DIM_MIME_TYPE];
00065 
00066         long lastModificationTime;
00067         SyncState state;
00068 
00069         WCHAR* targetParent;
00070         WCHAR* sourceParent;
00071 
00075         void initialize();
00076 
00077     public:
00078         /*
00079          * Default constructor
00080          */
00081         SyncItem();
00082 
00083         ~SyncItem();
00084 
00085         /*
00086          * Constructs a new SyncItem identified by the given key. The key must
00087          * not be longer than DIM_KEY (see SPDS Constants).
00088          *
00089          * @param key - the key
00090          */
00091         SyncItem(const WCHAR* key);
00092 
00093         /*
00094          * Returns the SyncItem's key. If key is NULL, the internal buffer is
00095          * returned; if key is not NULL, the value is copied in the caller
00096          * allocated buffer and the given buffer pointer is returned.
00097          *
00098          * @param key - buffer where the key will be stored
00099          */
00100         const WCHAR* getKey();
00101 
00102         /*
00103          * Changes the SyncItem key. The key must not be longer than DIM_KEY
00104          * (see SPDS Constants).
00105          *
00106          * @param key - the key
00107          */
00108         void setKey(const WCHAR* key);
00109 
00110         /*
00111          * Sets the SyncItem modification timestamp. timestamp is a milliseconds
00112          * timestamp since a reference time (which is platform specific).
00113          *
00114          * @param timestamp - last modification timestamp
00115          */
00116         void setModificationTime(long timestamp);
00117 
00118         /*
00119          * Returns the SyncItem modeification timestamp. The returned value
00120          * is a milliseconds timestamp since a reference time (which is
00121          * platform specific).
00122          */
00123         long getModificationTime();
00124 
00125         /*
00126          * Sets the SyncItem content data. The passed data is copied into an
00127          * internal buffer so that the caller can release the buffer after
00128          * calling setData().
00129          *
00130          * Data which is to be sent as it is currently cannot contain nul-bytes
00131          * because it is treated like a C-style string. The size parameter should
00132          * not include the nul-byte which terminates C strings, so
00133          * pass size==0 for an empty string. A nul-byte is always
00134          * appended at the end of the data automatically.
00135          *
00136          * Binary data can be sent if it is encoded during transmission. The client
00137          * can decide which encoding to use like this:
00138          * - setData() with binary data
00139          * - changeEncoding(SyncItem::encodings::...)
00140          * or
00141          * - setData() with data that is already encoded in some way
00142          * - setDataEncoding(<the encoding name>)
00143          *
00144          * If the client neither changes nor sets the encoding, then
00145          * the default encoding specified in the SyncSource's
00146          * configuration is automatically applied by the client
00147          * library.
00148          *
00149          * @param data        memory to be copied, may be NULL; in that case an empty buffer is allocated
00150          * @param size        length of the given data or, if data is NULL, the desired buffer size
00151          */
00152         void* setData(const void* data, long size);
00153 
00154         /*
00155          * Returns the SyncItem data buffer, in read-write mode.
00156          *
00157          * There is guaranteed to be a nul-byte after the data which
00158          * is not included in the data size.
00159          */
00160         void* getData();
00161 
00162         /*
00163          * Returns the amount of bytes stored in the item,
00164          * excluding the implicit nul-byte after the real data.
00165          */
00166         long getDataSize();
00167 
00168          /*
00169          * Sets the SyncItem data size without changing the data buffer.
00170          *
00171          * @param s the new size
00172          */
00173         void setDataSize(long s);
00174 
00186         void setDataEncoding(const char* encoding);
00187 
00194         const char* getDataEncoding();
00195 
00212         int changeDataEncoding(const char* encoding, const char* encryption, const char* credentialInfo = NULL);
00213 
00214         /*
00215          * Sets the SyncItem data mime type
00216          *
00217          * @param - type the content mimetype
00218          */
00219         void setDataType(const WCHAR* type);
00220 
00221         /*
00222          * Returns the SyncItem data mime type.
00223          */
00224         const WCHAR* getDataType();
00225 
00226         /*
00227          * Sets the SyncItem state
00228          *
00229          * @param state the new SyncItem state
00230          */
00231         void setState(SyncState newState);
00232 
00233         /*
00234          * Gets the SyncItem state
00235          */
00236         SyncState getState();
00237 
00243         const WCHAR* getTargetParent();
00244 
00251         void setTargetParent(const WCHAR* parent);
00252 
00258         const WCHAR* getSourceParent();
00259 
00266         void setSourceParent(const WCHAR* parent);
00267 
00273         ArrayElement* clone();
00274 
00278         struct encodings {
00279             static const char* const plain;      
00280             static const char* const escaped;    
00281             static const char* const des;        
00285             static const char* encodingString(const char* encoding) {
00286                 return encoding ? encoding : plain;
00287             }
00288 
00290             static const BOOL isSupported(const char* encoding) {
00291                 const char* enc = encodingString(encoding);
00292                 return !strcmp(enc, plain) ||
00293                     !strcmp(enc, escaped) ||
00294                     !strcmp(enc, des);
00295             }
00296         };
00297 
00298       private:
00300         int transformData(const char* name, BOOL encode, const char* password);
00301     };
00302 
00304 #endif

Generated on Thu Mar 6 14:25:05 2008 for Funambol C++ Client Library by  doxygen 1.5.2