#include <app/versit.h>
| class CVersitParser : public CBase |
| Public Member Enumerations | |
|---|---|
| enum | TCharCodes { ESpace, EHTab, ELineFeed, ECarriageReturn, EColon } |
| enum | TVersitParserFlags { ENoVersionProperty, ESupportsVersion, EImportSyncML, EUseAutoDetection, ..., EUseDefaultCharSetForAllProperties } |
A generic Versit parser.
Provides generic functions which implement behaviour common to both vCalendar and vCard parsers. For instance:
InternalizeL() and ExternalizeL() functions, for writing and reading data from a stream or file.
adding/retrieving properties and sub-entities to/from an existing entity.
encoding and character set conversion capabilities.
Although this is not an abstract class, in practice you would create and use objects of a derived class instead (CParserVCal or CParserVCard), as these provide additional functionality needed for parsing vCalendars and vCards.
Note: a flag used in the class constructor indicates whether the entity needs a version property. The version property will be inserted at the start of the array of properties for the entity, and specifies the version of the vCard/vCalendar specification used by the data of this particular vCard/vCalendar. The versions that are currently supported are vCard v2.1 and vCalendar v1.0.
A typical vCard looks like this:
BEGIN VCARD
VERSION 2.1 ...
END VCARD
Note: if you are sequentially creating and destroying multiple parsers, a major performance improvement may be achieved by using thread local storage to store an instance of CVersitUnicodeUtils which persists and can be used by all of the parsers.
See CVersitTlsData for more details.
| const CArrayFix< CCnvCharacterSetConverter::SCharacterSet > * | iAutoDetectCharSets | [protected] |
Flags that can be specified on construction.
| Enumerator | Value | Description |
|---|---|---|
| ENoVersionProperty | 0 |
This entity does not need a version property. |
| ESupportsVersion | 0x01 |
This entity should have a version property. |
| EImportSyncML | 0x1000 | |
| EUseAutoDetection | 0x4000 |
Indicates whether the parser should use auto-detection of character sets when one has not been explicitly specified. |
| ECharSetIdentified | 0x8000 |
The current property has specified a character set. |
| EUseDefaultCharSetForAllProperties | 0x2000 |
If the charset is not explicitly specified, the default charset will be used instead of US-ASCII as required by the Versit specification . |
| IMPORT_C | CVersitParser | ( | TUint | aFlags | ) |
The first phase constructor for a Versit parser.
Sets the default encoding to Versit::ENoEncoding and the default character set to Versit::EUSAsciiCharSet.
Note: this function is called by the CParserVCal and CParserVCard constructors. It should only be called directly by a user if creating a new parser
| Parameter | Description |
|---|---|
| aFlags | The flag to indicate whether this entity needs a version property. The possible values for this flag are given in the TVersitParserFlags enumeration. If a version property is needed, one will be created and appended to the start of the array of properties. |
| IMPORT_C | ~CVersitParser | ( | ) |
Frees all resources owned by the object, prior to its destruction.
| IMPORT_C void | AddEntityL | ( | CVersitParser * | aEntity | ) |
Adds a sub-entity (e.g. a to-do, event or a nested vCard) to the current entity.
Sets the default encoding and character set to the default ones of the current Versit parser, then adds the entity to the array of entities owned by the parser.
Note: This function may be used when building up a Versit parser object from a client application.
Called by ParseEntityL().
| Parameter | Description |
|---|---|
| aEntity | The entity to be added into the array of entities. Ownership of aEntity is taken at beginning of the function. |
| IMPORT_C void | AddPropertyL | ( | CParserProperty * | aProperty, |
| TBool | aInternalizing = EFalse | |||
| ) | ||||
Appends a property to the current entity's array of properties.
This function may be used when building up a Versit parser object from a client application. It is not called internally.
| Parameter | Description |
|---|---|
| aProperty | Pointer to the property to add to the entity. |
| aInternalizing | This parameter is used to distinguish between reading an entity from a stream or file (i.e. internalising), in which case the argument should have a value of ETrue, and building an entity "by hand" (e.g. creating a vCard in the Contacts application), in which case the argument should have a value of EFalse. |
| IMPORT_C void | AdjustAllPropertyDateTimesToMachineLocalL | ( | ) |
| IMPORT_C void | AnalysesEncodingCharset | ( | CArrayPtr< CParserParam > * | aArrayOfParams | ) | [protected] |
| IMPORT_C CArrayPtr< CVersitParser > * | ArrayOfEntities | ( | TBool | aTakeOwnership = ETrue | ) |
Gets the current entity's array of sub-entities.
Note: the current entity may be a top level entity, or may itself be a sub-entity.
| Parameter | Description |
|---|---|
| aTakeOwnership | If ETrue, the calling code takes ownership of the array; the array of entities owned by the current entity is then deleted. If EFalse, ownership remains with the Versit parser. |
Returns: Array of pointers to the current entity's array of sub-entities.
| IMPORT_C CArrayPtr< CParserProperty > * | ArrayOfProperties | ( | TBool | aTakeOwnership = ETrue | ) |
Gets the current entity's array of properties.
| Parameter | Description |
|---|---|
| aTakeOwnership | If ETrue, the calling code takes ownership of the array; the entity's array of properties is then deleted . If EFalse, ownership remains with the entity. |
Returns: Array of pointers to the entity's properties.
| IMPORT_C void | ConstructL | ( | ) |
The second phase constructor for a Versit parser.
Stores a pointer to a CVersitTlsData (thread local storage data class). This is used to allow an instance of CVersitUnicodeUtils to be shared by all co-existing parsers, which provides a major performance improvement.
Called by the CParserVCal and CParserVCard constructors.
Should only be called directly by a user if creating a new parser.
| IMPORT_C void | ConvertAllPropertyDateTimesToMachineLocalL | ( | const TTimeIntervalSeconds & | aIncrement, |
| const CVersitDaylight * | aDaylight | |||
| ) | [virtual] | |||
Converts all date/time property values contained in the current entity's array of properties into machine local values.
This conversion is needed because of differences in universal and local times due to time zones and daylight savings (seasonal time shifts).
First, all of the date/times are converted to universal time, if they are not already:
If daylight saving is in effect then the daylight savings rule (held in the aDaylight parameter) will be used to compensate for differences between universal and local times due to both time zones and the daylight saving. Otherwise, the aIncrement parameter is used to compensate for any difference due to time zones alone.
Then, these universal time values are converted into machine local times by adding the universal time offset for the machine's locale.
Deprecatedsince 9.1
| Parameter | Description |
|---|---|
| aIncrement | A time interval in seconds which represents the negative of the time zone of the originating machine. For instance, if the time zone is +04:30, aIncrement should be set to -04:30. |
| aDaylight | Pointer to the specification for daylight saving. If the date/time value is within the period for daylight saving, the value is modified by the daylight saving offset (which accounts for both the time zone and daylight saving rule). |
| IMPORT_C TInt | ConvertFromUnicodeToISOL | ( | TDes8 & | aIso, |
| const TDesC16 & | aUnicode, | |||
| CCnvCharacterSetConverter * | aConverter | |||
| ) | [static] | |||
Converts text in the Unicode character set (UCS-2) into a non-unicode (International Standards Organisation) character set.
Which ISO character set the string is converted to is determined by the value of the character set identifier in the aConverter parameter.
| Parameter | Description |
|---|---|
| aIso | On return, the converted text string in the specified ISO character set. |
| aUnicode | The Unicode text string to be converted. |
| aConverter | The character set converter. |
Returns: If no error occurs, this is the number of unconverted characters left at the end of the input descriptor. This is zero if the whole string is converted, but may be greater than zero (e.g. because the output descriptor is not long enough to hold all the text). Otherwise, one of the error values defined in TError in the CCnvCharacterSetConverter class, or KErrNotFound if aConverter does not point to a valid character set converter object.
| IMPORT_C TInt | ConvertToUnicodeFromISOL | ( | TDes16 & | aUnicode, |
| const TDesC8 & | aIso, | |||
| TUint | aCharacterSet | |||
| ) | [protected] | |||
Converts text in a non-Unicode character set into Unicode (UCS-2).
| Parameter | Description |
|---|---|
| aUnicode | On return, the converted text string in the Unicode character set. |
| aIso | The non-Unicode text string to be converted. |
| aCharacterSet | The non-Unicode character set in which aIso is encoded. |
Returns: If no error occurs, the number of unconverted bytes left at the end of the input descriptor. This is zero if the whole string is converted; but it may be greater than zero, e.g. because the output descriptor is not long enough to hold all the text. Otherwise, one of the error values defined in TError in the CCnvCharacterSetConverter class, or KErrNotFound if aCharacterSet cannot be converted.
| IMPORT_C TTimeIntervalSeconds | DecodeTimeZoneL | ( | const TDesC & | aToken | ) | const [protected] |
| IMPORT_C Versit::TVersitCharSet | DefaultCharSet | ( | ) | const |
Gets the default character set or transformation format. This may be used to represent property values in Versit objects.
Returns: The default character set.
| IMPORT_C Versit::TVersitEncoding | DefaultEncoding | ( | ) | const |
Gets the parser's default encoding.
This value is initialised on construction, to ENoEncoding.
Returns: The parser's default encoding.
| IMPORT_C void | DoAddPropertyL | ( | CParserProperty * | aProperty | ) | [protected] |
| IMPORT_C CArrayPtr< CVersitParser > * | EntityL | ( | const TDesC & | aEntityName, |
| TBool | aTakeOwnership = ETrue | |||
| ) | ||||
Gets all sub-entities in the current entity, whose name matches the name specified.
| Parameter | Description |
|---|---|
| aEntityName | The sub-entity name of interest, e.g. KVersitVarTokenVEVENT or KVersitVarTokenVTODO. All sub-entities which match this name are returned in the array of pointers. |
| aTakeOwnership | If ETrue, the calling code takes ownership of each matching sub-entity, in which case the sub-entities are deleted from the current object's array of entities. If EFalse, ownership remains with the Versit parser. |
Returns: An array of pointers to all sub-entities with the specified name. (Ownership is taken by the calling code).
| IMPORT_C TPtrC | EntityName | ( | ) | const |
Gets the current entity's name.
If no name has been set, returns an empty descriptor.
Returns: The current entity's name.
| IMPORT_C void | ExternalizeL | ( | RFile & | aOutputFile | ) |
Externalises a Versit entity (vCard or vCalendar) and all of its sub-entities and properties to a file.
Adds a version property to the start of the current entity's array of properties if the entity supports this.
This is a thin layer over the CVersitParser::ExternalizeL(RWriteStream& aStream) function to enable a versit entity to be externalised into an RFile.
| Parameter | Description |
|---|---|
| aOutputFile | The file to which to write the entity. |
| IMPORT_C void | ExternalizeL | ( | RWriteStream & | aStream | ) | [virtual] |
Externalises a Versit entity (vCard or vCalendar) and all of its sub-entities and properties to a write stream.
Adds a version property to the start of the current entity's array of properties if the entity supports this. (If there isn't an array of properties then one is made).
The presence of this function means that the standard templated operator<<() (defined in s32strm.h) is available to externalise objects of this class.
This virtual function serves as a base function for derived classes to externalise an entity.
| Parameter | Description |
|---|---|
| aStream | Stream to which the entity should be externalised. |
Sets up a pointer to the remaining field. Sets the original remaining field pointers length to 0.
| Parameter | Description |
|---|---|
| aField | on return points to the data and length that aRemaining originally pointed to. |
| aRemaining | as input references a location that the descriptor is to represent. On return length is set to 0. |
| IMPORT_C CArrayPtr< CParserParam > * | GetPropertyParamsLC | ( | TPtr8 | aParams | ) | [protected] |
Internalises a versit entity (vCard or vCalendar) and all of its sub-entities and properties from a file.
Stores all date/time in same format as received
| Parameter | Description |
|---|---|
| aInputFile | The file from which to internalise the entity. |
| aBytesThroughFile | The number of bytes into the file at which to begin reading. On return, is updated to contain the last position in the file which was read. |
| IMPORT_C void | InternalizeL | ( | RReadStream & | aStream | ) | [virtual] |
Internalises a Versit entity (vCard or vCalendar) contained in the incoming stream and parses it, breaking it down into its constituent sub-entities (e.g. to-dos, events, and nested vCards) and properties.
The presence of this function means that the standard templated operator>>() (defined in s32strm.h) is available to internalise objects of this class.
This virtual function serves as a base function for derived classes to internalise an entity.
| Parameter | Description |
|---|---|
| aStream | Stream from which the vCalendar should be internalised. |
| IMPORT_C void | InternalizeL | ( | HBufC * | aEntityName, |
| CLineReader * | aLineReader | |||
| ) | [virtual] | |||
Internalises a vCalendar or vCard sub-entity.
(Assumes "BEGIN : <EntityName> CRLF" has been parsed).
This virtual function serves as a base function for derived classes to parse a sub-entity.
| Parameter | Description |
|---|---|
| aEntityName | The entity name to be parsed. Ownership of aEntityName is taken by the parser. |
| aLineReader | Pointer to a line reader which is used by the super-entity. |
Tests whether a property name is valid.
The property name is invalid if it contains any of the following characters:-
[] (left or right square bracket)
= (equals sign)
: (colon)
. (dot)
, (comma)
| Parameter | Description |
|---|---|
| aLabel | The property name to test. |
| aPos | On return, contains the character position within the property name of the first invalid character found. |
Returns: ETrue if valid, EFalse if invalid.
Tests whether a property parameter name or value is valid.
If the string aParamValue contains any punctuation characters, the string is invalid. Otherwise, it is valid. Punctuation characters are defined as any of the following:-
[] (left or right square bracket)
= (equals sign)
: (colon)
; (semi colon)
. (dot)
, (comma)
| Parameter | Description |
|---|---|
| aPos | On return, contains the character position of the first invalid character in the property parameter name or value. |
| aParamValue | The property parameter name or value to test. |
Returns: ETrue if valid, EFalse if invalid.
| IMPORT_C TInt | LoadBinaryValuesFromFilesL | ( | ) |
Loads all files represented by URI property values and sets the binary data contained in the files to be the property values instead of the URIs.
For every property in the parser, if its value is a URI containing file:// followed by a path and filename, then the file is opened and the binary data it contains is read into a CParserPropertyValueBinary object. This replaces the URI as the property value. The function also operates on any agents in the vCard that contain URI property values.
The function creates its own file server session, which is needed to open the files. It leaves if there is a problem opening any of the files.
Returns: The number of files that were read.
Loads all files represented by URI property values and sets the binary data contained in the files to be the property values instead of the URIs.
For every property in the parser, if its value is a URI containing file:// followed by a path and filename, then the file is opened and the binary data it contains is read into a CParserPropertyValueBinary object. This replaces the URI as the property value. The function also operates on any agents in the vCard that contain URI property values.
The function uses the file server session supplied, which is needed to open the files. It leaves if there is a problem opening any of the files.
| Parameter | Description |
|---|---|
| aFileSession | The file server session used to open the files. |
Returns: The number of files that were read.
| CParserPropertyValueHBufC * | MakeDefaultPropertyValueL | ( | HBufC16 *& | aValue | ) | [protected] |
Instantiates and gives ownership of a CParserPropertyValueHBufC object.
| IMPORT_C CVersitParser * | MakeEntityL | ( | TInt | aEntityUid, |
| HBufC * | aEntityName | |||
| ) | [protected, virtual] | |||
| IMPORT_C CDesCArray * | MakePropertyValueCDesCArrayL | ( | TPtr16 | aStringValue | ) | [protected] |
Parses a compound property value string.
The sub-values found are appended to an array, after removal of escape characters. The array is returned, and ownership is transferred to the caller.
| Parameter | Description |
|---|---|
| aStringValue | Compound property value string. |
Returns: Array of property values found in the string.
| IMPORT_C CVersitDaylight * | MakePropertyValueDaylightL | ( | TPtr16 | aDaylightValue | ) | [protected] |
| IMPORT_C CParserPropertyValue * | MakePropertyValueL | ( | const TUid & | aPropertyUid, |
| HBufC16 *& | aValue | |||
| ) | [protected, virtual] | |||
| IMPORT_C CArrayPtr< TVersitDateTime > * | MakePropertyValueMultiDateTimeL | ( | TPtr16 | aDateTimeGroup | ) | [protected] |
| TUint | MapVersitCharsetToCharConvCharset | ( | Versit::TVersitCharSet | aVersitSet | ) | [static] |
| TUint | MapVersitEncodingToConArcUid | ( | Versit::TVersitEncoding | aVersitEncoding | ) | [static] |
| MVersitObserver * | Observer | ( | ) | [inline] |
Gets a pointer to the Versit observer.
Returns: A pointer to the observer.
| IMPORT_C void | ParseParamL | ( | CArrayPtr< CParserParam > * | aArray, |
| TPtr8 | aParam | |||
| ) | [protected] | |||
| MVersitPlugIn * | PlugIn | ( | ) | [inline] |
Gets a pointer to the Versit plug-in.
Returns: A pointer to the plug-in.
| IMPORT_C CArrayPtr< CParserProperty > * | PropertyL | ( | const TDesC8 & | aPropertyName, |
| const TUid & | aPropertyUid, | |||
| TBool | aTakeOwnership = ETrue | |||
| ) | const | |||
Gets all properties in the current entity's array of properties whose name and value match the name and value specified.
| Parameter | Description |
|---|---|
| aPropertyName | The property name of interest. Property names are defined in vtoken.h. |
| aPropertyUid | The ID of the property value of interest (which has the format "K<Versit/Card/Cal>Property<Type>Uid"). The values are defined in file vuid.h. |
| aTakeOwnership | If ETrue, the calling code takes ownership of each matching property; the property is then deleted from the current entity's array. If EFalse, ownership remains with the entity. |
Returns: An array of pointers to all properties with the name and value specified, or NULL if there are none.
| IMPORT_C CArrayPtr< CParserParam > * | ReadLineAndDecodeParamsLC | ( | TInt & | aValueStart, |
| TInt & | aNameLen | |||
| ) | [protected] | |||
| IMPORT_C TInt | RecognizeEntityName | ( | ) | const [virtual] |
Tests the current entity to see if it is a vEvent or vTodo.
This function is virtual. Actual testing only occurs in derived classes which implement this function.
Returns: Zero. Derived classes' implementations would return a value that indicates the current entity's type.
Returns a UID for the specified token.
This function only recognizes generic Versit tokens. For example, if aToken contains the property name KVersitTokenBEGIN, the function returns KVersitTokenBeginUid. More specific recognition should occur in derived classes which implement this function, using this as the base recogniser.
| Parameter | Description |
|---|---|
| aToken | The token to be recognized. |
Returns: A defined UID value if the token has been recognized; KVersitTokenUnknownUid otherwise.
| IMPORT_C void | ResetAndDestroyArrayOfEntities | ( | TAny * | aObject | ) | [static] |
Destroys an array of entities.
| Parameter | Description |
|---|---|
| aObject | Pointer to the array of entities to be destroyed. |
| IMPORT_C void | ResetAndDestroyArrayOfParams | ( | TAny * | aObject | ) | [static] |
Destroys an array of parameters.
| Parameter | Description |
|---|---|
| aObject | Pointer to the array of parameters to be destroyed. |
| IMPORT_C void | ResetAndDestroyArrayOfProperties | ( | TAny * | aObject | ) | [static] |
Destroys an array of properties.
| Parameter | Description |
|---|---|
| aObject | Pointer to the array of properties to be destroyed. |
Saves all binary property values larger than a specified threshold to files, and sets each property value to be a URI representing the file, rather than the binary data iself.
The files are created in the folder identified by aPath, and are assigned unique filenames that consist of the property name and some random numbers.
Each new URI property value is prefixed with file:// and contains the path and filename of the file created.
If a vCard contains any agent property values and if they contain binary data whose size exceeds the threshold, these property values are replaced with URI property values.
The function sets up its own file server session, which is needed to create the files. It leaves if there is a problem creating any of the files.
| Parameter | Description |
|---|---|
| aSizeThreshold | The threshold number of bytes for the binary data, above which the binary data is stored in a file. |
| aPath | The path identifying the location in which the files are created. This must not be greater than 240 characters long or the function leaves with KErrArgument. If it doesn't end in a slash, then one is appended. |
Returns: The number of files created.
Saves all binary property values larger than a specified threshold to files, and sets each property value to be a URI representing the file rather than the binary data iself.
The files are created in the folder identified by aPath, and are assigned unique filenames that consist of the property name and some random numbers.
Each new URI property value is prefixed with file:// and contains the path and filename of the file created.
If a vCard contains any agent property values and if they contain binary data whose size exceeds the threshold, these property values are replaced with URI property values.
The function uses the file server session supplied, which is needed to create the files. It leaves if there is a problem creating any of the files.
| Parameter | Description |
|---|---|
| aSizeThreshold | The threshold number of bytes for the binary data, above which the binary data is stored in a file. |
| aPath | The path identifying the location in which the files are created. This must not be greater than 240 characters long or the function leaves with KErrArgument. If it doesn't end in a slash, then one is appended. |
| aFileSession | The file server session used to create the files. |
Returns: The number of files created.
| IMPORT_C void | SetAutoDetect | ( | TBool | aOn, |
| const CArrayFix< CCnvCharacterSetConverter::SCharacterSet > * | aAutoDetectCharSets = NULL | |||
| ) | ||||
Turns auto detection of character sets on or off.
If a property does not specify a character set, then it is possible to guess its character set. This function turns this behaviour on or off. When the behaviour is on, it also lets the caller specify a restricted set of character sets to be considered.
Auto-detection of character sets is used (if auto detection is on) when converting a property value to Unicode while internalising a stream.
| Parameter | Description |
|---|---|
| aOn | If ETrue, auto detection is turned on; if EFalse (the default value), auto detection is turned off |
| aAutoDetectCharSets | If specified then auto detection will only consider the character sets listed. If NULL, all available character sets are considered. |
| IMPORT_C void | SetCharacterConverter | ( | Versit::TEncodingAndCharset & | encodingAndCharset | ) |
Sets a character converter suitable for converting strings between Unicode and the specified character set.
The function finds a suitable converter for the character set specified in aEncodingAndCharset.iCharSetId, if one is available, and assigns it to aEncodingAndCharset.iConverter.
If there is no converter available for the specified character set then iConverter is set to NULL.
This function is only of use if executing a major change to the externalisation behaviour, particularly if overriding CParserProperty::ExternalizeL() - the function from which this function is called.
| Parameter | Description |
|---|---|
| encodingAndCharset | A utility class from which the character set information is extracted (from its member iCharSetId) and to which the suitable character converter is set (to its member iConverter). |
| IMPORT_C void | SetDefaultCharSet | ( | const Versit::TVersitCharSet | aCharSet | ) |
Sets the default character set or transformation format.
This may be used to represent property values in Versit objects.
| Parameter | Description |
|---|---|
| aCharSet | The default character set. |
| IMPORT_C void | SetDefaultEncoding | ( | const Versit::TVersitEncoding | aEncoding | ) |
Sets the parser's default encoding to aEncoding.
| Parameter | Description |
|---|---|
| aEncoding | An encoding. Cannot be 8-bit. |
| IMPORT_C void | SetEntityNameL | ( | const TDesC & | aEntityName | ) |
Sets the name for the current entity to one of: VCARD, VCALENDAR, VEVENT or VTODO.
| Parameter | Description |
|---|---|
| aEntityName | The new name for the current parser entity. Any existing name is first deleted. |
| IMPORT_C void | SetLineCharacterSet | ( | Versit::TVersitCharSet | aLineCharSet | ) | [protected] |
| IMPORT_C void | SetLineCoding | ( | Versit::TVersitCharSet | aLineCharSet, |
| Versit::TVersitEncoding | aLineEncoding | |||
| ) | [protected] | |||
| IMPORT_C void | SetLineEncoding | ( | Versit::TVersitEncoding | aLineEncoding | ) | [protected] |
| void | SetObserver | ( | MVersitObserver * | aObserver | ) | [inline] |
Sets the Versit observer.
| Parameter | Description |
|---|---|
| aObserver | A pointer to the observer. |
| void | SetPlugIn | ( | MVersitPlugIn * | aPlugIn | ) | [inline] |
Sets the Versit plug-in.
If there is one, the Versit plug-in needs to be set before any properties are added to the parser. This is done for you when internalising (using InternalizeL()) or adding properties (using AddPropertyL()).
| Parameter | Description |
|---|---|
| aPlugIn | A pointer to the plug in. |
Converts a string into an integer, for example, it converts "438" to 438.
| Parameter | Description |
|---|---|
| aString | The string to be converted. Every character contained in the string needs to be number presentable, i.e. between '0' and '9'. |
| aNumber | On return, the integer corresponding to aString. |
Returns: KErrNone if the number has been converted from the string; KVersitErrNumberExpected otherwise.