williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2:  
williamr@2: #ifndef __VCARD_H__
williamr@2: #define __VCARD_H__
williamr@2: 
williamr@2: #ifndef __VERSIT_H__
williamr@2: #include <versit.h>
williamr@2: #endif
williamr@2: 
williamr@2: #include <vobserv.h>
williamr@2: 
williamr@4: 
williamr@4: /** This constant is for internal use only.
williamr@4: @internalTechnology
williamr@4: */
williamr@2: _LIT(KVersitTokenVCardVersionNo, "2.1");
williamr@2: 
williamr@4: 
williamr@2: class CVCard3ParserPlugIn;
williamr@2: 
williamr@2: //
williamr@2: // CParserVCard
williamr@2: //
williamr@2: class CParserVCard : public CVersitParser
williamr@2: /** A vCard parser. 
williamr@2: 
williamr@2: Adds support for property groups (see CParserGroupedProperty) and agents 
williamr@2: (see CParserPropertyValueAgent) to the functionality of CVersitParser. 
williamr@2: 
williamr@2: Provides a constructor and overrides CVersitParser::InternalizeL(),   
williamr@2: ExternalizeL(), RecognizeToken(), ConvertAllPropertyDateTimesToMachineLocalL(), 
williamr@2: ParsePropertyL() and MakePropertyValueL().
williamr@2: 
williamr@2: The vCard data is read from or written to a stream or file, using the InternalizeL() 
williamr@2: and ExternalizeL() functions. Most users of this class will only need to use 
williamr@2: these functions.
williamr@2: 
williamr@2: If you are sequentially creating and destroying multiple parsers, a major performance 
williamr@2: improvement may be achieved by using thread local storage to store an instance of 
williamr@2: CVersitUnicodeUtils which persists and can be used by all of the parsers.
williamr@2: 
williamr@2: See CVersitTlsData for more information. 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C static CParserVCard* NewL();
williamr@4: 	static CParserVCard* NewL(TBool aParsingAgent);
williamr@2: 	IMPORT_C CArrayPtr<CParserProperty>* GroupOfPropertiesL(const TDesC8& aName) const;
williamr@2: public: //from CVersitParser
williamr@2: 	IMPORT_C void InternalizeL(RReadStream& aStream);
williamr@2: 	IMPORT_C void ExternalizeL(RWriteStream& aStream);
williamr@2: 	IMPORT_C void ConvertAllPropertyDateTimesToMachineLocalL(const TTimeIntervalSeconds& aIncrement,const CVersitDaylight* aDaylight);
williamr@2: protected:
williamr@2: 	IMPORT_C virtual CParserPropertyValue* MakePropertyValueAgentL(TPtr16 aValue);
williamr@2: 	IMPORT_C CDesC8Array* GetGroupNamesL(TPtr8& aGroupsAndName);
williamr@2: protected: // from CVersitParser
williamr@2: 	IMPORT_C void ParsePropertyL();
williamr@2: 	IMPORT_C CParserPropertyValue* MakePropertyValueL(const TUid& aPropertyUid,HBufC16*& aValue);
williamr@2:     IMPORT_C CParserPropertyValue* MakePropertyValueSoundL(HBufC16*& aValue);
williamr@2: public: //from CVersitParser
williamr@2: 	IMPORT_C TUid RecognizeToken(const TDesC8& aToken) const;
williamr@2: 	IMPORT_C void ConvertDateTimesToMachineLocalAndDeleteTZL();
williamr@2: protected:
williamr@2: 	CParserVCard();
williamr@4: 	CParserVCard(TBool aParsingAgent);
williamr@2: private: // from CVersitParser
williamr@2: 	IMPORT_C virtual void Reserved1();
williamr@2: 	IMPORT_C virtual void Reserved2();
williamr@4: 	TBool iParsingAgent;
williamr@2: 	};
williamr@2: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@2: NONSHARABLE_CLASS(CParserVCard3) : public CParserVCard
williamr@2: /** A vCard 3.0 parser. 
williamr@2: 
williamr@2: Overrides CParserVCard::InternalizeL(). Internalizing of vCard 3.0
williamr@2: objects is not supported
williamr@2: 
williamr@2: @internalTechnology
williamr@4: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C static CParserVCard3* NewL();
williamr@2: 	~CParserVCard3();
williamr@2: 	
williamr@2: public: //from CParserVCard
williamr@2: 	IMPORT_C void InternalizeL(RReadStream& aStream);
williamr@2: 	
williamr@2: private:
williamr@2: 	CParserVCard3();
williamr@2: 	void ConstructL();
williamr@2: 	void CreateParserPlugInL();
williamr@2: 
williamr@2: private:
williamr@2: 	CVCard3ParserPlugIn* iPlugInImpl;
williamr@2: 	};
williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS	
williamr@2: //
williamr@2: // CParserGroupedProperty
williamr@2: //
williamr@2: class CParserGroupedProperty : public CParserProperty
williamr@2: /** A grouped property.
williamr@2: 
williamr@2: This is a vCard property which may be a member of one or more property groups. 
williamr@2: It owns an array of descriptors, each of which identifies a group 
williamr@2: to which the property belongs.
williamr@2: 
williamr@2: An example of how grouped properties may be useful is for a person with two 
williamr@2: homes. Each home has an address and telephone number, both of which are to 
williamr@2: be stored on the vCard. The address and telephone number are grouped for each 
williamr@2: home. A prefix for the address and telephone number properties is provided: 
williamr@2: one for each home. Each prefix is stored as a property group.
williamr@2: 
williamr@2: When the property is externalised, the identities of all the groups to which 
williamr@2: the property belongs (i.e. the prefixes) are written to the stream before 
williamr@2: CParserProperty::ExternalizeL() is called.
williamr@2: 
williamr@2: The class also provides a function which can be used to test whether 
williamr@2: the property is a member of a given group.
williamr@2: 
williamr@2: Note that the vCard parser stores all properties using this class; if the 
williamr@2: vCard property is not grouped then the array of property groups is empty. 
williamr@2: Conversely, the vCalender parser does not have property groups, and so stores 
williamr@2: all properties using the CParserProperty base class. 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C static CParserGroupedProperty* NewL(CParserPropertyValue& aPropertyValue, const TDesC8& aName, CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);
williamr@2: 	IMPORT_C CParserGroupedProperty(CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);
williamr@2: 	IMPORT_C ~CParserGroupedProperty();
williamr@2: 	IMPORT_C TBool Group(const TDesC8& aGroup) const;
williamr@2: 	inline void SetGroups(CDesC8Array* aArrayOfGroups);
williamr@2: 	inline const CDesC8Array* Groups();
williamr@2: public: //from CParserProperty
williamr@2: 	IMPORT_C TBool SupportsInterface(const TUid& aInterfaceUid) const;
williamr@2: 	IMPORT_C void ExternalizeL(RWriteStream& aStream, CVersitParser* aVersitParser = NULL);
williamr@2: protected:
williamr@2: 	CParserGroupedProperty(CParserPropertyValue& aPropertyValue, CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);
williamr@2: private: //from CParserProperty
williamr@2: 	IMPORT_C virtual void Reserved();
williamr@2: protected:
williamr@2: 	CDesC8Array* iArrayOfGroups;
williamr@2: 	};
williamr@2: 
williamr@2: //
williamr@2: // CParserPropertyValueAgent
williamr@2: //
williamr@2: class CParserPropertyValueAgent : public CParserPropertyValue
williamr@2: /** An agent property value parser. 
williamr@2: 
williamr@2: An agent property value contains information about a person who is not the 
williamr@2: main subject of the vCard. It is implemented as a vCard nested within another 
williamr@2: vCard. The agent's vCard is held in the property value of the parent vCard.
williamr@2: 
williamr@4: We do not support nested agents when parsing an agent's vcard.
williamr@4: 
williamr@2: The UID for an agent property value is KVCardPropertyAgentUid. 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C CParserPropertyValueAgent(CParserVCard* aValue);
williamr@2: 	IMPORT_C ~CParserPropertyValueAgent();
williamr@2: 	inline CParserVCard* Value() const;
williamr@2: 
williamr@2: public: // from CParserPropertyValue
williamr@2: 	IMPORT_C void ExternalizeL(RWriteStream& aStream,const Versit::TEncodingAndCharset& /*aEncodingCharset*/,TInt /*aLengthOutput*/);
williamr@2: protected:
williamr@2: 	CParserVCard* iValue;
williamr@2: private:
williamr@2: 	};
williamr@2: 
williamr@2: #include <vcard.inl>
williamr@2: 
williamr@2: #endif