1 vobserv.h |
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 |