CParserProperty Class Reference

#include <app/vprop.h>

Link against: versit.lib

class CParserProperty : public CBase

Inherits from

CParserProperty

Protected Attributes
CArrayPtr< CParserParam > *	iArrayOfParams
HBufC8 *	iPropertyName
TUid	iPropertyNameUid
CParserPropertyValue *	iPropertyValue

Public Member Functions
	CParserProperty(CArrayPtr< CParserParam > *)
	~CParserProperty()
IMPORT_C void	AddParamL(CParserParam *)
IMPORT_C void	DeleteParam(TDesC8 &)
virtual IMPORT_C void	ExternalizeL(RWriteStream &, CVersitParser *)
IMPORT_C TBool	LoadBinaryValuesFromFilesL(RFs &)
IMPORT_C TPtrC8	Name()
TUid	NameUid()
IMPORT_C CParserProperty *	NewL(CParserPropertyValue &, const TDesC8 &, CArrayPtr< CParserParam > *)
IMPORT_C CParserParam *	Param(const TDesC8 &)
IMPORT_C CArrayPtr< CParserParam > *	ParamArray()
IMPORT_C TBool	SaveBinaryValuesToFilesL(TInt, const TDesC &, RFs &)
IMPORT_C void	SetNameL(const TDesC8 &)
void	SetNameUid(TUid)
void	SetParamArray(CArrayPtr< CParserParam > *)
void	SetValue(CParserPropertyValue *)
virtual IMPORT_C TBool	SupportsInterface(const TUid &)
TUid	Uid()
CParserPropertyValue *	Value()

Protected Member Functions
	CParserProperty(CParserPropertyValue &, CArrayPtr< CParserParam > *)
IMPORT_C void	ConstructSelfL(CParserProperty &, const TDesC8 &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed 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.

Member Attribute Documentation

iArrayOfParams

CArrayPtr< CParserParam > *

iArrayOfParams

[protected]

iPropertyName

HBufC8 *

iPropertyName

[protected]

iPropertyNameUid

TUid

iPropertyNameUid

[protected]

iPropertyValue

CParserPropertyValue *

iPropertyValue

[protected]

Constructor & Destructor Documentation

CParserProperty ( CArrayPtr< CParserParam > * )

IMPORT_C

CParserProperty

(

CArrayPtr< CParserParam > *

aArrayOfParams

)

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

The property takes ownership of the array of parameters.

Parameter	Description
aArrayOfParams	Pointer to the property parameters.

CParserProperty ( CParserPropertyValue &, CArrayPtr< CParserParam > * )

IMPORT_C	CParserProperty	(	CParserPropertyValue &	aPropertyValue,
			CArrayPtr< CParserParam > *	aArrayOfParams
		)	[protected]

~CParserProperty ( )

IMPORT_C

~CParserProperty

(

)

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

Member Function Documentation

AddParamL ( CParserParam * )

IMPORT_C void

AddParamL

(

CParserParam *

aParam

)

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.

Parameter	Description
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.

ConstructSelfL ( CParserProperty &, const TDesC8 & )

IMPORT_C void	ConstructSelfL	(	CParserProperty &	aSelf,
			const TDesC8 &	aName
		)	[protected, static]

DeleteParam ( TDesC8 & )

IMPORT_C void

DeleteParam

(

TDesC8 &

aParamName

)

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.

Parameter	Description
aParamName	The name of the parameter to delete.

ExternalizeL ( RWriteStream &, CVersitParser * )

IMPORT_C void	ExternalizeL	(	RWriteStream &	aStream,
			CVersitParser *	aVersitParser = NULL
		)	[virtual]

Externalises a property.

The property has the general format:

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.

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

LoadBinaryValuesFromFilesL ( RFs & )

IMPORT_C TBool

LoadBinaryValuesFromFilesL

(

RFs &

aFileSession

)

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().

Parameter	Description
aFileSession	The file server session used to open the files.

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

Name ( )

IMPORT_C TPtrC8

Name

(

)

const

Gets the property name.

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

Returns: The property name.

NameUid ( )

TUid

NameUid

(

)

const [inline]

Gets the property name UID.

Returns: UID of the property name.

NewL ( CParserPropertyValue &, const TDesC8 &, CArrayPtr< CParserParam > * )

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

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.

Parameter	Description
aPropertyValue	The property value.
aName	The property name.
aArrayOfParams	Pointer to the property parameters.

Returns: Pointer to the newly created property.

Param ( const TDesC8 & )

IMPORT_C CParserParam *

Param

(

const TDesC8 &

aParamName

)

const

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.

Parameter	Description
aParamName	The name of the parameter to search for.

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

ParamArray ( )

IMPORT_C CArrayPtr< CParserParam > *

ParamArray

(

)

const

Returns a pointer to the array of property parameters.

Returns: Pointer to array of property parameters. NULL if the property is not having any parameters.

SaveBinaryValuesToFilesL ( TInt, const TDesC &, RFs & )

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

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().

Parameter	Description
aSizeThreshold	The threshold number of bytes for the binary data, above which a file is created and the binary data is stored in it.
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.
aFileSession	The file server session used to create the files.

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

SetNameL ( const TDesC8 & )

IMPORT_C void

SetNameL

(

const TDesC8 &

aName

)

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.

Parameter	Description
aName	The new property name. Property names are defined in vtoken.h.

SetNameUid ( TUid )

void

SetNameUid

(

TUid

aUid

)

[inline]

Sets a property name UID.

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

Parameter	Description
aUid	A property name UID.

SetParamArray ( CArrayPtr< CParserParam > * )

void

SetParamArray

(

CArrayPtr< CParserParam > *

aArrayOfParams

)

[inline]

Sets the array of property parameters.

The property takes ownership of aArrayOfParams

Parameter	Description
aArrayOfParams	Array of property parameters.

SetValue ( CParserPropertyValue * )

void

SetValue

(

CParserPropertyValue *

aPropertyValue

)

[inline]

Sets the property value.

The property takes ownership of the property value.

Parameter	Description
aPropertyValue	A pointer to the property value to be set.

SupportsInterface ( const TUid & )

IMPORT_C TBool

SupportsInterface

(

const TUid &

)

const [virtual]

Tests whether the property value supports the specified interface.

This implementation returns EFalse.

Returns: EFalse.

Uid ( )

TUid

Uid

(

)

const [inline]

Gets the UID of the property value.

Returns: UID of the property value.

Value ( )

CParserPropertyValue *

Value

(

)

const [inline]

Gets a pointer to the property value.

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

Returns: Pointer to generic parser property value.