EPOC   SDK Home Glossary Indexes Previous Next Up

CVersitParser class


Contents


CVersitParser class — Base versit parser class

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

CBase

Abstract: CBase behaviour.

Defined in

versit.h

Link against

versit.lib

Description

The base class for versit parsers. It provides functions to parse data contained in a stream into a versit object, as well as the ability to add properties and sub-entities to an existing object. The key functions are ExternalizeL() and InternalizeL() which are used to convert an entity to and from stream form. These are the only functions which most users of this class will need to use.

Concrete classes derived from this class are CParserVCard, CParserVCal and CParserVCalEntity.

Although this is not an abstract class, in practice, you would create and use objects of one of the derived classes instead.


Stream persistence


ExternalizeL() — Externalize to a stream

void ExternalizeL(RWriteStream& aStream);

Description

Use this function to externalize an entity to a write stream. Any sub-entities will in turn be externalized. The presence of this function means that the standard templated operator<<() (defined in s32strm.h) is available to externalize objects of this class.

Arguments

RWriteStream& aStream

Stream to which the entity should be externalized.


ExternalizeL() — Externalize to a file

void ExternalizeL(RFile& aOutputFile);

Description

Use this function to externalize an entity to a file. Any sub-entities will in turn be externalized.

Arguments

RFile& aOutputFile

The file to which to write the entity.


InternalizeL() — Internalize from a stream

void InternalizeL(RReadStream& aStream);

Description

Use this function to internalize an entity from a read stream. Any sub-entities will in turn be internalized. The presence of this function means that the standard templated operator>>() (defined in s32strm.h) is available to internalize objects of this class.

Arguments

RReadStream& aStream

Stream from which the entity should be internalized.


InternalizeL() — Internalize from a file

void InternalizeL(RFile& aInputFile,TInt& aBytesThroughFile);

Description

Use this function to internalize the entity from a file. Any sub-entities will also be internalized.

aBytesThroughFile is the file position at which reading should start. On return, it is updated to mark the file position of the last byte read from the file.

Arguments

RFile& aInputFile

The file from which to internalize the entity.

TInt& 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.

Leave considerations

The file position specified should not be beyond the end of the file, otherwise the function will leave with KErrEof.


Entities


AddEntityL() — Add an entity

void AddEntityL(CVersitParser* aEntity);

Description

Adds a sub-entity to the current entity. This function may be used when building up a versit parser object from a client application.

Arguments

CVersitParser* aEntity

Pointer to the sub-entity to add.


ArrayOfEntities() — Get array of entities

CArrayPtr<CVersitParser>* ArrayOfEntities(TBool aTakeOwnership);

Description

This function retrieves the current entity's array of sub-entities. The current entity may be a top level entity, or may itself be a sub-entity. If aTakeOwnership is true, the array of sub-entities owned by the current entity is then set to NULL so that the code which calls this function takes ownership of the array.

Arguments

TBool aTakeOwnership

If ETrue, the calling code takes ownership of the array. If EFalse, ownership remains with the parser.

Return value

CArrayPtr<CVersitParser>*

Array of pointers to the current entity's array of sub-entities.


EntityL() — Retrieve specific entities

CArrayPtr<CVersitParser>* EntityL(const TDesC& aEntityName,TBool aTakeOwnership);

Description

Retrieves all sub-entities in the current entity, whose name matches the name specified.

Arguments

const TDesC& aEntityName

The sub-entity name of interest. All sub-entities which match this name are returned in the array of pointers.

TBool aTakeOwnership

If ETrue, the calling code takes ownership of each matching sub-entity (the sub-entity in the array owned by the current entity is set to NULL). If EFalse, ownership remains with the current entity.

Return value

CArrayPtr<CVersitParser>*

An array of pointers to all sub-entities with the specified name property.


SetEntityNameL() — Set the entity name

void SetEntityNameL(const TDesC& aEntityName);

Description

Sets the name for the current entity to one of: — VCARD, VCALENDAR, VEVENT or VTODO.

Arguments

const TDesC& aEntityName

The new name for the current parser entity. Any existing name is first deleted.

Leave considerations

The function allocates memory for the new entity name on the heap, so the function can leave if there is insufficient memory available.


EntityName() — Get the entity name

TPtrC EntityName() const;

Description

Retrieves the current entity's name. If no name has been set, returns an empty descriptor.

Return value

TPtrC

The current entity's name.


Properties


AddPropertyL() — Add a property

void AddPropertyL(CParserProperty* aProperty,TBool aInternalizing);

Description

Appends a property to the current entity's list of properties. This function may be used when building up a versit parser object from a client application.

Arguments

CParserProperty* aProperty

Pointer to the property to add to the entity.

If NULL, the function will have no effect.

TBool aInternalizing

This parameter is used to distinguish between reading an entity in from a stream or file (i.e. importing), 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 app, or synchronizing), in which case, the argument should have a value of EFalse.


ArrayOfProperties() — Get array of properties

CArrayPtr<CParserProperty>* ArrayOfProperties(TBool aTakeOwnership);

Description

This function retrieves the current entity’s array of properties. If aTakeOwnership is true, the entity’s array of properties is then set to NULL so that the code which calls this function takes ownership of the array.

Arguments

TBool aTakeOwnership

If ETrue, the calling code takes ownership of the array. If EFalse, ownership remains with the entity.

Return value

CArrayPtr<CParserProperty>*

Array of pointers to the entity’s properties.


PropertyL() — Retrieve specific properties

CArrayPtr<CParserProperty>* PropertyL(const TDesC& aPropertyName,const TUid& aPropertyUid,TBool aTakeOwnership);

Description

Retrieves all properties in the current entity's list of properties whose name and value match the name and value specified.

Arguments

const TDesC& aPropertyName

The property name of interest. Property names are defined in file vtoken.h.

const TUid& aPropertyUid

The property value of interest. See the property UID values defined in file vuid.h.

TBool aTakeOwnership

If ETrue, the calling code takes ownership of each matching property (the property in the entity’s array is set to NULL). If EFalse, ownership remains with the entity.

Return value

CArrayPtr<CParserProperty>*

An array of pointers to all properties with the name and value specified.


ConvertAllPropertyDateTimesToMachineLocalL() — Convert all date/time property values to machine local

void ConvertAllPropertyDateTimesToMachineLocalL(const TTimeIntervalSeconds& aIncrement,const CVersitDaylight* aDaylight);

Description

The function is used to convert all date/time property values contained in the current entity's array of properties into machine local values.

It does this first by converting all date/times into universal time, by adding aIncrement and subtracting the daylight saving offset specified in aDaylight (if applicable). Then, these universal time values are converted into machine local times by adding the universal time offset for the machine's locale.

Note that time conversion is taken care of by the InternalizeL() and ExternalizeL() functions.

Arguments

const TTimeIntervalSeconds& aIncrement

A time interval in seconds to add to the date/time.

const CVersitDaylight* aDaylight

The specification for daylight saving. If a date/time value is within the period for daylight saving, the date/time is modified by the daylight saving offset.


Validation


IsValidLabel() — Validate property name

TBool IsValidLabel(const TDesC& aLabel, TInt& aPos);

Description

Tests whether a property name is valid.

Arguments

const TDesC& aLabel

The property name to test.

TInt& aPos

On return, contains the character position within the property name of the first invalid character found.

Return value

TBool

ETrue if valid, EFalse if invalid.

Notes

The property name is invalid if it contains any of the following characters: —


IsValidParameterValue() — Validate property parameter name / value

TBool IsValidParameterValue(TInt& aPos,const TDesC& aParamValue) const;

Description

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: —

Arguments

TInt& aPos

On return, contains the character position of the first invalid character in the property parameter name or value.

const TDesC& aParamValue

The property parameter name or value to test.

Return value

TBool

ETrue if valid, EFalse if invalid.


Enumerations


TCharCodes enum — Character codes

ESpace

Space.

EHTab

Horizontal tab.

ELineFeed

Line feed.

ECarriageReturn

Carriage return.

EPOC       SDK Home Glossary Indexes Previous Next Up