1.1 --- a/epoc32/include/vobserv.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/vobserv.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,257 @@
1.4 -vobserv.h
1.5 +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __VOBSERV_H__
1.21 +#define __VOBSERV_H__
1.22 +
1.23 +#ifndef __E32DEF_H__
1.24 +#include <e32def.h>
1.25 +#endif
1.26 +#ifndef __E32STD_H__
1.27 +#include <e32std.h>
1.28 +#endif
1.29 +#ifndef __E32DES16_H__
1.30 +#include <e32des16.h>
1.31 +#endif
1.32 +#ifndef __S32STRM_H__
1.33 +#include <s32strm.h>
1.34 +#endif
1.35 +#ifndef __VUTIL_H__
1.36 +#include <vutil.h>
1.37 +#endif
1.38 +
1.39 +class CVersitParser;
1.40 +
1.41 +class MVersitObserver
1.42 +/** A Versit parser observer.
1.43 +
1.44 +This is a plug-in class and contains only pure virtual functions.
1.45 +
1.46 +An implementator of this class can find out the version number of an entity
1.47 +being parsed. The version number specifies the version of the vCard/vCalendar
1.48 +specification used by the data of the vCard/vCalendar. This is for use in
1.49 +conjunction with the MVersitPlugin class, which adjusts the parser's behaviour
1.50 +according to the vCard/vCalendar version.
1.51 +
1.52 +An implementator of this class can also respond to the creation of a new parser
1.53 +for an embedded sub-entity. This is so that the observer can set the MVersitPlugin,
1.54 +as well as itself, for each new parser that is created.
1.55 +
1.56 +An observer is set up for a Versit parser using CVersitParser::SetObserver().
1.57 +@publishedAll
1.58 +@released
1.59 +*/
1.60 + {
1.61 +public:
1.62 + /** Called when the version property (a property of the name KVersitTokenVERSION)
1.63 + of an entity is parsed during internalisation of a stream, if the Versit parser
1.64 + has an observer.
1.65 +
1.66 + An implementation of this function can determine the version of an entity
1.67 + being parsed.
1.68 +
1.69 + Called by CVersitParser::ParsePropertiesL().
1.70 +
1.71 + @param aParser A pointer to the parser object that detected the version.
1.72 + @param aVersion A unicode string containing the version number detected. */
1.73 + virtual void VersionSet(CVersitParser* aParser,const TDesC16& aVersion)=0;
1.74 + /** Called when a new Versit parser is created to parse an embedded object,
1.75 + specifically a vEvent, a vTodo or an agent, if the Versit parser has an observer.
1.76 +
1.77 + @param aParser The newly created Versit entity. */
1.78 + virtual void NewParser(CVersitParser* aParser)=0;
1.79 +private:
1.80 + IMPORT_C virtual void Reserved1();
1.81 + IMPORT_C virtual void Reserved2();
1.82 + };
1.83 +
1.84 +class MVersitPlugIn
1.85 +/** A Versit parser plug-in.
1.86 +
1.87 +This is a plug-in class and contains only pure virtual functions.
1.88 +
1.89 +An implementator of this class can override some of the low level behaviour
1.90 +of a Versit parser. For instance, options are provided to determine behaviour
1.91 +during line wrapping and unwrapping.
1.92 +
1.93 +The use of this plug-in is optional, and when there is no plug-in the parser
1.94 +object will use default behaviour. However, vCard v3.0 has some differences
1.95 +to vCard v2.1, such as for line wrapping and unwrapping. Symbian OS supports
1.96 +vCard v2.1 in its default behaviour. Therefore this plug-in can be used to
1.97 +provide compatibility with vCard v3.0.
1.98 +@publishedAll
1.99 +@released
1.100 +*/
1.101 + {
1.102 +public:
1.103 + /** Tests whether a space is to be added when merging (unwrapping) two lines
1.104 + while internalising a stream.
1.105 +
1.106 + If there is no plug-in then a space will be added.
1.107 +
1.108 + Used by the CLineReader class.
1.109 +
1.110 + @return ETrue if a space is to be added and EFalse if not. */
1.111 + virtual TBool AddSpace()=0; //Unwrapping lines
1.112 + /** Tests whether white space at the start of a line, apart from the first space,
1.113 + forms part of the data when internalising a stream.
1.114 +
1.115 + Note that the first space is always ignored and never included.
1.116 +
1.117 + If there is no plug-in then the rest of the white space at the start of a
1.118 + line (tabs and spaces) is skipped and does not form part of the data when
1.119 + internalising a stream.
1.120 +
1.121 + Used by the CLineReader class.
1.122 +
1.123 + @return EFalse if the spaces are to be part of the data and ETrue if not. */
1.124 + virtual TBool DeleteAllSpaces()=0; //Unwrapping lines
1.125 + /** Tests how the end of Base64 data (data encoded using Versit::EBase64Encoding)
1.126 + should be detected when internalising a stream.
1.127 +
1.128 + To determine the end of Base64 data, either a blank line can be used, or a line
1.129 + without a space at the start.
1.130 +
1.131 + If there is no plug-in then a blank line will be looked for.
1.132 +
1.133 + Used by the CVersitParser class.
1.134 +
1.135 + @return ETrue if a blank line should be used and EFalse if a line without
1.136 + a space at the start should be used. */
1.137 + virtual TBool NeedsBlankLine()=0; //Unwrapping Base64 data
1.138 + /** Allows the removal of escape characters from a property value when internalising
1.139 + from a stream.
1.140 +
1.141 + Versit deals with the escaping of semi-colons and the escape character itself
1.142 + (that is, the Yen character for Shift-JIS or a backslash for other character
1.143 + sets) without the help of a plug-in. Other characters, such as commas and
1.144 + carriage returns, can be escaped and un-escaped using the plug-in's AddEscaping()
1.145 + and RemoveEscaping().
1.146 +
1.147 + This function is needed as escaping is done differently in vCard v3.0: firstly,
1.148 + commas are used as syntactical characters and so need to be escaped when they
1.149 + are just part of the text; secondly, \\r\\n in plain (un-encoded) text is used
1.150 + to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if
1.151 + there is a CRLF in the data.
1.152 +
1.153 + Note that, although the string passed into this function can be changed, it
1.154 + must not be made longer.
1.155 +
1.156 + Used by the CVersitParser class.
1.157 +
1.158 + @param aText The property value text from which escape characters are to be
1.159 + removed. */
1.160 + virtual void RemoveEscaping(TPtr16& aText)=0;
1.161 + /** Allows the addition of escape characters to a property value when externalising
1.162 + to a stream.
1.163 +
1.164 + Versit deals with the escaping of semi-colons and the escape character itself
1.165 + (that is, the Yen character for Shift-JIS or a backslash for other character
1.166 + sets) without the help of a plug-in. Other characters, such as commas and
1.167 + carriage returns, can be escaped and un-escaped using the plug-in's RemoveEscaping()
1.168 + and AddEscaping().
1.169 +
1.170 + This function is needed as escaping is done differently in vCard v3.0: firstly,
1.171 + commas are used as syntactical characters and so need to be escaped when they
1.172 + are just part of the text; secondly, \\r\\n in plain (un-encoded) text is used
1.173 + to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if
1.174 + there is a CRLF in the data.
1.175 +
1.176 + If the string passed into this function needs to be made longer, then this
1.177 + should be done with the following command, otherwise the cleanup stack will
1.178 + eventually panic:
1.179 +
1.180 + @code
1.181 + aText=aText->ReAllocL(newSize);
1.182 + @endcode
1.183 +
1.184 + Used by the CParserPropertyValue class.
1.185 +
1.186 + @param aText The property value text to which escape characters are to be
1.187 + added. */
1.188 + virtual void AddEscaping(HBufC16*& aText)=0;
1.189 + /** Determines how an unencoded property value should be wrapped when externalising
1.190 + to a stream.
1.191 +
1.192 + If there is no plug-in then line wrapping will follow vCal v1.0 and vCard
1.193 + v2.1 wrapping rules. In this case, the text is split into lines with a maximum
1.194 + length of KMaxExternalizedTokenLength (70) characters, and two spaces are inserted
1.195 + at the beginning of each new line.
1.196 +
1.197 + Used by the CParserPropertyValue class.
1.198 +
1.199 + @param aStream The stream to write the text to.
1.200 + @param aCurrentLineLength The number of characters already written to the current
1.201 + line, which needs to be taken into account when calculating where the next
1.202 + line break should occur. This value should be updated before returning.
1.203 + @param aText The property value text to write to the stream, in the correct
1.204 + character set and encoded as necessary.
1.205 + @return ETrue if the property value is wrapped using the method defined in
1.206 + this (overloaded) function. EFalse if the property value text is not wrapped
1.207 + by this function (in which case the default wrapping rules are implemented). */
1.208 + virtual TBool WrapLine(RWriteStream& aStream,TInt& aCurrentLineLength,const TPtr8& aText)=0;
1.209 + /** Determines how property values are encoded when externalising a property to
1.210 + a stream.
1.211 +
1.212 + This function is called for each property in turn and can specify how encoding
1.213 + should be implemented for the value of that property.
1.214 +
1.215 + If there is no plug-in, or this function returns EFalse, then the default
1.216 + rules are used to determine how each property value is encoded.
1.217 +
1.218 + Used by the CVersitParser plug-in when externalising a property.
1.219 +
1.220 + @param aEncoding On return, specifies the encoding type used.
1.221 + @param aRequiresEncoding ETrue if encoding is required. This is the case if
1.222 + either the default encoding is not Versit::ENoEncoding, or if the property
1.223 + value contains characters that cannot be written out directly (e.g. equals,
1.224 + CR, LF, tab or non-ASCII characters).
1.225 + @param aDefaultEncoding The default encoding specifed by the user of the parser.
1.226 + @param aPropertyUid The property UID of the property being externalised. These are
1.227 + defined in vuid.h.
1.228 + @param aPropertyCharsetId The character set UID of the character set being
1.229 + used to output the property.
1.230 + @return ETrue if the encoding type to be used is defined in this (overloaded)
1.231 + function. EFalse if this function does not determine the encoding type (in
1.232 + which case Versit's default method is used to decide the encoding type). */
1.233 + virtual TBool EncodingType(Versit::TVersitEncoding& aEncoding,TBool aRequiresEncoding,Versit::TVersitEncoding aDefaultEncoding
1.234 + ,TUid aPropertyUid,TUint aPropertyCharsetId)=0;
1.235 + /** Returns the encoding name to be used for a specified encoding type when externalising
1.236 + a property to a stream, or allows the default name to be used.
1.237 +
1.238 + Can override the default name Versit would select if there was no plug-in ("BASE64",
1.239 + "QUOTED-PRINTABLE", "8-BIT").
1.240 +
1.241 + The default names are selected using VersitUtils::IANAEncodingName().
1.242 +
1.243 + Used by the CVersitParser class when externalising a property.
1.244 +
1.245 + @param aEncoding The encoding type the name is required for.
1.246 + @return The name to use for the encoding type, or a zero length descriptor
1.247 + if the default name should be used. */
1.248 + virtual const TDesC8& EncodingName(Versit::TVersitEncoding aEncoding)=0;
1.249 +
1.250 + /** Returns a pointer to a specified interface extension - to allow future extension
1.251 + of this class without breaking binary compatibility
1.252 +
1.253 + @param aInterfaceUid Identifier of the interface to be retrieved
1.254 + @param aInterface A reference to a pointer that retrieves the specified interface.
1.255 + */
1.256 + IMPORT_C virtual void GetInterface(TUid aInterfaceUid, TAny*& aInterface);
1.257 +private:
1.258 + IMPORT_C virtual void Reserved2();
1.259 + };
1.260 +
1.261 +#endif