1 vcard.h

     1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15  

    16 #ifndef __VCARD_H__

    17 #define __VCARD_H__

    18 

    19 #ifndef __VERSIT_H__

    20 #include <versit.h>

    21 #endif

    22 

    23 #include <vobserv.h>

    24 

    25 _LIT(KVersitTokenVCardVersionNo, "2.1");

    26 

    27 class CVCard3ParserPlugIn;

    28 

    29 //

    30 // CParserVCard

    31 //

    32 class CParserVCard : public CVersitParser

    33 /** A vCard parser. 

    34 

    35 Adds support for property groups (see CParserGroupedProperty) and agents 

    36 (see CParserPropertyValueAgent) to the functionality of CVersitParser. 

    37 

    38 Provides a constructor and overrides CVersitParser::InternalizeL(),   

    39 ExternalizeL(), RecognizeToken(), ConvertAllPropertyDateTimesToMachineLocalL(), 

    40 ParsePropertyL() and MakePropertyValueL().

    41 

    42 The vCard data is read from or written to a stream or file, using the InternalizeL() 

    43 and ExternalizeL() functions. Most users of this class will only need to use 

    44 these functions.

    45 

    46 If you are sequentially creating and destroying multiple parsers, a major performance 

    47 improvement may be achieved by using thread local storage to store an instance of 

    48 CVersitUnicodeUtils which persists and can be used by all of the parsers.

    49 

    50 See CVersitTlsData for more information. 

    51 @publishedAll

    52 @released

    53 */

    54 	{

    55 public:

    56 	IMPORT_C static CParserVCard* NewL();

    57 	IMPORT_C CArrayPtr<CParserProperty>* GroupOfPropertiesL(const TDesC8& aName) const;

    58 public: //from CVersitParser

    59 	IMPORT_C void InternalizeL(RReadStream& aStream);

    60 	IMPORT_C void ExternalizeL(RWriteStream& aStream);

    61 	IMPORT_C void ConvertAllPropertyDateTimesToMachineLocalL(const TTimeIntervalSeconds& aIncrement,const CVersitDaylight* aDaylight);

    62 protected:

    63 	IMPORT_C virtual CParserPropertyValue* MakePropertyValueAgentL(TPtr16 aValue);

    64 	IMPORT_C CDesC8Array* GetGroupNamesL(TPtr8& aGroupsAndName);

    65 protected: // from CVersitParser

    66 	IMPORT_C void ParsePropertyL();

    67 	IMPORT_C CParserPropertyValue* MakePropertyValueL(const TUid& aPropertyUid,HBufC16*& aValue);

    68     IMPORT_C CParserPropertyValue* MakePropertyValueSoundL(HBufC16*& aValue);

    69 public: //from CVersitParser

    70 	IMPORT_C TUid RecognizeToken(const TDesC8& aToken) const;

    71 	IMPORT_C void ConvertDateTimesToMachineLocalAndDeleteTZL();

    72 protected:

    73 	CParserVCard();

    74 private: // from CVersitParser

    75 	IMPORT_C virtual void Reserved1();

    76 	IMPORT_C virtual void Reserved2();

    77 	};

    78 

    79 NONSHARABLE_CLASS(CParserVCard3) : public CParserVCard

    80 /** A vCard 3.0 parser. 

    81 

    82 Overrides CParserVCard::InternalizeL(). Internalizing of vCard 3.0

    83 objects is not supported

    84 

    85 @internalTechnology

    86 @prototype

    87 */

    88 	{

    89 public:

    90 	IMPORT_C static CParserVCard3* NewL();

    91 	~CParserVCard3();

    92 	

    93 public: //from CParserVCard

    94 	IMPORT_C void InternalizeL(RReadStream& aStream);

    95 	

    96 private:

    97 	CParserVCard3();

    98 	void ConstructL();

    99 	void CreateParserPlugInL();

   100 

   101 private:

   102 	CVCard3ParserPlugIn* iPlugInImpl;

   103 	};

   104 	

   105 //

   106 // CParserGroupedProperty

   107 //

   108 class CParserGroupedProperty : public CParserProperty

   109 /** A grouped property.

   110 

   111 This is a vCard property which may be a member of one or more property groups. 

   112 It owns an array of descriptors, each of which identifies a group 

   113 to which the property belongs.

   114 

   115 An example of how grouped properties may be useful is for a person with two 

   116 homes. Each home has an address and telephone number, both of which are to 

   117 be stored on the vCard. The address and telephone number are grouped for each 

   118 home. A prefix for the address and telephone number properties is provided: 

   119 one for each home. Each prefix is stored as a property group.

   120 

   121 When the property is externalised, the identities of all the groups to which 

   122 the property belongs (i.e. the prefixes) are written to the stream before 

   123 CParserProperty::ExternalizeL() is called.

   124 

   125 The class also provides a function which can be used to test whether 

   126 the property is a member of a given group.

   127 

   128 Note that the vCard parser stores all properties using this class; if the 

   129 vCard property is not grouped then the array of property groups is empty. 

   130 Conversely, the vCalender parser does not have property groups, and so stores 

   131 all properties using the CParserProperty base class. 

   132 @publishedAll

   133 @released

   134 */

   135 	{

   136 public:

   137 	IMPORT_C static CParserGroupedProperty* NewL(CParserPropertyValue& aPropertyValue, const TDesC8& aName, CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);

   138 	IMPORT_C CParserGroupedProperty(CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);

   139 	IMPORT_C ~CParserGroupedProperty();

   140 	IMPORT_C TBool Group(const TDesC8& aGroup) const;

   141 	inline void SetGroups(CDesC8Array* aArrayOfGroups);

   142 	inline const CDesC8Array* Groups();

   143 public: //from CParserProperty

   144 	IMPORT_C TBool SupportsInterface(const TUid& aInterfaceUid) const;

   145 	IMPORT_C void ExternalizeL(RWriteStream& aStream, CVersitParser* aVersitParser = NULL);

   146 protected:

   147 	CParserGroupedProperty(CParserPropertyValue& aPropertyValue, CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);

   148 private: //from CParserProperty

   149 	IMPORT_C virtual void Reserved();

   150 protected:

   151 	CDesC8Array* iArrayOfGroups;

   152 	};

   153 

   154 //

   155 // CParserPropertyValueAgent

   156 //

   157 class CParserPropertyValueAgent : public CParserPropertyValue

   158 /** An agent property value parser. 

   159 

   160 An agent property value contains information about a person who is not the 

   161 main subject of the vCard. It is implemented as a vCard nested within another 

   162 vCard. The agent's vCard is held in the property value of the parent vCard.

   163 

   164 The UID for an agent property value is KVCardPropertyAgentUid. 

   165 @publishedAll

   166 @released

   167 */

   168 	{

   169 public:

   170 	IMPORT_C CParserPropertyValueAgent(CParserVCard* aValue);

   171 	IMPORT_C ~CParserPropertyValueAgent();

   172 	inline CParserVCard* Value() const;

   173 

   174 public: // from CParserPropertyValue

   175 	IMPORT_C void ExternalizeL(RWriteStream& aStream,const Versit::TEncodingAndCharset& /*aEncodingCharset*/,TInt /*aLengthOutput*/);

   176 protected:

   177 	CParserVCard* iValue;

   178 private:

   179 	};

   180 

   181 #include <vcard.inl>

   182 

   183 #endif