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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
25 #ifndef __E32DES16_H__
38 /** A Versit parser observer.
40 This is a plug-in class and contains only pure virtual functions.
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.
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.
52 An observer is set up for a Versit parser using CVersitParser::SetObserver().
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
62 An implementation of this function can determine the version of an entity
65 Called by CVersitParser::ParsePropertiesL().
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.
73 @param aParser The newly created Versit entity. */
74 virtual void NewParser(CVersitParser* aParser)=0;
76 IMPORT_C virtual void Reserved1();
77 IMPORT_C virtual void Reserved2();
81 /** A Versit parser plug-in.
83 This is a plug-in class and contains only pure virtual functions.
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.
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.
99 /** Tests whether a space is to be added when merging (unwrapping) two lines
100 while internalising a stream.
102 If there is no plug-in then a space will be added.
104 Used by the CLineReader class.
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.
111 Note that the first space is always ignored and never included.
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.
117 Used by the CLineReader class.
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.
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.
127 If there is no plug-in then a blank line will be looked for.
129 Used by the CVersitParser class.
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
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().
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.
149 Note that, although the string passed into this function can be changed, it
150 must not be made longer.
152 Used by the CVersitParser class.
154 @param aText The property value text from which escape characters are to be
156 virtual void RemoveEscaping(TPtr16& aText)=0;
157 /** Allows the addition of escape characters to a property value when externalising
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()
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.
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
177 aText=aText->ReAllocL(newSize);
180 Used by the CParserPropertyValue class.
182 @param aText The property value text to which escape characters are to be
184 virtual void AddEscaping(HBufC16*& aText)=0;
185 /** Determines how an unencoded property value should be wrapped when externalising
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.
193 Used by the CParserPropertyValue class.
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
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.
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.
214 Used by the CVersitParser plug-in when externalising a property.
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
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.
234 Can override the default name Versit would select if there was no plug-in ("BASE64",
235 "QUOTED-PRINTABLE", "8-BIT").
237 The default names are selected using VersitUtils::IANAEncodingName().
239 Used by the CVersitParser class when externalising a property.
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;
246 /** Returns a pointer to a specified interface extension - to allow future extension
247 of this class without breaking binary compatibility
249 @param aInterfaceUid Identifier of the interface to be retrieved
250 @param aInterface A reference to a pointer that retrieves the specified interface.
252 IMPORT_C virtual void GetInterface(TUid aInterfaceUid, TAny*& aInterface);
254 IMPORT_C virtual void Reserved2();