src/include/common/spds/SyncItem.h

/*
 * Copyright (C) 2003-2007 Funambol
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

 #ifndef INCL_SYNC_ITEM
    #define INCL_SYNC_ITEM

    #include "base/fscapi.h"
    #include "base/constants.h"
    #include "base/util/ArrayElement.h"
    #include "spds/constants.h"
    #include "spds/SyncStatus.h"

    #include <string.h>

    typedef enum {
        SYNC_STATE_NEW     = 'N',
        SYNC_STATE_UPDATED = 'U',
        SYNC_STATE_DELETED = 'D',
        SYNC_STATE_NONE    = ' '
    } SyncState;

    class SyncItem : public ArrayElement {

    private:

        char* data;
        char* encoding;
        long size;

        WCHAR key[DIM_KEY];
        WCHAR type[DIM_MIME_TYPE];

        long lastModificationTime;
        SyncState state;

        WCHAR* targetParent;
        WCHAR* sourceParent;

        void initialize() EXTRA_SECTION_01;

    public:
        /*
         * Default constructor
         */
        SyncItem() EXTRA_SECTION_01;

        ~SyncItem() EXTRA_SECTION_01;

        /*
         * Constructs a new SyncItem identified by the given key. The key must
         * not be longer than DIM_KEY (see SPDS Constants).
         *
         * @param key - the key
         */
        SyncItem(const WCHAR* key) EXTRA_SECTION_01;

        /*
         * Returns the SyncItem's key. If key is NULL, the internal buffer is
         * returned; if key is not NULL, the value is copied in the caller
         * allocated buffer and the given buffer pointer is returned.
         *
         * @param key - buffer where the key will be stored
         */
        const WCHAR* getKey() EXTRA_SECTION_01;

        /*
         * Changes the SyncItem key. The key must not be longer than DIM_KEY
         * (see SPDS Constants).
         *
         * @param key - the key
         */
        void setKey(const WCHAR* key) EXTRA_SECTION_01;

        /*
         * Sets the SyncItem modification timestamp. timestamp is a milliseconds
         * timestamp since a reference time (which is platform specific).
         *
         * @param timestamp - last modification timestamp
         */
        void setModificationTime(long timestamp) EXTRA_SECTION_01;

        /*
         * Returns the SyncItem modeification timestamp. The returned value
         * is a milliseconds timestamp since a reference time (which is
         * platform specific).
         */
        long getModificationTime() EXTRA_SECTION_01;

        /*
         * Sets the SyncItem content data. The passed data is copied into an
         * internal buffer so that the caller can release the buffer after
         * calling setData().
         *
         * Data which is to be sent as it is currently cannot contain nul-bytes
         * because it is treated like a C-style string. The size parameter should
         * not include the nul-byte which terminates C strings, so
         * pass size==0 for an empty string. A nul-byte is always
         * appended at the end of the data automatically.
         *
         * Binary data can be sent if it is encoded during transmission. The client
         * can decide which encoding to use like this:
         * - setData() with binary data
         * - changeEncoding(SyncItem::encodings::...)
         * or
         * - setData() with data that is already encoded in some way
         * - setDataEncoding(<the encoding name>) 
         *
         * If the client neither changes nor sets the encoding, then
         * the default encoding specified in the SyncSource's
         * configuration is automatically applied by the client
         * library.
         *
         * @param data        memory to be copied, may be NULL; in that case an empty buffer is allocated
         * @param size        length of the given data or, if data is NULL, the desired buffer size
         */
        void* setData(const void* data, long size) EXTRA_SECTION_01;

        /*
         * Returns the SyncItem data buffer, in read-write mode.
         *
         * There is guaranteed to be a nul-byte after the data which
         * is not included in the data size.
         */
        void* getData() EXTRA_SECTION_01;

        /*
         * Returns the amount of bytes stored in the item,
         * excluding the implicit nul-byte after the real data.
         */
        long getDataSize() EXTRA_SECTION_01;
        
         /*
         * Sets the SyncItem data size without changing the data buffer.
         *
         * @param s the new size
         */
        void setDataSize(long s) EXTRA_SECTION_01;

        void setDataEncoding(const char* encoding) EXTRA_SECTION_01;

        const char* getDataEncoding() EXTRA_SECTION_01;

        int changeDataEncoding(const char* encoding, const char* encryption, const char* credentialInfo = NULL) EXTRA_SECTION_01;

        /*
         * Sets the SyncItem data mime type
         *
         * @param - type the content mimetype
         */
        void setDataType(const WCHAR* type) EXTRA_SECTION_01;

        /*
         * Returns the SyncItem data mime type.
         */
        const WCHAR* getDataType() EXTRA_SECTION_01;

        /*
         * Sets the SyncItem state
         *
         * @param state the new SyncItem state
         */
        void setState(SyncState newState) EXTRA_SECTION_01;

        /*
         * Gets the SyncItem state
         */
        SyncState getState() EXTRA_SECTION_01;

        const WCHAR* getTargetParent() EXTRA_SECTION_01;
    
        void setTargetParent(const WCHAR* parent) EXTRA_SECTION_01;    

        const WCHAR* getSourceParent() EXTRA_SECTION_01;
    
        void setSourceParent(const WCHAR* parent) EXTRA_SECTION_01;

        ArrayElement* clone() EXTRA_SECTION_01;

        struct encodings {
            static const char* const plain;      
            static const char* const escaped;    
            static const char* const des;        
            static const char* encodingString(const char* encoding) {
                return encoding ? encoding : plain;
            }

            static const BOOL isSupported(const char* encoding) {
                const char* enc = encodingString(encoding);
                return !strcmp(enc, plain) ||
                    !strcmp(enc, escaped) ||
                    !strcmp(enc, des);
            }
        };

      private:
        int transformData(const char* name, BOOL encode, const char* password);
    };

#endif

---