MVersitPlugIn Class Reference

class MVersitPlugIn

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.

Member Functions Documentation

AddEscaping(HBufC16 *&)

voidAddEscaping(HBufC16 *&aText)[pure virtual]

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 *& aTextThe property value text to which escape characters are to be added.

AddSpace()

TBool AddSpace()[pure virtual]

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.

DeleteAllSpaces()

TBool DeleteAllSpaces()[pure virtual]

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.

EncodingName(Versit::TVersitEncoding)

const TDesC8 &EncodingName(Versit::TVersitEncodingaEncoding)[pure virtual]

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 aEncodingThe encoding type the name is required for.

EncodingType(Versit::TVersitEncoding &, TBool, Versit::TVersitEncoding, TUid, TUint)

TBool EncodingType(Versit::TVersitEncoding &aEncoding,
TBoolaRequiresEncoding,
Versit::TVersitEncodingaDefaultEncoding,
TUidaPropertyUid,
TUintaPropertyCharsetId
)[pure virtual]

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 & aEncodingOn return, specifies the encoding type used.
TBool aRequiresEncodingETrue 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 aDefaultEncodingThe default encoding specifed by the user of the parser.
TUid aPropertyUidThe property UID of the property being externalised. These are defined in vuid.h.
TUint aPropertyCharsetIdThe character set UID of the character set being used to output the property.

GetInterface(TUid, TAny *&)

IMPORT_C voidGetInterface(TUidaInterfaceUid,
TAny *&aInterface
)[virtual]

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

Parameters

TUid aInterfaceUidIdentifier of the interface to be retrieved
TAny *& aInterfaceA reference to a pointer that retrieves the specified interface.

NeedsBlankLine()

TBool NeedsBlankLine()[pure virtual]

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.

RemoveEscaping(TPtr16 &)

voidRemoveEscaping(TPtr16 &aText)[pure virtual]

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 & aTextThe property value text from which escape characters are to be removed.

Reserved2()

IMPORT_C voidReserved2()[private, virtual]

Reserved function.

WrapLine(RWriteStream &, TInt &, const TPtr8 &)

TBool WrapLine(RWriteStream &aStream,
TInt &aCurrentLineLength,
const TPtr8 &aText
)[pure virtual]

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 & aStreamThe stream to write the text to.
TInt & aCurrentLineLengthThe 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 & aTextThe property value text to write to the stream, in the correct character set and encoded as necessary.