Class MVersitPlugIn

class MVersitPlugIn;

Description

A Versit parser plug-in.

This is a plug-in class and contains only pure virtual functions.

An implementator of this class can override some of the low level behaviour of a Versit parser. For instance, options are provided to determine behaviour during line wrapping and unwrapping.

The use of this plug-in is optional, and when there is no plug-in the parser object will use default behaviour. However, vCard v3.0 has some differences to vCard v2.1, such as for line wrapping and unwrapping. Symbian OS supports vCard v2.1 in its default behaviour. Therefore this plug-in can be used to provide compatibility with vCard v3.0.

Members

Defined in MVersitPlugIn:
AddEscaping(), AddSpace(), DeleteAllSpaces(), EncodingName(), EncodingType(), GetInterface(), NeedsBlankLine(), RemoveEscaping(), WrapLine()

virtual TBool AddSpace()=0;

Description

Tests whether a space is to be added when merging (unwrapping) two lines while internalising a stream.

If there is no plug-in then a space will be added.

Used by the CLineReader class.

Return value

TBool ETrue if a space is to be added and EFalse if not.

virtual TBool DeleteAllSpaces()=0;

Description

Tests whether white space at the start of a line, apart from the first space, forms part of the data when internalising a stream.

Note that the first space is always ignored and never included.

If there is no plug-in then the rest of the white space at the start of a line (tabs and spaces) is skipped and does not form part of the data when internalising a stream.

Used by the CLineReader class.

Return value

TBool EFalse if the spaces are to be part of the data and ETrue if not.

virtual TBool NeedsBlankLine()=0;

Description

Tests how the end of Base64 data (data encoded using Versit::EBase64Encoding) should be detected when internalising a stream.

To determine the end of Base64 data, either a blank line can be used, or a line without a space at the start.

If there is no plug-in then a blank line will be looked for.

Used by the CVersitParser class.

Return value

TBool ETrue if a blank line should be used and EFalse if a line without a space at the start should be used.

virtual void RemoveEscaping(TPtr16 &aText)=0;

Description

Allows the removal of escape characters from a property value when internalising from a stream.

Versit deals with the escaping of semi-colons and the escape character itself (that is, the Yen character for Shift-JIS or a backslash for other character sets) without the help of a plug-in. Other characters, such as commas and carriage returns, can be escaped and un-escaped using the plug-in's AddEscaping() and RemoveEscaping().

This function is needed as escaping is done differently in vCard v3.0: firstly, commas are used as syntactical characters and so need to be escaped when they are just part of the text; secondly, \r\n in plain (un-encoded) text is used to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if there is a CRLF in the data.

Note that, although the string passed into this function can be changed, it must not be made longer.

Used by the CVersitParser class.

Parameters

TPtr16 &aText The property value text from which escape characters are to be removed.

virtual void AddEscaping(HBufC16 *&aText)=0;

Description

Allows the addition of escape characters to a property value when externalising to a stream.

Versit deals with the escaping of semi-colons and the escape character itself (that is, the Yen character for Shift-JIS or a backslash for other character sets) without the help of a plug-in. Other characters, such as commas and carriage returns, can be escaped and un-escaped using the plug-in's RemoveEscaping() and AddEscaping().

This function is needed as escaping is done differently in vCard v3.0: firstly, commas are used as syntactical characters and so need to be escaped when they are just part of the text; secondly, \r\n in plain (un-encoded) text is used to mean a CRLF, whereas v2.1 forces you to use Quoted Printble encoding if there is a CRLF in the data.

If the string passed into this function needs to be made longer, then this should be done with the following command, otherwise the cleanup stack will eventually panic:

    aText=aText->ReAllocL(newSize); 

Used by the CParserPropertyValue class.

Parameters

HBufC16 *&aText The property value text to which escape characters are to be added.

virtual TBool WrapLine(RWriteStream &aStream, TInt &aCurrentLineLength, const TPtr8 &aText)=0;

Description

Determines how an unencoded property value should be wrapped when externalising to a stream.

If there is no plug-in then line wrapping will follow vCal v1.0 and vCard v2.1 wrapping rules. In this case, the text is split into lines with a maximum length of KMaxExternalizedTokenLength (70) characters, and two spaces are inserted at the beginning of each new line.

Used by the CParserPropertyValue class.

Parameters

RWriteStream &aStream The stream to write the text to. TInt &aCurrentLineLength The number of characters already written to the current line, which needs to be taken into account when calculating where the next line break should occur. This value should be updated before returning. const TPtr8 &aText The property value text to write to the stream, in the correct character set and encoded as necessary.

Return value

TBool ETrue if the property value is wrapped using the method defined in this (overloaded) function. EFalse if the property value text is not wrapped by this function (in which case the default wrapping rules are implemented).

virtual TBool EncodingType(Versit::TVersitEncoding &aEncoding, TBool aRequiresEncoding, Versit::TVersitEncoding aDefaultEncoding,TUid aPropertyUid, TUint aPropertyCharsetId)=0;

Description

Determines how property values are encoded when externalising a property to a stream.

This function is called for each property in turn and can specify how encoding should be implemented for the value of that property.

If there is no plug-in, or this function returns EFalse, then the default rules are used to determine how each property value is encoded.

Used by the CVersitParser plug-in when externalising a property.

Parameters

Versit::TVersitEncoding &aEncoding On return, specifies the encoding type used. TBool aRequiresEncoding ETrue if encoding is required. This is the case if either the default encoding is not Versit::ENoEncoding, or if the property value contains characters that cannot be written out directly (e.g. equals, CR, LF, tab or non-ASCII characters). Versit::TVersitEncoding aDefaultEncoding The default encoding specifed by the user of the parser. TUid aPropertyUid The property UID of the property being externalised. These are defined in vuid.h. TUint aPropertyCharsetId The character set UID of the character set being used to output the property.

Return value

TBool ETrue if the encoding type to be used is defined in this (overloaded) function. EFalse if this function does not determine the encoding type (in which case Versit's default method is used to decide the encoding type).

virtual const TDesC8 &EncodingName(Versit::TVersitEncoding aEncoding)=0;

Description

Returns the encoding name to be used for a specified encoding type when externalising a property to a stream, or allows the default name to be used.

Can override the default name Versit would select if there was no plug-in ("BASE64", "QUOTED-PRINTABLE", "8-BIT").

The default names are selected using VersitUtils::IANAEncodingName().

Used by the CVersitParser class when externalising a property.

Parameters

Versit::TVersitEncoding aEncoding The encoding type the name is required for.

Return value

const TDesC8 & The name to use for the encoding type, or a zero length descriptor if the default name should be used.

virtual IMPORT_C void GetInterface(TUid aInterfaceUid, TAny *&aInterface);

Description

Returns a pointer to a specified interface extension - to allow future extension of this class without breaking binary compatibility

Parameters

TUid aInterfaceUid Identifier of the interface to be retrieved TAny *&aInterface A reference to a pointer that retrieves the specified interface.