epoc32/include/app/vcard.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:27:01 +0100
branchSymbian2
changeset 3 e1b950c65cb4
parent 2 epoc32/include/vcard.h@2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
Attempt to represent the S^2->S^3 header reorganisation as a series of "hg rename" operations
williamr@2
     1
// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     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
williamr@2
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
//
williamr@2
    15
 
williamr@2
    16
#ifndef __VCARD_H__
williamr@2
    17
#define __VCARD_H__
williamr@2
    18
williamr@2
    19
#ifndef __VERSIT_H__
williamr@2
    20
#include <versit.h>
williamr@2
    21
#endif
williamr@2
    22
williamr@2
    23
#include <vobserv.h>
williamr@2
    24
williamr@2
    25
_LIT(KVersitTokenVCardVersionNo, "2.1");
williamr@2
    26
williamr@2
    27
class CVCard3ParserPlugIn;
williamr@2
    28
williamr@2
    29
//
williamr@2
    30
// CParserVCard
williamr@2
    31
//
williamr@2
    32
class CParserVCard : public CVersitParser
williamr@2
    33
/** A vCard parser. 
williamr@2
    34
williamr@2
    35
Adds support for property groups (see CParserGroupedProperty) and agents 
williamr@2
    36
(see CParserPropertyValueAgent) to the functionality of CVersitParser. 
williamr@2
    37
williamr@2
    38
Provides a constructor and overrides CVersitParser::InternalizeL(),   
williamr@2
    39
ExternalizeL(), RecognizeToken(), ConvertAllPropertyDateTimesToMachineLocalL(), 
williamr@2
    40
ParsePropertyL() and MakePropertyValueL().
williamr@2
    41
williamr@2
    42
The vCard data is read from or written to a stream or file, using the InternalizeL() 
williamr@2
    43
and ExternalizeL() functions. Most users of this class will only need to use 
williamr@2
    44
these functions.
williamr@2
    45
williamr@2
    46
If you are sequentially creating and destroying multiple parsers, a major performance 
williamr@2
    47
improvement may be achieved by using thread local storage to store an instance of 
williamr@2
    48
CVersitUnicodeUtils which persists and can be used by all of the parsers.
williamr@2
    49
williamr@2
    50
See CVersitTlsData for more information. 
williamr@2
    51
@publishedAll
williamr@2
    52
@released
williamr@2
    53
*/
williamr@2
    54
	{
williamr@2
    55
public:
williamr@2
    56
	IMPORT_C static CParserVCard* NewL();
williamr@2
    57
	IMPORT_C CArrayPtr<CParserProperty>* GroupOfPropertiesL(const TDesC8& aName) const;
williamr@2
    58
public: //from CVersitParser
williamr@2
    59
	IMPORT_C void InternalizeL(RReadStream& aStream);
williamr@2
    60
	IMPORT_C void ExternalizeL(RWriteStream& aStream);
williamr@2
    61
	IMPORT_C void ConvertAllPropertyDateTimesToMachineLocalL(const TTimeIntervalSeconds& aIncrement,const CVersitDaylight* aDaylight);
williamr@2
    62
protected:
williamr@2
    63
	IMPORT_C virtual CParserPropertyValue* MakePropertyValueAgentL(TPtr16 aValue);
williamr@2
    64
	IMPORT_C CDesC8Array* GetGroupNamesL(TPtr8& aGroupsAndName);
williamr@2
    65
protected: // from CVersitParser
williamr@2
    66
	IMPORT_C void ParsePropertyL();
williamr@2
    67
	IMPORT_C CParserPropertyValue* MakePropertyValueL(const TUid& aPropertyUid,HBufC16*& aValue);
williamr@2
    68
    IMPORT_C CParserPropertyValue* MakePropertyValueSoundL(HBufC16*& aValue);
williamr@2
    69
public: //from CVersitParser
williamr@2
    70
	IMPORT_C TUid RecognizeToken(const TDesC8& aToken) const;
williamr@2
    71
	IMPORT_C void ConvertDateTimesToMachineLocalAndDeleteTZL();
williamr@2
    72
protected:
williamr@2
    73
	CParserVCard();
williamr@2
    74
private: // from CVersitParser
williamr@2
    75
	IMPORT_C virtual void Reserved1();
williamr@2
    76
	IMPORT_C virtual void Reserved2();
williamr@2
    77
	};
williamr@2
    78
williamr@2
    79
NONSHARABLE_CLASS(CParserVCard3) : public CParserVCard
williamr@2
    80
/** A vCard 3.0 parser. 
williamr@2
    81
williamr@2
    82
Overrides CParserVCard::InternalizeL(). Internalizing of vCard 3.0
williamr@2
    83
objects is not supported
williamr@2
    84
williamr@2
    85
@internalTechnology
williamr@2
    86
@prototype
williamr@2
    87
*/
williamr@2
    88
	{
williamr@2
    89
public:
williamr@2
    90
	IMPORT_C static CParserVCard3* NewL();
williamr@2
    91
	~CParserVCard3();
williamr@2
    92
	
williamr@2
    93
public: //from CParserVCard
williamr@2
    94
	IMPORT_C void InternalizeL(RReadStream& aStream);
williamr@2
    95
	
williamr@2
    96
private:
williamr@2
    97
	CParserVCard3();
williamr@2
    98
	void ConstructL();
williamr@2
    99
	void CreateParserPlugInL();
williamr@2
   100
williamr@2
   101
private:
williamr@2
   102
	CVCard3ParserPlugIn* iPlugInImpl;
williamr@2
   103
	};
williamr@2
   104
	
williamr@2
   105
//
williamr@2
   106
// CParserGroupedProperty
williamr@2
   107
//
williamr@2
   108
class CParserGroupedProperty : public CParserProperty
williamr@2
   109
/** A grouped property.
williamr@2
   110
williamr@2
   111
This is a vCard property which may be a member of one or more property groups. 
williamr@2
   112
It owns an array of descriptors, each of which identifies a group 
williamr@2
   113
to which the property belongs.
williamr@2
   114
williamr@2
   115
An example of how grouped properties may be useful is for a person with two 
williamr@2
   116
homes. Each home has an address and telephone number, both of which are to 
williamr@2
   117
be stored on the vCard. The address and telephone number are grouped for each 
williamr@2
   118
home. A prefix for the address and telephone number properties is provided: 
williamr@2
   119
one for each home. Each prefix is stored as a property group.
williamr@2
   120
williamr@2
   121
When the property is externalised, the identities of all the groups to which 
williamr@2
   122
the property belongs (i.e. the prefixes) are written to the stream before 
williamr@2
   123
CParserProperty::ExternalizeL() is called.
williamr@2
   124
williamr@2
   125
The class also provides a function which can be used to test whether 
williamr@2
   126
the property is a member of a given group.
williamr@2
   127
williamr@2
   128
Note that the vCard parser stores all properties using this class; if the 
williamr@2
   129
vCard property is not grouped then the array of property groups is empty. 
williamr@2
   130
Conversely, the vCalender parser does not have property groups, and so stores 
williamr@2
   131
all properties using the CParserProperty base class. 
williamr@2
   132
@publishedAll
williamr@2
   133
@released
williamr@2
   134
*/
williamr@2
   135
	{
williamr@2
   136
public:
williamr@2
   137
	IMPORT_C static CParserGroupedProperty* NewL(CParserPropertyValue& aPropertyValue, const TDesC8& aName, CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);
williamr@2
   138
	IMPORT_C CParserGroupedProperty(CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);
williamr@2
   139
	IMPORT_C ~CParserGroupedProperty();
williamr@2
   140
	IMPORT_C TBool Group(const TDesC8& aGroup) const;
williamr@2
   141
	inline void SetGroups(CDesC8Array* aArrayOfGroups);
williamr@2
   142
	inline const CDesC8Array* Groups();
williamr@2
   143
public: //from CParserProperty
williamr@2
   144
	IMPORT_C TBool SupportsInterface(const TUid& aInterfaceUid) const;
williamr@2
   145
	IMPORT_C void ExternalizeL(RWriteStream& aStream, CVersitParser* aVersitParser = NULL);
williamr@2
   146
protected:
williamr@2
   147
	CParserGroupedProperty(CParserPropertyValue& aPropertyValue, CDesC8Array* aArrayOfGroups, CArrayPtr<CParserParam>* aArrayOfParams);
williamr@2
   148
private: //from CParserProperty
williamr@2
   149
	IMPORT_C virtual void Reserved();
williamr@2
   150
protected:
williamr@2
   151
	CDesC8Array* iArrayOfGroups;
williamr@2
   152
	};
williamr@2
   153
williamr@2
   154
//
williamr@2
   155
// CParserPropertyValueAgent
williamr@2
   156
//
williamr@2
   157
class CParserPropertyValueAgent : public CParserPropertyValue
williamr@2
   158
/** An agent property value parser. 
williamr@2
   159
williamr@2
   160
An agent property value contains information about a person who is not the 
williamr@2
   161
main subject of the vCard. It is implemented as a vCard nested within another 
williamr@2
   162
vCard. The agent's vCard is held in the property value of the parent vCard.
williamr@2
   163
williamr@2
   164
The UID for an agent property value is KVCardPropertyAgentUid. 
williamr@2
   165
@publishedAll
williamr@2
   166
@released
williamr@2
   167
*/
williamr@2
   168
	{
williamr@2
   169
public:
williamr@2
   170
	IMPORT_C CParserPropertyValueAgent(CParserVCard* aValue);
williamr@2
   171
	IMPORT_C ~CParserPropertyValueAgent();
williamr@2
   172
	inline CParserVCard* Value() const;
williamr@2
   173
williamr@2
   174
public: // from CParserPropertyValue
williamr@2
   175
	IMPORT_C void ExternalizeL(RWriteStream& aStream,const Versit::TEncodingAndCharset& /*aEncodingCharset*/,TInt /*aLengthOutput*/);
williamr@2
   176
protected:
williamr@2
   177
	CParserVCard* iValue;
williamr@2
   178
private:
williamr@2
   179
	};
williamr@2
   180
williamr@2
   181
#include <vcard.inl>
williamr@2
   182
williamr@2
   183
#endif