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 "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     virtual ~VObject();
00119     void setVersion (const WCHAR* ver);
00120     void setProdID (const WCHAR* prodID);
00121     WCHAR* getVersion();
00122     WCHAR* getProdID();
00124     void addProperty(VProperty* property);
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 
00187 #endif
00188 
00189 };
00190 
00191 
00192 
00193 END_NAMESPACE
00194 
00196 #endif

Generated on Wed Jan 14 17:15:37 2009 for Funambol C++ Client Library by  doxygen 1.5.2