src/client-api/src/include/windows/vocl/WinItem.h

   1 /*
   2  * Funambol is a mobile platform developed by Funambol, Inc.
   3  * Copyright (C) 2003 - 2007 Funambol, Inc.
   4  *
   5  * This program is free software; you can redistribute it and/or modify it under
   6  * the terms of the GNU Affero General Public License version 3 as published by
   7  * the Free Software Foundation with the addition of the following permission
   8  * added to Section 15 as permitted in Section 7(a): FOR ANY PART OF THE COVERED
   9  * WORK IN WHICH THE COPYRIGHT IS OWNED BY FUNAMBOL, FUNAMBOL DISCLAIMS THE
  10  * WARRANTY OF NON INFRINGEMENT  OF THIRD PARTY RIGHTS.
  11  *
  12  * This program is distributed in the hope that it will be useful, but WITHOUT
  13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  14  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  15  * details.
  16  *
  17  * You should have received a copy of the GNU Affero General Public License
  18  * along with this program; if not, see http://www.gnu.org/licenses or write to
  19  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  20  * MA 02110-1301 USA.
  21  *
  22  * You can contact Funambol, Inc. headquarters at 643 Bair Island Road, Suite
  23  * 305, Redwood City, CA 94063, USA, or at email address info@funambol.com.
  24  *
  25  * The interactive user interfaces in modified source and object code versions
  26  * of this program must display Appropriate Legal Notices, as required under
  27  * Section 5 of the GNU Affero General Public License version 3.
  28  *
  29  * In accordance with Section 7(b) of the GNU Affero General Public License
  30  * version 3, these Appropriate Legal Notices must retain the display of the
  31  * "Powered by Funambol" logo. If the display of the logo is not reasonably
  32  * feasible for technical reasons, the Appropriate Legal Notices must display
  33  * the words "Powered by Funambol".
  34  */
  35
  36 #ifndef INCL_WINITEM
  37 #define INCL_WINITEM
  38
  39 /** @cond API */
  40 /** @addtogroup win_adapter */
  41 /** @{ */
  42
  43
  44 #include "base/fscapi.h"
  45 #include "base/Log.h"
  46 #include "vocl/VObject.h"
  47 #include <string>
  48 #include <list>
  49 #include <map>
  50
  51 using namespace std;
  52
  53
  54 // Versions supported:
  55 #define VCARD_VERSION                       TEXT("2.1")
  56 #define VCALENDAR_VERSION                   TEXT("1.0")
  57 #define VNOTE_VERSION                       TEXT("1.1")
  58 #define SIF_VERSION                         TEXT("1.1")
  59
  60
  61 // Error messages:
  62 #define ERR_ITEM_VOBJ_PARSE                 "VConverter: error occurred parsing the item data."
  63 #define ERR_ITEM_VOBJ_WRONG_TYPE            "Error: wrong vobject type \"%ls\" (\"%ls\" expected)"
  64 #define ERR_ITEM_VOBJ_TYPE_NOTFOUND         "Error: vobject type not specified (\"%ls\" expected)"
  65 #define ERR_SIFFIELDS_NULL                  "Parsing error: sifFields must be initialized before parsing data."
  66 #define INFO_ITEM_VOBJ_WRONG_VERSION        "Warning! Wrong vobject version \"%ls\" (\"%ls\" expected)"
  67 #define INFO_ITEM_VOBJ_VERSION_NOTFOUND     "Warning! VObject version not specified (\"%ls\" expected)"
  68 #include "base/globalsdef.h"
  69
  70 BEGIN_NAMESPACE
  71
  72
  73 typedef map<wstring,wstring>::iterator      mapIterator;
  74
  75
  76 /**
  77  ****************************************************************************
  78  * Rapresents an item object for Windows Clients.
  79  * Contains a map of <propertyName,propertyValue> for all properties
  80  * exchanged and methods to get/set them.
  81  ****************************************************************************
  82  */
  83 class WinItem {
  84
  85 private:
  86
  87     /// A dummy bad string "<NULL>", used by methods that return a reference
  88     /// to an internal property value, when the property is missing.
  89     static wstring badString;
  90
  91
  92 protected:
  93
  94     /// The table used to calculate the crc.
  95     static unsigned long crc32Table[256];
  96
  97
  98 public:
  99
 100     /**
 101      * Map <propertyName, propertyValue> of props exchanged.
 102      * - Client to Server: contains props supported by Client, MUST be filled by Client
 103      *                     calling setProperty() for each property, before calling toString().
 104      * - Server to Client: contains props parsed from vCard/vCalendar, it's automatically
 105      *                     filled by parsers of derived classes. Client SHOULD call getProperty()
 106      *                     for each property he wants to retrieve, after calling parse().
 107     */
 108     map<wstring,wstring> propertyMap;
 109
 110     /// Default Constructor
 111     WinItem();
 112
 113     /// Destructor
 114     virtual ~WinItem();
 115
 116
 117     /// Returns the size of propertyMap;
 118     int getPropertyMapSize();
 119
 120     /// Returns a reference to the internal propertyMap.
 121     map<wstring,wstring>& getPropertyMap();
 122
 123
 124     /**
 125      * Sets a property value of name 'propertyName'.
 126      * Stores the value into the propertyMap, adds a new row <name, value> if the
 127      * property is not found, otherwise existing value is overwritten.
 128      * @param  propertyName   the name of property to set
 129      * @param  propertyValue  the value of property to set
 130      */
 131     void setProperty(const wstring propertyName, const wstring propertyValue);
 132
 133     /**
 134      * Sets a integer property value of name 'propertyName'.
 135      * Like 'setProperty', but the input value is integer and it's formatted
 136      * into a string.
 137      * @param  propertyName   the name of property to set
 138      * @param  propertyValue  the integer value of property to set
 139      */
 140     void setIntProperty(const wstring propertyName, const int intValue);
 141
 142
 143     /**
 144      * Gets a property value from its name.
 145      * Retrieves the value from the propertyMap. If property is not
 146      * found, returns false.
 147      * @param  propertyName   the name of property to retrieve
 148      * @param  propertyValue  [IN-OUT] the value of property, it's set to empty string
 149      *                        if the property is not found
 150      * @return                true if property found, false if not found
 151      */
 152     bool getProperty(const wstring propertyName, wstring& propertyValue);
 153
 154     /**
 155      * Gets a property value from its name.
 156      * Retrieves the value from the propertyMap. Returns a reference to the internal
 157      * value of property inside the map (value not copied).
 158      * @note  If property not found, returns a reference to the
 159      *        'badString' static member of this class.
 160      *
 161      * @param  propertyName   the name of property to retrieve
 162      * @param  propertyValue  [IN-OUT] true if property found, false if not found
 163      * @return                the value of property found, by reference
 164      */
 165     wstring& getPropertyRef(const wstring propertyName, bool* found);
 166
 167     /**
 168      * Gets a property value from its name, and convert into a integer value.
 169      * Retrieves the value from the propertyMap. If property is not
 170      * found or not correctly converted into int, returns false.
 171      * @param  propertyName   the name of property to retrieve
 172      * @param  propertyValue  [IN-OUT] the value of property, integer value
 173      * @return                true if property found, false if not found or wrong format
 174      */
 175     bool getIntProperty(const wstring propertyName, int* intValue);
 176
 177
 178     void removeElement(wstring key);
 179
 180     /// Reset the propertyMap (clear all rows).
 181     void resetPropertyMap();
 182
 183     /// Reset all fields values of the propertyMap (only values).
 184     void resetAllValues();
 185
 186
 187     /**
 188      * Format and return a string from the propertyMap.
 189      * Not supported properties are ignored and so not formatted
 190      * as they don't have a correspondence in propertyMap.
 191      * @return  the string formatted, reference to internal wstring
 192      */
 193     virtual wstring& toString() = 0;
 194
 195     /**
 196      * Parse a string and fills the propertyMap.
 197      * The map is cleared and will contain only found properties
 198      * at the end of the parsing.
 199      * @param dataString  input vCard string to be parsed
 200      * @return            0 if no errors
 201      */
 202     virtual int parse(const wstring dataString) = 0;
 203
 204
 205     /**
 206     * Return the crc value of the internal map with all values.
 207     * It uses only the values of the map not the key.
 208     * Can be overrided by derived classes if other properties are involved
 209     * (e.g. Events have recucurrence props and exceptions)
 210     */
 211     virtual long getCRC();
 212
 213     /**
 214      * Utility to safe-retrieve the property value inside VObject 'vo'.
 215      * @param vo           : VObject to read from
 216      * @param propertyName : the property name requested
 217      * @return               the property value (NULL if not found)
 218      */
 219     WCHAR* getVObjectPropertyValue(VObject* vo, const WCHAR* propertyName);
 220
 221
 222     /**
 223      * Util function that returns the name of the item, usually the "Subject" property.
 224      * It should be implemented by derived classes to return a desired value.
 225      * If property doesn't exist, returns "<NULL>"
 226      */
 227     virtual wstring& getName();
 228 };
 229
 230
 231 END_NAMESPACE
 232
 233 /** @} */
 234 /** @endcond */
 235 #endif