src/include/common/vocl/VObject.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 
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

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