williamr@2: // Copyright (c) 2002-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@2: // 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: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 __VOBSERV_H__
williamr@2: #define __VOBSERV_H__
williamr@2: 
williamr@2: #ifndef __E32DEF_H__
williamr@2: #include <e32def.h>
williamr@2: #endif
williamr@2: #ifndef __E32STD_H__
williamr@2: #include <e32std.h>
williamr@2: #endif
williamr@2: #ifndef __E32DES16_H__
williamr@2: #include <e32des16.h>
williamr@2: #endif
williamr@2: #ifndef __S32STRM_H__
williamr@2: #include <s32strm.h>
williamr@2: #endif
williamr@2: #ifndef __VUTIL_H__
williamr@2: #include <vutil.h>
williamr@2: #endif
williamr@2: 
williamr@2: class CVersitParser;
williamr@2: 
williamr@2: class MVersitObserver
williamr@2: /** A Versit parser observer.
williamr@2: 
williamr@2: This is a plug-in class and contains only pure virtual functions.
williamr@2: 
williamr@2: An implementator of this class can find out the version number of an entity 
williamr@2: being parsed. The version number specifies the version of the vCard/vCalendar 
williamr@2: specification used by the data of the vCard/vCalendar. This is for use in 
williamr@2: conjunction with the MVersitPlugin class, which adjusts the parser's behaviour 
williamr@2: according to the vCard/vCalendar version.
williamr@2: 
williamr@2: An implementator of this class can also respond to the creation of a new parser 
williamr@2: for an embedded sub-entity. This is so that the observer can set the MVersitPlugin, 
williamr@2: as well as itself, for each new parser that is created.
williamr@2: 
williamr@2: An observer is set up for a Versit parser using CVersitParser::SetObserver(). 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Called when the version property (a property of the name KVersitTokenVERSION) 
williamr@2: 	of an entity is parsed during internalisation of a stream, if the Versit parser 
williamr@2: 	has an observer.
williamr@2: 	
williamr@2: 	An implementation of this function can determine the version of an entity 
williamr@2: 	being parsed.
williamr@2: 	
williamr@2: 	Called by CVersitParser::ParsePropertiesL().
williamr@2: 	
williamr@2: 	@param aParser A pointer to the parser object that detected the version.
williamr@2: 	@param aVersion A unicode string containing the version number detected. */
williamr@2: 	virtual void VersionSet(CVersitParser* aParser,const TDesC16& aVersion)=0;
williamr@2: 	/** Called when a new Versit parser is created to parse an embedded object, 
williamr@2: 	specifically a vEvent, a vTodo or an agent, if the Versit parser has an observer.
williamr@2: 	
williamr@2: 	@param aParser The newly created Versit entity. */
williamr@2: 	virtual void NewParser(CVersitParser* aParser)=0;
williamr@2: private:
williamr@2: 	IMPORT_C virtual void Reserved1();
williamr@2: 	IMPORT_C virtual void Reserved2();
williamr@2: 	};
williamr@2: 
williamr@2: class MVersitPlugIn
williamr@2: /** A Versit parser plug-in.
williamr@2: 
williamr@2: This is a plug-in class and contains only pure virtual functions.
williamr@2: 
williamr@2: An implementator of this class can override some of the low level behaviour 
williamr@2: of a Versit parser. For instance, options are provided to determine behaviour 
williamr@2: during line wrapping and unwrapping.
williamr@2: 
williamr@2: The use of this plug-in is optional, and when there is no plug-in the parser 
williamr@2: object will use default behaviour. However, vCard v3.0 has some differences 
williamr@2: to vCard v2.1, such as for line wrapping and unwrapping. Symbian OS supports 
williamr@2: vCard v2.1 in its default behaviour. Therefore this plug-in can be used to 
williamr@2: provide compatibility with vCard v3.0. 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Tests whether a space is to be added when merging (unwrapping) two lines 
williamr@2: 	while internalising a stream. 
williamr@2: 	
williamr@2: 	If there is no plug-in then a space will be added.
williamr@2: 	
williamr@2: 	Used by the CLineReader class.
williamr@2: 	
williamr@2: 	@return ETrue if a space is to be added and EFalse if not. */
williamr@2: 	virtual TBool AddSpace()=0;				//Unwrapping lines
williamr@2: 	/** Tests whether white space at the start of a line, apart from the first space, 
williamr@2: 	forms part of the data when internalising a stream.
williamr@2: 	
williamr@2: 	Note that the first space is always ignored and never included.
williamr@2: 	
williamr@2: 	If there is no plug-in then the rest of the white space at the start of a 
williamr@2: 	line (tabs and spaces) is skipped and does not form part of the data when 
williamr@2: 	internalising a stream.
williamr@2: 	
williamr@2: 	Used by the CLineReader class.
williamr@2: 	
williamr@2: 	@return EFalse if the spaces are to be part of the data and ETrue if not. */
williamr@2: 	virtual TBool DeleteAllSpaces()=0;		//Unwrapping lines
williamr@2: 	/** Tests how the end of Base64 data (data encoded using Versit::EBase64Encoding) 
williamr@2: 	should be detected when internalising a stream. 
williamr@2: 	
williamr@2: 	To determine the end of Base64 data, either a blank line can be used, or a line 
williamr@2: 	without a space at the start.
williamr@2: 	
williamr@2: 	If there is no plug-in then a blank line will be looked for. 
williamr@2: 	
williamr@2: 	Used by the CVersitParser class.
williamr@2: 	
williamr@2: 	@return ETrue if a blank line should be used and EFalse if a line without 
williamr@2: 	a space at the start should be used. */
williamr@2: 	virtual TBool NeedsBlankLine()=0;		//Unwrapping Base64 data
williamr@2: 	/** Allows the removal of escape characters from a property value when internalising 
williamr@2: 	from a stream.
williamr@2: 	
williamr@2: 	Versit deals with the escaping of semi-colons and the escape character itself 
williamr@2: 	(that is, the Yen character for Shift-JIS or a backslash for other character 
williamr@2: 	sets) without the help of a plug-in. Other characters, such as commas and 
williamr@2: 	carriage returns, can be escaped and un-escaped using the plug-in's AddEscaping() 
williamr@2: 	and RemoveEscaping().
williamr@2: 	
williamr@2: 	This function is needed as escaping is done differently in vCard v3.0: firstly, 
williamr@2: 	commas are used as syntactical characters and so need to be escaped when they 
williamr@2: 	are just part of the text; secondly, \\r\\n in plain (un-encoded) text is used 
williamr@2: 	to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if 
williamr@2: 	there is a CRLF in the data.
williamr@2: 	
williamr@2: 	Note that, although the string passed into this function can be changed, it 
williamr@2: 	must not be made longer.
williamr@2: 	
williamr@2: 	Used by the CVersitParser class.
williamr@2: 	
williamr@2: 	@param aText The property value text from which escape characters are to be 
williamr@2: 	removed. */
williamr@2: 	virtual void RemoveEscaping(TPtr16& aText)=0;
williamr@2: 	/** Allows the addition of escape characters to a property value when externalising 
williamr@2: 	to a stream. 
williamr@2: 	
williamr@2: 	Versit deals with the escaping of semi-colons and the escape character itself 
williamr@2: 	(that is, the Yen character for Shift-JIS or a backslash for other character 
williamr@2: 	sets) without the help of a plug-in. Other characters, such as commas and 
williamr@2: 	carriage returns, can be escaped and un-escaped using the plug-in's RemoveEscaping() 
williamr@2: 	and AddEscaping().
williamr@2: 	
williamr@2: 	This function is needed as escaping is done differently in vCard v3.0: firstly, 
williamr@2: 	commas are used as syntactical characters and so need to be escaped when they 
williamr@2: 	are just part of the text; secondly, \\r\\n in plain (un-encoded) text is used 
williamr@2: 	to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if 
williamr@2: 	there is a CRLF in the data.
williamr@2: 	
williamr@2: 	If the string passed into this function needs to be made longer, then this 
williamr@2: 	should be done with the following command, otherwise the cleanup stack will 
williamr@2: 	eventually panic:
williamr@2: 	
williamr@2: 	@code
williamr@2: 	aText=aText->ReAllocL(newSize); 
williamr@2: 	@endcode
williamr@2: 	
williamr@2: 	Used by the CParserPropertyValue class.
williamr@2: 	
williamr@2: 	@param aText The property value text to which escape characters are to be 
williamr@2: 	added. */
williamr@2: 	virtual void AddEscaping(HBufC16*& aText)=0;
williamr@2: 	/** Determines how an unencoded property value should be wrapped when externalising 
williamr@2: 	to a stream.
williamr@2: 	
williamr@2: 	If there is no plug-in then line wrapping will follow vCal v1.0 and vCard 
williamr@2: 	v2.1 wrapping rules. In this case, the text is split into lines with a maximum 
williamr@2: 	length of KMaxExternalizedTokenLength (70) characters, and two spaces are inserted 
williamr@2: 	at the beginning of each new line.
williamr@2: 	
williamr@2: 	Used by the CParserPropertyValue class.
williamr@2: 	
williamr@2: 	@param aStream The stream to write the text to.
williamr@2: 	@param aCurrentLineLength The number of characters already written to the current 
williamr@2: 	line, which needs to be taken into account when calculating where the next 
williamr@2: 	line break should occur. This value should be updated before returning.
williamr@2: 	@param aText The property value text to write to the stream, in the correct 
williamr@2: 	character set and encoded as necessary.
williamr@2: 	@return ETrue if the property value is wrapped using the method defined in 
williamr@2: 	this (overloaded) function. EFalse if the property value text is not wrapped 
williamr@2: 	by this function (in which case the default wrapping rules are implemented). */
williamr@2: 	virtual TBool WrapLine(RWriteStream& aStream,TInt& aCurrentLineLength,const TPtr8& aText)=0;
williamr@2: 	/** Determines how property values are encoded when externalising a property to 
williamr@2: 	a stream.
williamr@2: 	
williamr@2: 	This function is called for each property in turn and can specify how encoding 
williamr@2: 	should be implemented for the value of that property.
williamr@2: 	
williamr@2: 	If there is no plug-in, or this function returns EFalse, then the default 
williamr@2: 	rules are used to determine how each property value is encoded.
williamr@2: 	
williamr@2: 	Used by the CVersitParser plug-in when externalising a property.
williamr@2: 	
williamr@2: 	@param aEncoding On return, specifies the encoding type used.
williamr@2: 	@param aRequiresEncoding ETrue if encoding is required. This is the case if 
williamr@2: 	either the default encoding is not Versit::ENoEncoding, or if the property 
williamr@2: 	value contains characters that cannot be written out directly (e.g. equals, 
williamr@2: 	CR, LF, tab or non-ASCII characters).
williamr@2: 	@param aDefaultEncoding The default encoding specifed by the user of the parser.
williamr@2: 	@param aPropertyUid The property UID of the property being externalised. These are 
williamr@2: 	defined in vuid.h.
williamr@2: 	@param aPropertyCharsetId The character set UID of the character set being 
williamr@2: 	used to output the property.
williamr@2: 	@return ETrue if the encoding type to be used is defined in this (overloaded) 
williamr@2: 	function. EFalse if this function does not determine the encoding type (in 
williamr@2: 	which case Versit's default method is used to decide the encoding type). */
williamr@2: 	virtual TBool EncodingType(Versit::TVersitEncoding& aEncoding,TBool aRequiresEncoding,Versit::TVersitEncoding aDefaultEncoding
williamr@2: 																						,TUid aPropertyUid,TUint aPropertyCharsetId)=0;
williamr@2: 	/** Returns the encoding name to be used for a specified encoding type when externalising 
williamr@2: 	a property to a stream, or allows the default name to be used.
williamr@2: 	
williamr@2: 	Can override the default name Versit would select if there was no plug-in ("BASE64", 
williamr@2: 	"QUOTED-PRINTABLE", "8-BIT").
williamr@2: 	
williamr@2: 	The default names are selected using VersitUtils::IANAEncodingName().
williamr@2: 	
williamr@2: 	Used by the CVersitParser class when externalising a property.
williamr@2: 	
williamr@2: 	@param aEncoding The encoding type the name is required for.
williamr@2: 	@return The name to use for the encoding type, or a zero length descriptor 
williamr@2: 	if the default name should be used. */
williamr@2: 	virtual const TDesC8& EncodingName(Versit::TVersitEncoding aEncoding)=0;
williamr@2: 	
williamr@2: 	/** Returns a pointer to a specified interface extension - to allow future extension
williamr@2: 	of this class without breaking binary compatibility
williamr@2: 
williamr@2: 	@param aInterfaceUid Identifier of the interface to be retrieved
williamr@2: 	@param aInterface A reference to a pointer that retrieves the specified interface.
williamr@2: 	*/
williamr@2: 	IMPORT_C virtual void GetInterface(TUid aInterfaceUid, TAny*& aInterface);
williamr@2: private:
williamr@2: 	IMPORT_C virtual void Reserved2();
williamr@2: 	};
williamr@2: 
williamr@2: #endif