#include <app/vobserv.h>
| class MVersitPlugIn |
| Public Member Functions | |
|---|---|
| pure virtual void | AddEscaping(HBufC16 *&) |
| pure virtual TBool | AddSpace() |
| pure virtual TBool | DeleteAllSpaces() |
| pure virtual const TDesC8 & | EncodingName(Versit::TVersitEncoding) |
| pure virtual TBool | EncodingType(Versit::TVersitEncoding &, TBool, Versit::TVersitEncoding, TUid, TUint) |
| virtual IMPORT_C void | GetInterface(TUid, TAny *&) |
| pure virtual TBool | NeedsBlankLine() |
| pure virtual void | RemoveEscaping(TPtr16 &) |
| pure virtual TBool | WrapLine(RWriteStream &, TInt &, const TPtr8 &) |
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.
| void | AddEscaping | ( | 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.
| Parameter | Description |
|---|---|
| aText | The property value text to which escape characters are to be added. |
| 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.
Returns: ETrue if a space is to be added and EFalse if not.
| 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.
Returns: EFalse if the spaces are to be part of the data and ETrue if not.
| const TDesC8 & | EncodingName | ( | Versit::TVersitEncoding | aEncoding | ) | [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.
| Parameter | Description |
|---|---|
| aEncoding | The encoding type the name is required for. |
Returns: The name to use for the encoding type, or a zero length descriptor if the default name should be used.
| TBool | EncodingType | ( | Versit::TVersitEncoding & | aEncoding, |
| TBool | aRequiresEncoding, | |||
| Versit::TVersitEncoding | aDefaultEncoding, | |||
| TUid | aPropertyUid, | |||
| TUint | aPropertyCharsetId | |||
| ) | [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.
| Parameter | Description |
|---|---|
| aEncoding | On return, specifies the encoding type used. |
| 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). |
| aDefaultEncoding | The default encoding specifed by the user of the parser. |
| aPropertyUid | The property UID of the property being externalised. These are defined in vuid.h. |
| aPropertyCharsetId | The character set UID of the character set being used to output the property. |
Returns: 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).
Returns a pointer to a specified interface extension - to allow future extension of this class without breaking binary compatibility
| Parameter | Description |
|---|---|
| aInterfaceUid | Identifier of the interface to be retrieved |
| aInterface | A reference to a pointer that retrieves the specified interface. |
| 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.
Returns: ETrue if a blank line should be used and EFalse if a line without a space at the start should be used.
| void | RemoveEscaping | ( | 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.
| Parameter | Description |
|---|---|
| aText | The property value text from which escape characters are to be removed. |
| 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.
| Parameter | Description |
|---|---|
| aStream | The stream to write the text to. |
| 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. |
| aText | The property value text to write to the stream, in the correct character set and encoded as necessary. |
Returns: 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).