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 00037 #ifndef INCL_VIRTUAL_OBJECT 00038 #define INCL_VIRTUAL_OBJECT 00039 /** @cond DEV */ 00040 00041 #include "vocl/VProperty.h" 00042 #include "base/globalsdef.h" 00043 00044 BEGIN_NAMESPACE 00045 00046 00047 00048 /* 00049 * ************************************* Class VObject ********************************************* 00050 * ************************************************************************************************* 00051 * A VObject object rapresents an item that can be a vCard, a vCalendar or vTodo. 00052 * A VObject contains an array of VProperty, each one rapresents a property. 00053 * A property is the definition of an individual attribute describing the vCard/vCal/vTodo. 00054 * Each property has a name, an array of parameters and an array of values, 00055 * for example, the property: 00056 * 00057 * TEL;HOME:+1-919-555-1234 00058 * 00059 * has name 'TEL', one parameter 'HOME' and one value '+1-919-555-1234' 00060 * 00061 * Some properties have more than one parameter, each parameter is a pair: (name, value). 00062 * Use VProperty::add/getParameter() methods to access them. 00063 * 00064 * Some properties have more than one value, each value is a string of text. 00065 * Values MUST be inserted in the right order (as vCard specific). 00066 * Use VProperty::add/getValue() methods to access them. 00067 * Note: 00068 * If one of these value is not present, it must be inserted however as 00069 * an empty string, to make sure the right order is respected. 00070 * 00071 * 00072 * Properties with more than one value are: 00073 * 00074 * Property name 1^value 2^value 3^value 4^value 5^value 6^value 7^value 00075 * ---------------------------------------------------------------------------------------------------------------------------------- 00076 * Name -> N: <LastName> <FirstName> <MiddleName> <Title> <Suffix> 00077 * Address -> ADR: <Post Office> <Extended Addr> <Street> <City> <State> <PostalCode> <Country> 00078 * Audio Alarm -> AALARM: <RunTime> <Snooze Time> <Repeat Count> <Audio Content> 00079 * 00080 * 00081 * Property values should be added as simple text, Quoted-Printable and BASE64 encodings are 00082 * automatically managed inside VObject. Also the escaping of special chars is 00083 * automatically managed inside VObject. 00084 * Escaped chars for v.2.1: ";" "\" 00085 * Escaped chars for v.3.0: ";" "\" "," 00086 * Use VObject::toString() method to obtain the correspondent vCard/vCal/vTodo. 00087 * 00088 * 00089 * To set Quoted-Printable / Base64 encoding for a property: 00090 * ========================================================= 00091 * QP and B64 encodings are automatically managed inside VObject. This means that 00092 * data conversion is performed inside VObject, to force data encoding 00093 * just add the encoding parameter to the VProperty, calling: 00094 * 00095 * for QP: VProperty->addParameter(TEXT("ENCODING"), TEXT("QUOTED-PRINTABLE")) 00096 * for B64: VProperty->addParameter(TEXT("ENCODING"), TEXT("b")) 00097 * 00098 * Note that QP encoding is used only for vCard v.2.1 (not allowed in v.3.0). 00099 * If a property contains characters that cannot be managed with the default 00100 * 7bit encoding, it is encoded automatically with QP (v.2.1) or B64 (v.3.0). 00101 * 00102 */ 00103 00104 00105 class VObject { 00106 00107 private: 00108 00109 WCHAR* version; 00110 WCHAR* productID; 00111 ArrayList* properties; 00112 void set(WCHAR**, const WCHAR*); 00113 00114 public: 00115 00116 VObject(); 00117 VObject(const WCHAR* prodID, const WCHAR* ver); 00118 ~VObject(); 00119 void setVersion (const WCHAR* ver); 00120 void setProdID (const WCHAR* prodID); 00121 WCHAR* getVersion(); 00122 WCHAR* getProdID(); 00123 /** Add a new property to the VObject */ 00124 void addProperty(VProperty* property); 00125 /** Add a new property to the VObject, using key and value for it. */ 00126 void addProperty(const WCHAR* key, const WCHAR* value) { 00127 VProperty vprop(key, value); addProperty(&vprop); 00128 } 00129 void addFirstProperty(VProperty* property); 00130 void insertProperty(VProperty* property); 00131 bool removeProperty(int index); 00132 void removeProperty(WCHAR* propName); 00133 void removeAllProperies(WCHAR* propName); 00134 //removes all properties having name - propName; 00135 bool containsProperty(const WCHAR* propName); 00136 int propertiesCount(); 00137 VProperty* getProperty(int index); 00138 VProperty* getProperty(const WCHAR* propName); 00139 WCHAR* toString(); 00140 00141 #ifdef VOCL_ENCODING_FIX 00142 00143 // Patrick Ohly: 00144 // 00145 // Normally the class does not change the encoding 00146 // of properties. That means that users of this class 00147 // have to be prepared to handle e.g. quoted-printable 00148 // encoding of non-ASCII characters or \n as line break 00149 // in vCard 3.0. 00150 // 00151 // This function decodes all property strings into the 00152 // native format. It supports: 00153 // - decoding quoted-printable characters if 00154 // ENCODING=QUOTED-PRINTABLE 00155 // - replacement of \n with a line break and \, with 00156 // single comma if version is 3.0 00157 // 00158 // It does not support charset conversions, so everything 00159 // has to be UTF-8 to work correctly. 00160 // 00161 // This function does not modify the property parameters, 00162 // so one could convert back into the original format. 00163 // 00164 // Consider this function a hack: at this time it is not 00165 // clear how the class is supposed to handle different 00166 // encodings, but I needed a solution, so here it is. 00167 // 00168 void toNativeEncoding(); 00169 00170 // 00171 // Converts properties in native format according to 00172 // their parameters. 00173 // 00174 // It only supports: 00175 // - replacement of line breaks and commas (if 3.0) 00176 // 00177 // It does not support any charsets or encoding. 00178 // ENCODING=QUOTED-PRINTABLE will be removed because 00179 // it no longer applies when toNativeEncoding() was 00180 // used before, but the other parameters are preserved: 00181 // this might be good enough to recreate the original 00182 // object. 00183 // 00184 void fromNativeEncoding(); 00185 00186 /** @endcond */ 00187 #endif 00188 00189 }; 00190 00191 00192 00193 END_NAMESPACE 00194 00195 /** @endcond */ 00196 #endif