epoc32/include/app/vobserv.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:27:01 +0100
branchSymbian2
changeset 3 e1b950c65cb4
parent 2 epoc32/include/vobserv.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
     1 // Copyright (c) 2002-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 __VOBSERV_H__
    17 #define __VOBSERV_H__
    18 
    19 #ifndef __E32DEF_H__
    20 #include <e32def.h>
    21 #endif
    22 #ifndef __E32STD_H__
    23 #include <e32std.h>
    24 #endif
    25 #ifndef __E32DES16_H__
    26 #include <e32des16.h>
    27 #endif
    28 #ifndef __S32STRM_H__
    29 #include <s32strm.h>
    30 #endif
    31 #ifndef __VUTIL_H__
    32 #include <vutil.h>
    33 #endif
    34 
    35 class CVersitParser;
    36 
    37 class MVersitObserver
    38 /** A Versit parser observer.
    39 
    40 This is a plug-in class and contains only pure virtual functions.
    41 
    42 An implementator of this class can find out the version number of an entity 
    43 being parsed. The version number specifies the version of the vCard/vCalendar 
    44 specification used by the data of the vCard/vCalendar. This is for use in 
    45 conjunction with the MVersitPlugin class, which adjusts the parser's behaviour 
    46 according to the vCard/vCalendar version.
    47 
    48 An implementator of this class can also respond to the creation of a new parser 
    49 for an embedded sub-entity. This is so that the observer can set the MVersitPlugin, 
    50 as well as itself, for each new parser that is created.
    51 
    52 An observer is set up for a Versit parser using CVersitParser::SetObserver(). 
    53 @publishedAll
    54 @released
    55 */
    56 	{
    57 public:
    58 	/** Called when the version property (a property of the name KVersitTokenVERSION) 
    59 	of an entity is parsed during internalisation of a stream, if the Versit parser 
    60 	has an observer.
    61 	
    62 	An implementation of this function can determine the version of an entity 
    63 	being parsed.
    64 	
    65 	Called by CVersitParser::ParsePropertiesL().
    66 	
    67 	@param aParser A pointer to the parser object that detected the version.
    68 	@param aVersion A unicode string containing the version number detected. */
    69 	virtual void VersionSet(CVersitParser* aParser,const TDesC16& aVersion)=0;
    70 	/** Called when a new Versit parser is created to parse an embedded object, 
    71 	specifically a vEvent, a vTodo or an agent, if the Versit parser has an observer.
    72 	
    73 	@param aParser The newly created Versit entity. */
    74 	virtual void NewParser(CVersitParser* aParser)=0;
    75 private:
    76 	IMPORT_C virtual void Reserved1();
    77 	IMPORT_C virtual void Reserved2();
    78 	};
    79 
    80 class MVersitPlugIn
    81 /** A Versit parser plug-in.
    82 
    83 This is a plug-in class and contains only pure virtual functions.
    84 
    85 An implementator of this class can override some of the low level behaviour 
    86 of a Versit parser. For instance, options are provided to determine behaviour 
    87 during line wrapping and unwrapping.
    88 
    89 The use of this plug-in is optional, and when there is no plug-in the parser 
    90 object will use default behaviour. However, vCard v3.0 has some differences 
    91 to vCard v2.1, such as for line wrapping and unwrapping. Symbian OS supports 
    92 vCard v2.1 in its default behaviour. Therefore this plug-in can be used to 
    93 provide compatibility with vCard v3.0. 
    94 @publishedAll
    95 @released
    96 */
    97 	{
    98 public:
    99 	/** Tests whether a space is to be added when merging (unwrapping) two lines 
   100 	while internalising a stream. 
   101 	
   102 	If there is no plug-in then a space will be added.
   103 	
   104 	Used by the CLineReader class.
   105 	
   106 	@return ETrue if a space is to be added and EFalse if not. */
   107 	virtual TBool AddSpace()=0;				//Unwrapping lines
   108 	/** Tests whether white space at the start of a line, apart from the first space, 
   109 	forms part of the data when internalising a stream.
   110 	
   111 	Note that the first space is always ignored and never included.
   112 	
   113 	If there is no plug-in then the rest of the white space at the start of a 
   114 	line (tabs and spaces) is skipped and does not form part of the data when 
   115 	internalising a stream.
   116 	
   117 	Used by the CLineReader class.
   118 	
   119 	@return EFalse if the spaces are to be part of the data and ETrue if not. */
   120 	virtual TBool DeleteAllSpaces()=0;		//Unwrapping lines
   121 	/** Tests how the end of Base64 data (data encoded using Versit::EBase64Encoding) 
   122 	should be detected when internalising a stream. 
   123 	
   124 	To determine the end of Base64 data, either a blank line can be used, or a line 
   125 	without a space at the start.
   126 	
   127 	If there is no plug-in then a blank line will be looked for. 
   128 	
   129 	Used by the CVersitParser class.
   130 	
   131 	@return ETrue if a blank line should be used and EFalse if a line without 
   132 	a space at the start should be used. */
   133 	virtual TBool NeedsBlankLine()=0;		//Unwrapping Base64 data
   134 	/** Allows the removal of escape characters from a property value when internalising 
   135 	from a stream.
   136 	
   137 	Versit deals with the escaping of semi-colons and the escape character itself 
   138 	(that is, the Yen character for Shift-JIS or a backslash for other character 
   139 	sets) without the help of a plug-in. Other characters, such as commas and 
   140 	carriage returns, can be escaped and un-escaped using the plug-in's AddEscaping() 
   141 	and RemoveEscaping().
   142 	
   143 	This function is needed as escaping is done differently in vCard v3.0: firstly, 
   144 	commas are used as syntactical characters and so need to be escaped when they 
   145 	are just part of the text; secondly, \\r\\n in plain (un-encoded) text is used 
   146 	to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if 
   147 	there is a CRLF in the data.
   148 	
   149 	Note that, although the string passed into this function can be changed, it 
   150 	must not be made longer.
   151 	
   152 	Used by the CVersitParser class.
   153 	
   154 	@param aText The property value text from which escape characters are to be 
   155 	removed. */
   156 	virtual void RemoveEscaping(TPtr16& aText)=0;
   157 	/** Allows the addition of escape characters to a property value when externalising 
   158 	to a stream. 
   159 	
   160 	Versit deals with the escaping of semi-colons and the escape character itself 
   161 	(that is, the Yen character for Shift-JIS or a backslash for other character 
   162 	sets) without the help of a plug-in. Other characters, such as commas and 
   163 	carriage returns, can be escaped and un-escaped using the plug-in's RemoveEscaping() 
   164 	and AddEscaping().
   165 	
   166 	This function is needed as escaping is done differently in vCard v3.0: firstly, 
   167 	commas are used as syntactical characters and so need to be escaped when they 
   168 	are just part of the text; secondly, \\r\\n in plain (un-encoded) text is used 
   169 	to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if 
   170 	there is a CRLF in the data.
   171 	
   172 	If the string passed into this function needs to be made longer, then this 
   173 	should be done with the following command, otherwise the cleanup stack will 
   174 	eventually panic:
   175 	
   176 	@code
   177 	aText=aText->ReAllocL(newSize); 
   178 	@endcode
   179 	
   180 	Used by the CParserPropertyValue class.
   181 	
   182 	@param aText The property value text to which escape characters are to be 
   183 	added. */
   184 	virtual void AddEscaping(HBufC16*& aText)=0;
   185 	/** Determines how an unencoded property value should be wrapped when externalising 
   186 	to a stream.
   187 	
   188 	If there is no plug-in then line wrapping will follow vCal v1.0 and vCard 
   189 	v2.1 wrapping rules. In this case, the text is split into lines with a maximum 
   190 	length of KMaxExternalizedTokenLength (70) characters, and two spaces are inserted 
   191 	at the beginning of each new line.
   192 	
   193 	Used by the CParserPropertyValue class.
   194 	
   195 	@param aStream The stream to write the text to.
   196 	@param aCurrentLineLength The number of characters already written to the current 
   197 	line, which needs to be taken into account when calculating where the next 
   198 	line break should occur. This value should be updated before returning.
   199 	@param aText The property value text to write to the stream, in the correct 
   200 	character set and encoded as necessary.
   201 	@return ETrue if the property value is wrapped using the method defined in 
   202 	this (overloaded) function. EFalse if the property value text is not wrapped 
   203 	by this function (in which case the default wrapping rules are implemented). */
   204 	virtual TBool WrapLine(RWriteStream& aStream,TInt& aCurrentLineLength,const TPtr8& aText)=0;
   205 	/** Determines how property values are encoded when externalising a property to 
   206 	a stream.
   207 	
   208 	This function is called for each property in turn and can specify how encoding 
   209 	should be implemented for the value of that property.
   210 	
   211 	If there is no plug-in, or this function returns EFalse, then the default 
   212 	rules are used to determine how each property value is encoded.
   213 	
   214 	Used by the CVersitParser plug-in when externalising a property.
   215 	
   216 	@param aEncoding On return, specifies the encoding type used.
   217 	@param aRequiresEncoding ETrue if encoding is required. This is the case if 
   218 	either the default encoding is not Versit::ENoEncoding, or if the property 
   219 	value contains characters that cannot be written out directly (e.g. equals, 
   220 	CR, LF, tab or non-ASCII characters).
   221 	@param aDefaultEncoding The default encoding specifed by the user of the parser.
   222 	@param aPropertyUid The property UID of the property being externalised. These are 
   223 	defined in vuid.h.
   224 	@param aPropertyCharsetId The character set UID of the character set being 
   225 	used to output the property.
   226 	@return ETrue if the encoding type to be used is defined in this (overloaded) 
   227 	function. EFalse if this function does not determine the encoding type (in 
   228 	which case Versit's default method is used to decide the encoding type). */
   229 	virtual TBool EncodingType(Versit::TVersitEncoding& aEncoding,TBool aRequiresEncoding,Versit::TVersitEncoding aDefaultEncoding
   230 																						,TUid aPropertyUid,TUint aPropertyCharsetId)=0;
   231 	/** Returns the encoding name to be used for a specified encoding type when externalising 
   232 	a property to a stream, or allows the default name to be used.
   233 	
   234 	Can override the default name Versit would select if there was no plug-in ("BASE64", 
   235 	"QUOTED-PRINTABLE", "8-BIT").
   236 	
   237 	The default names are selected using VersitUtils::IANAEncodingName().
   238 	
   239 	Used by the CVersitParser class when externalising a property.
   240 	
   241 	@param aEncoding The encoding type the name is required for.
   242 	@return The name to use for the encoding type, or a zero length descriptor 
   243 	if the default name should be used. */
   244 	virtual const TDesC8& EncodingName(Versit::TVersitEncoding aEncoding)=0;
   245 	
   246 	/** Returns a pointer to a specified interface extension - to allow future extension
   247 	of this class without breaking binary compatibility
   248 
   249 	@param aInterfaceUid Identifier of the interface to be retrieved
   250 	@param aInterface A reference to a pointer that retrieves the specified interface.
   251 	*/
   252 	IMPORT_C virtual void GetInterface(TUid aInterfaceUid, TAny*& aInterface);
   253 private:
   254 	IMPORT_C virtual void Reserved2();
   255 	};
   256 
   257 #endif