// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
//
#ifndef __VERSIT_H__
#define __VERSIT_H__
// System includes
#include <e32base.h>
#include <badesca.h>
#include <s32file.h>
// User includes
#include <vuid.h>
#include <vtoken.h>
#include <vprop.h>
#include <versittls.h>
// Classes referenced
class RFile;
class TVersitDateTime;
class MVersitObserver;
class MVersitPlugIn;
#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
// Panic enumeration
/** Versit panic numbers. The Versit panic numbers have a category of "Versit-Parser".
@internalComponent
@released
*/
enum TVersitParserPanic
{
ECurrentTokenNotFound, //Unused
EUnicodeUtilsNotFound, //Unused
ENoPropertyValue, //Unused
/** A CWeekDayArray contains an invalid value (not between EMonday
and ESunday inclusive). */
ENoWeekdayFound,
/** The number of a week within a month is invalid. */
EWeekNoOverTen,
/** The repeat type for a recurrence rule property value is not one of the values
specified in CVersitRecurrence::TType. */
ENoRecognizedRepeatType,
EVersitPanicEscapedTextAlreadyExists, //Unused
/** 8-bit encoding is proposed as the default for a parser but may not be appropriate. */
EVersitPanicCannotSetEightBitEncoding,
/** 8-bit encoding is encountered or proposed where it is not expected. */
EVersitPanicUnexpectedEightBitEncoding,
/** A parser was not specified when externalising a property. */
EVersitPanicNeedToSpecifyParser,
/** The additional storage slot for the given property has already been used */
EVersitPanicAdditionalStorageSlotAlreadyInUse,
/** Attempting to assign a NULL value to an additional storage slot */
EVersitPanicNullValueAssignedToAdditionalStorageSlot,
//
EVersitPanicLast
};
/**
Used as key into additional storage within tls object, for CVersitTLSContainer
Value should not conflict with genuine compiler generated pointer values
@internalComponent
@released
*/
const static TInt* const KTLSVars = reinterpret_cast<TInt*>(1);
/**
@internalComponent
@released
*/
GLREF_C void DestroyHBufC(TAny* aHBufC);
/** Versit parser panic
@internalComponent
@released
*/
IMPORT_C void Panic(TVersitParserPanic aPanic);
#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
/** Extension mechanism for CLineReader
This is an internal class and is only for use by CLineReader
@internalComponent
@released
*/
NONSHARABLE_CLASS(CLineReaderExtension) : public CBase
{
friend class CLineReader;
private:
CLineReaderExtension();
~CLineReaderExtension();
static CLineReaderExtension* NewL();
void DeleteBase64ValueBuffer();
HBufC8* CreateBase64ValueBufferL();
HBufC8* Base64ValueBuffer();
private:
TUint8 iBuf[1024];
TInt iOffset;
TInt iSize;
// Hold the line buffer temporarily.
// It is only used when the client wants
// the base64 extended behaviour defined
// in MVersitPlugInExtensionBase64Ending
HBufC8* iLineBase64Value;
};
#else
//Forward declare class
class CLineReaderExtension;
#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
class CLineReader : public CBase
/** Line reader for a vCalendar or vCard parser.
Reads in a line at a time for the parser.
Also allows the first character of the next line to be checked to see if it
is a space, which can indicate that the line is wrapped. This enables the
reading of multi-line property values.
Used by CVersitParser to internalise streams.
@publishedAll
@released
*/
{
public:
/** Defines the initial line size of, and the size of expansions to, the buffer
which stores the line being read. */
enum
{
/** The initial size of the buffer (pointed to by iBuf). */
EInitialLineSize=96,
/** The size by which the buffer (pointed to by iBuf)
is expanded when it has run out of room. */
EExpandSize=16,
};
/** Defines values which describe the content of a line that has been read.
This is the return value from the function ReadLine(). */
enum
{
/** The line has content (not white space). */
ELineHasContent=0,
/** The line has white space only. */
ELineIsWhiteSpace=1, //Doesn't include next case
/** The line has no content, and so is just a carriage return and line
feed ("/r/n"). */
ELineIsCRLFOnly=2,
/** The line has a colon
This is only used internally. When the line has a colon, ReadLineL will
return ELineHasContent for the sake of backwards compatibility.
*/
ELineHasColon
};
public:
IMPORT_C static CLineReader* NewL(RReadStream& aStream);
IMPORT_C ~CLineReader();
IMPORT_C virtual TInt ReadLineL(TInt aPos,TInt& aErr);
IMPORT_C TBool AppendLineIfSpaceNextL();
IMPORT_C TBool IsSpaceNextL();
IMPORT_C TInt AppendSpaceL();
inline void SetPlugIn(MVersitPlugIn* aPlugIn);
inline void SetSkipWhiteSpaceAtStart(TBool aDoSkip);
public:
void ReadBase64ValueL(TInt aPopValueStart);
protected:
inline CLineReader(RReadStream& aStream) :iReadStream(&aStream), iBufPtr(NULL,0), iFirstCharNextLine(-1) {}
IMPORT_C void ConstructL();
IMPORT_C void ExpandBufferL(TInt aCurrentSize);
IMPORT_C TUint8 ReadChar(TInt& aErr);
private:
IMPORT_C virtual void Reserved();
private:
TInt ReadLineL(HBufC8*& aHBuf, TInt aPos,TInt& aErr);
public:
/** A pointer to an RReadStream object, the ReadUint8L() function of which is used
to read single characters from the stream.
This is passed into the NewL() function upon construction. */
RReadStream* iReadStream;
/** A pointer to a buffer which stores data read from the stream.
Its size on construction is EInitialLineSize, and it is expanded by EExpandSize
when necessary.
A copy of this value should not be stored, since the buffer location may change
if the buffer is expanded.
Data in the buffer is not lost when the buffer is expanded, but is copied
to the new location. */
TPtr8 iBufPtr;
protected:
HBufC8* iLineBuf;
TInt iFirstCharNextLine;
private:
MVersitPlugIn* iPlugIn;
TBool iSkipWhiteSpaceAtStart;
CLineReaderExtension* iExtension;
};
class CVersitParser : public CBase
/** A generic Versit parser.
Provides generic functions which implement behaviour common to both vCalendar
and vCard parsers. For instance:
- InternalizeL() and ExternalizeL() functions, for writing and reading
data from a stream or file.
- adding/retrieving properties and sub-entities to/from an existing entity.
- encoding and character set conversion capabilities.
Although this is not an abstract class, in practice you would create and use
objects of a derived class instead (CParserVCal or CParserVCard), as these
provide additional functionality needed for parsing vCalendars and vCards.
Note: a flag used in the class constructor indicates whether the entity needs
a version property. The version property will be inserted at the start of
the array of properties for the entity, and specifies the version of the vCard/vCalendar
specification used by the data of this particular vCard/vCalendar. The versions
that are currently supported are vCard v2.1 and vCalendar v1.0.
A typical vCard looks like this:
BEGIN VCARD
VERSION 2.1 ...
END VCARD
Note: if you are sequentially creating and destroying multiple
parsers, a major performance improvement may be achieved
by using thread local storage to store an instance of CVersitUnicodeUtils
which persists and can be used by all of the parsers.
See CVersitTlsData for more details.
@publishedAll
@released
*/
{
friend class CParserProperty;
public:
IMPORT_C CVersitParser(TUint aFlags);
IMPORT_C void ConstructL();
IMPORT_C ~CVersitParser();
IMPORT_C void InternalizeL(RFile& aInputFile,TInt& aBytesThroughFile);
IMPORT_C virtual void InternalizeL(RReadStream& aStream);
IMPORT_C virtual void InternalizeL(HBufC* aEntityName,CLineReader* aLineReader);
IMPORT_C void ExternalizeL(RFile& aOutputFile);
IMPORT_C virtual void ExternalizeL(RWriteStream& aStream);
IMPORT_C void AddEntityL(CVersitParser* aEntity);
IMPORT_C void AddPropertyL(CParserProperty* aProperty,TBool aInternalizing=EFalse);
IMPORT_C CArrayPtr<CVersitParser>* EntityL(const TDesC& aEntityName,TBool aTakeOwnership=ETrue);
IMPORT_C CArrayPtr<CVersitParser>* ArrayOfEntities(TBool aTakeOwnership=ETrue);
IMPORT_C CArrayPtr<CParserProperty>* PropertyL(const TDesC8& aPropertyName,const TUid& aPropertyUid,TBool aTakeOwnership=ETrue) const;
IMPORT_C CArrayPtr<CParserProperty>* ArrayOfProperties(TBool aTakeOwnership=ETrue);
IMPORT_C virtual void ConvertAllPropertyDateTimesToMachineLocalL(const TTimeIntervalSeconds& aIncrement,const CVersitDaylight* aDaylight);
IMPORT_C void AdjustAllPropertyDateTimesToMachineLocalL();
IMPORT_C static TBool IsValidParameterValue(TInt& aPos,const TDesC& aParamValue);
IMPORT_C void SetEntityNameL(const TDesC& aEntityName);
IMPORT_C TPtrC EntityName() const;
IMPORT_C static TBool IsValidLabel(const TDesC& aLabel, TInt& aPos);
IMPORT_C static TInt Val(const TDesC& aString, TInt& aNumber);
IMPORT_C void SetCharacterConverter(Versit::TEncodingAndCharset& encodingAndCharset);
//
// Set/Get the default settings for the [en|de]coding process
//
IMPORT_C Versit::TVersitEncoding DefaultEncoding() const;
IMPORT_C void SetDefaultEncoding(const Versit::TVersitEncoding aEncoding);
IMPORT_C Versit::TVersitCharSet DefaultCharSet() const;
IMPORT_C TUint DefaultCharSetId() const;
IMPORT_C void SetDefaultCharSet(const Versit::TVersitCharSet aCharSet);
IMPORT_C void SetDefaultCharSetId(TUint aCharSetId);
IMPORT_C void SetAutoDetect(TBool aOn,const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* aAutoDetectCharSets=NULL);
//
// Set/Get Observers and PlugIn's
//
inline void SetObserver(MVersitObserver* aObserver);
inline MVersitObserver* Observer();
inline void SetPlugIn(MVersitPlugIn* aPlugIn);
inline MVersitPlugIn* PlugIn();
public:
IMPORT_C TInt LoadBinaryValuesFromFilesL();
IMPORT_C TInt LoadBinaryValuesFromFilesL(RFs& aFileSession);
IMPORT_C TInt SaveBinaryValuesToFilesL(TInt aSizeThreshold,const TDesC& aPath);
IMPORT_C TInt SaveBinaryValuesToFilesL(TInt aSizeThreshold,const TDesC& aPath,RFs& aFileSession);
public:
/** White space character codes: used while analysing the syntax of the received
data and while externalising data.
@publishedAll
@released
*/
enum TCharCodes
{
/** ' ' */
ESpace = ' ',
/** 9 */
EHTab = 9,
/** 10 */
ELineFeed = 10,
/** 13 */
ECarriageReturn = 13,
/** ':' */
EColon =':'
};
/** Flags that can be specified on construction.
@publishedAll
@released
*/
enum TVersitParserFlags
{
/** This entity does not need a version property. */
ENoVersionProperty = 0,
/** This entity should have a version property. */
ESupportsVersion = 0x01,
//Gaps since other flags have been used in past
EImportSyncML = 0x1000, //Importing from a SyncML server
/** Indicates whether the parser should use auto-detection of character sets when
one has not been explicitly specified. */
EUseAutoDetection = 0x4000,
//versit Internal use only
/** The current property has specified a character set. */
ECharSetIdentified = 0x8000,
/** If the charset is not explicitly specified, the default charset will be used instead of US-ASCII as required
by the Versit specification . */
EUseDefaultCharSetForAllProperties = 0x2000
};
//
// Unicode support conversion functions
//
IMPORT_C static TInt ConvertFromUnicodeToISOL(TDes8& aIso, const TDesC16& aUnicode, CCnvCharacterSetConverter* aConverter);
IMPORT_C TVersitDateTime* DecodeDateTimeL(TDes& aToken) const;
protected:
IMPORT_C TInt ConvertToUnicodeFromISOL(TDes16& aUnicode, const TDesC8& aIso, TUint aCharacterSet);
//
// Parsing high level functions
//
IMPORT_C void ParsePropertiesL();
IMPORT_C void ParseBeginL();
IMPORT_C void ParseEndL();
void ParseEndL(HBufC16& aEntityName);
IMPORT_C TBool ParseEntityL();
IMPORT_C virtual void ParsePropertyL();
IMPORT_C CArrayPtr<CParserParam>* ReadLineAndDecodeParamsLC(TInt& aValueStart,TInt& aNameLen);
IMPORT_C void MakePropertyL(TPtr8& aPropName,TInt aValueStart);
IMPORT_C CArrayPtr<CParserParam>* GetPropertyParamsLC(TPtr8 aParams);
IMPORT_C void ParseParamL(CArrayPtr<CParserParam>* aArray,TPtr8 aParam);
IMPORT_C void AnalysesEncodingCharset(CArrayPtr<CParserParam>* aArrayOfParams);
IMPORT_C void ReadMultiLineValueL(TPtr8& aValue,TInt aValueStart,TBool aBinaryData);
inline TPtr8& BufPtr();
//
// Append standard versit tokens to streams
//
IMPORT_C void AppendBeginL();
IMPORT_C void AppendEndL();
void AppendEntityNameL();
IMPORT_C void DoAddPropertyL(CParserProperty* aProperty);
//
// Dispatcher functions to create entities/properties based upon a Versit identifying Uid
//
IMPORT_C virtual CVersitParser* MakeEntityL(TInt aEntityUid,HBufC* aEntityName);
CParserPropertyValueHBufC* MakeDefaultPropertyValueL(HBufC16*& aValue);
IMPORT_C virtual CParserPropertyValue* MakePropertyValueL(const TUid& aPropertyUid,HBufC16*& aValue);
IMPORT_C HBufC* DecodePropertyValueL(const TDesC8& aValue);
IMPORT_C void DecodePropertyValueL(const TDesC8& aValue,const TUid& aEncodingUid);
HBufC* ConvertToUnicodeL(const TDesC8& aValue);
IMPORT_C CDesCArray* MakePropertyValueCDesCArrayL(TPtr16 aStringValue);
IMPORT_C CArrayPtr<TVersitDateTime>* MakePropertyValueMultiDateTimeL(TPtr16 aDateTimeGroup);
IMPORT_C CVersitDaylight* MakePropertyValueDaylightL(TPtr16 aDaylightValue);
IMPORT_C TBool FindFirstField(TPtr16& aField,TPtr16& aRemaining, TBool aTrimSpace=ETrue);
IMPORT_C void FindRemainingField(TPtr16& aField,TPtr16& aRemaining);
//
// Helper methods to decode versit dates, times, and time periods
//
IMPORT_C TTimeIntervalSeconds DecodeTimeZoneL(const TDesC& aToken) const;
IMPORT_C TTime* DecodeTimePeriodL(const TDesC& aToken) const;
IMPORT_C TInt GetNumberL(const TDesC& aToken,TInt& aNumChars) const;
public:
IMPORT_C virtual TUid RecognizeToken(const TDesC8& aToken) const;
IMPORT_C virtual TInt RecognizeEntityName() const;
//
// Cleanup support methods
//
IMPORT_C static void ResetAndDestroyArrayOfParams(TAny* aObject);
IMPORT_C static void ResetAndDestroyArrayOfProperties(TAny* aObject);
IMPORT_C static void ResetAndDestroyArrayOfEntities(TAny* aObject);
IMPORT_C static void ResetAndDestroyArrayOfDateTimes(TAny* aObject);
inline void SetFlags(TUint aFlags);
protected:
//
// Enquiry functions
//
static TBool IsPunctuationToken(TUint aChar);
inline TBool SupportsVersion() const;
inline void SetSupportsVersion();
inline void ClearSupportsVersion();
//
// Set the settings for the [en|de]coding of the current property
//
IMPORT_C void RestoreLineCodingDetailsToDefault();
IMPORT_C void SetLineEncoding(Versit::TVersitEncoding aLineEncoding);
IMPORT_C void SetLineEncoding(TUint aVersitEncodingUid);
IMPORT_C void SetLineCharacterSet(Versit::TVersitCharSet aLineCharSet);
IMPORT_C void SetLineCharacterSetId(TUint aLineCharSetId);
IMPORT_C void SetLineCoding(Versit::TVersitCharSet aLineCharSet, Versit::TVersitEncoding aLineEncoding);
//
// Return the settings for the current property
//
IMPORT_C Versit::TVersitEncoding LineEncoding() const;
IMPORT_C Versit::TVersitCharSet LineCharSet() const;
IMPORT_C TUint LineEncodingId() const;
IMPORT_C TUint LineCharSetId() const;
inline CVersitUnicodeUtils& UnicodeUtils();
public:
//
// Static utility functions to aid with the Unicode conversion process
//
static TUint MapVersitCharsetToCharConvCharset(Versit::TVersitCharSet aVersitSet);
static TUint MapVersitEncodingToConArcUid(Versit::TVersitEncoding aVersitEncoding);
private:
void SetLineCharsetDetailsToDefault();
void SetLineEncodingDetailsToDefault();
private: //To fix TimeZone SyncML bug
void ConvertAllUTCDateTimesToMachineLocalL(const TTimeIntervalSeconds& aIncrement,const CVersitDaylight* aDaylight);
void ConvertUTCDateTimeToMachineLocal(TVersitDateTime* aDateTime,const TTimeIntervalSeconds& aIncrement,const CVersitDaylight* aDaylight);
//void AddTimeZonePropertyL();
protected:
struct TParserCodingDetails
{
Versit::TVersitEncoding iEncoding;
TUint iEncodingUid;
Versit::TVersitCharSet iCharSet;
TUint iCharSetUid;
};
protected:
// Default settings & internal flags
TInt iFlags;
TParserCodingDetails iDefaultCodingDetails;
TParserCodingDetails iCurrentPropertyCodingDetails;
TBuf<KVersitMaxVersionLength> iDefaultVersion;
const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iAutoDetectCharSets;
// Member data relating to the current item being parsed
HBufC* iEntityName;
CArrayPtr<CVersitParser>* iArrayOfEntities;
CArrayPtr<CParserProperty>* iArrayOfProperties;
CParserProperty* iCurrentProperty;
CLineReader* iOwnedLineReader;
CLineReader* iLineReader;
HBufC8* iDecodedValue;
CBufSeg* iLargeDataBuf;
// In memory buffers
RWriteStream* iWriteStream;
// General utility class
CVersitTlsData* iStaticUtils;
// Plug-in classes
MVersitObserver* iObserver;
MVersitPlugIn* iPlugIn;
private:
void DoInternalizeL();
IMPORT_C virtual void Reserved1();
IMPORT_C virtual void Reserved2();
private:
TInt iParseBegin;
TInt iReserved2;
};
#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
NONSHARABLE_CLASS( CVersitTLSContainer ): public CBase
/**
Wrapper class for static variables to be stored in TLS
@internalComponent
@released
*/
{
public:
static CVersitTLSContainer *NewLC(const TInt aSize);
~CVersitTLSContainer();
public:
HBufC * iShiftJisEscape;//Store shift-jis escape charcter, as generated by relevant charconv plugin
};
#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
#include <versit.inl>
#endif