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