Class CParserProperty

class CParserProperty : public CBase;

Description

A vCard or vCalendar property.

A property consists of a name, an optional value and one or more optional parameters.

The name, value and parameters are initialised on construction.

Versit properties have the general form:

Property Name (; Property Parameter Name(=Property Parameter Value)* : Property Value)

where items in brackets are optional and * indicates that the item may be repeated.

For instance, TEL; HOME; ENCODING=QUOTED-PRINTABLE; CHARSET=US-ASCII : 01234 567890

Here, TEL is the property name; HOME, ENCODING and CHARSET are property parameter names; QUOTED-PRINTABLE and US-ASCII are property parameter values. The component following the colon is the property value.

Properties also have a name UID, which set during internalisation of a property and used only during internalisation. It is set by SetNameUid() and is used to allow number comparisons during internalisation. This provides a faster alternative to string comparisons when checking a property to see if it is a significant one (e.g. a begin or binary property). This is the only use of the name UID: it is not used during externalisation of a property.

Note that grouped properties are supported by the derived class, CParserGroupedProperty. The vCalender parser does not have property groups, and so stores all properties using this base class, whereas the vCard parser stores all properties using CParserGroupedProperty.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CParserProperty - A vCard or vCalendar property

Members

Defined in CParserProperty:
AddParamL(), CParserProperty(), CParserProperty(), ConstructSelfL(), DeleteParam(), ExternalizeL(), LoadBinaryValuesFromFilesL(), Name(), NameUid(), NewL(), Param(), ParamArray(), Reserved(), SaveBinaryValuesToFilesL(), SetNameL(), SetNameUid(), SetParamArray(), SetValue(), SupportsInterface(), Uid(), Value(), iArrayOfParams, iPropertyName, iPropertyNameUid, iPropertyValue, ~CParserProperty()

Inherited from CBase:
Delete(), Extension_(), operator new()

static IMPORT_C CParserProperty *NewL(CParserPropertyValue &aPropertyValue, const TDesC8 &aName, CArrayPtr< CParserParam > *aArrayOfParams);

Description

Allocates and constructs a new vCalendar or vCard property with the property value, property name and array of property parameters specified.

Takes ownership of aPropertyValue and aArrayOfParams.

Parameters

CParserPropertyValue &aPropertyValue The property value. const TDesC8 &aName The property name. CArrayPtr< CParserParam > *aArrayOfParams Pointer to the property parameters.

Return value

CParserProperty * Pointer to the newly created property.

IMPORT_C CParserProperty(CArrayPtr< CParserParam > *aArrayOfParams);

Description

C++ constructor which sets the array of property parameters only.

The property takes ownership of the array of parameters.

Parameters

CArrayPtr< CParserParam > *aArrayOfParams Pointer to the property parameters.

IMPORT_C ~CParserProperty();

Description

Frees all resources owned by the property, prior to its destruction.

protected: IMPORT_C CParserProperty(CParserPropertyValue &aPropertyValue, CArrayPtr< CParserParam > *aArrayOfParams);

Description

Parameters

CParserPropertyValue &aPropertyValue CArrayPtr< CParserParam > *aArrayOfParams

virtual IMPORT_C void ExternalizeL(RWriteStream &aStream, CVersitParser *aVersitParser=0);

Description

Externalises a property.

The property has the general format:

<NAME>;<PARAMNAME=PARAMVALUE>:<VALUE>

Checks the property value, and Versit's default encoding and character set, to decide what encoding, if any, and character set should be applied to the property value.

If the encoding is not the default, (no encoding), then a parameter (with the name KVersitTokenENCODING) is added to the property to specify the encoding used. Similarly, if the character set used is not the default, (Ascii), then a parameter (with the name KVersitTokenCHARSET) is added to the property to specify the character set used.

A parser parameter needs to be supplied when calling this function: if NULL is passed then a panic is raised.

The name is externalised by this function directly. The parameters (if there are any) are externalised using CParserParam::ExternalizeL(). The value (if there is one) is externalised using the ExternalizeL() function of the appropriate property value class.

Using the encoding format and character set selected for the property value, the function forms a Versit specific UID (Versit::TEncodingAndCharset). When the property value is externalised, this UID is passed to the property value class' ExternalizeL() function, so that it knows which character set and encoding format to use.

Also passed to the ExternalizeL() function of the property value class are the output stream and the 'output length'. The output stream is the same as is passed to this function. The 'output length' refers to the amount of data that has been output to the current line in the stream. This is kept track of while the property name and parameters are externalised, and then passed to the ExternalizeL() function of the property value class to make sure the line length does not exceed the maximum length allowed.

As well as inserting the semi-colon and colon between the name and parameter(s) and parameter(s) and value, a CRLF is written at the end.

Parameters

RWriteStream &aStream Stream to which the value is to be externalised. CVersitParser *aVersitParser The Versit parser whose ExternalizeL() function calls this function, and in whose array of properties this instance of CParserProperty is held.

IMPORT_C CParserParam *Param(const TDesC8 &aParamName) const;

Description

Gets a pointer to the property parameter with the specified name.

If the property has more than one parameter with the same name, the function returns the one nearest the start of the array, but there should never be more than one of each possible parameter.

Parameters

const TDesC8 &aParamName The name of the parameter to search for.

Return value

CParserParam * Pointer to a property parameter. NULL if the parameter name specified is not found in the array.

IMPORT_C void AddParamL(CParserParam *aParam);

Description

Adds a property parameter to the property.

Any existing parameter with the same name is replaced. The parameter is appended to the property's parameter array. If no property parameter array has been allocated, the function will first allocate one.

Parameters

CParserParam *aParam Pointer to a generic property parameter, consisting of a name and optionally a value, both specified as descriptors. The property takes ownership of the new parameter.

IMPORT_C void DeleteParam(TDesC8 &aParamName);

Description

Deletes the specified property parameter from the property's array of parameters, if it exists in the array.

If the property has more than one parameter with the same name, the function deletes the one nearest the start of the array, but there should never be more than one of each possible parameter.

Parameters

TDesC8 &aParamName The name of the parameter to delete.

IMPORT_C void SetNameL(const TDesC8 &aName);

Description

Sets the property name.

If a name has already been set, this function will replace it.

This function allocates and constructs a new heap descriptor and initialises it using the content of aName, so can leave if insufficient memory is available.

Parameters

const TDesC8 &aName The new property name. Property names are defined in vtoken.h.

virtual IMPORT_C TBool SupportsInterface(const TUid &) const;

Description

Tests whether the property value supports the specified interface.

This implementation returns EFalse.

Parameters

const TUid &

Return value

TBool EFalse.

IMPORT_C TPtrC8 Name() const;

Description

Gets the property name.

If no name has been set, the function returns an empty descriptor.

Return value

TPtrC8 The property name.

inline void SetValue(CParserPropertyValue *aPropertyValue);

Description

Sets the property value.

The property takes ownership of the property value.

Parameters

CParserPropertyValue *aPropertyValue A pointer to the property value to be set.

inline CParserPropertyValue *Value() const;

Description

Gets a pointer to the property value.

Ownership of the property value is not transferred by this function.

Return value

CParserPropertyValue * Pointer to generic parser property value.

inline TUid Uid() const;

Description

Gets the UID of the property value.

Return value

TUid UID of the property value.

inline void SetNameUid(TUid aUid);

Description

Sets a property name UID.

This function is called by CVersitParser::AddProperty() when internalising, and will not normally be used directly.

Parameters

TUid aUid A property name UID.

inline TUid NameUid() const;

Description

Gets the property name UID.

Return value

TUid UID of the property name.

inline void SetParamArray(CArrayPtr< CParserParam > *aArrayOfParams);

Description

Sets the array of property parameters.

The property takes ownership of aArrayOfParams

Parameters

CArrayPtr< CParserParam > *aArrayOfParams Array of property parameters.

IMPORT_C TBool LoadBinaryValuesFromFilesL(RFs &aFileSession);

Description

If the property value is a URI, this function loads the file represented by the URI and sets the binary data it contains to be the property value, instead of the URI.

If the property value is not a URI, the function just returns EFalse.

The function also operates on any agents in a 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.

This function is used by CVersitParser::LoadBinaryValuesFromFilesL().

Parameters

RFs &aFileSession The file server session used to open the files.

Return value

TBool ETrue if the property value is a URI, EFalse if not.

IMPORT_C TBool SaveBinaryValuesToFilesL(TInt aSizeThreshold, const TDesC &aPath, RFs &aFileSession);

Description

If the property value is binary and is larger than the specified threshold, this function saves the binary data to a file and sets the property value to be a URI representing the file rather than the binary data iself.

If the property value is not binary, or if it is binary, but is smaller than the threshold, the function just returns EFalse.

The file is created in the folder identified by aPath, and is assigned a unique filename that consists of the property name and some random numbers.

The new URI property value is prefixed with file:// and contains the path and filename of the file created.

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.

This function is used by CVersitParser::SaveBinaryValuesToFilesL().

Parameters

TInt aSizeThreshold The threshold number of bytes for the binary data, above which a file is created and the binary data is stored in it. const TDesC &aPath The path identifying the location in which the file is created. 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. RFs &aFileSession The file server session used to create the files.

Return value

TBool ETrue if the property value is binary and its size is greater than the threshold. EFalse if not.

protected: static IMPORT_C void ConstructSelfL(CParserProperty &aSelf, const TDesC8 &aName);

Description

Parameters

CParserProperty &aSelf const TDesC8 &aName

IMPORT_C CArrayPtr< CParserParam > *ParamArray() const;

Description

Returns a pointer to the array of property parameters.

Return value

CArrayPtr< CParserParam > * Pointer to array of property parameters. NULL if the property is not having any parameters.

private: virtual IMPORT_C void Reserved();

Description

protected: CParserPropertyValue * iPropertyValue;

Description

protected: HBufC8 * iPropertyName;

Description

protected: TUid iPropertyNameUid;

Description

protected: CArrayPtr< CParserParam > * iArrayOfParams;

Description