Collapse all Symbian^3 Application Developer Library

CParserProperty Class Reference

class CParserProperty : public CBase

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 .

Inherits from

CParserProperty
- CBase

Public Member Functions
	CParserProperty ( CArrayPtr < CParserParam > *)
	~CParserProperty ()
IMPORT_C void	AddParamL ( CParserParam *)
IMPORT_C void	DeleteParam ( TDesC8 &)
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 *)
IMPORT_C TBool	SupportsInterface (const TUid &)
TUid	Uid ()
CParserPropertyValue *	Value ()

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

Private Member Functions
void	GenerateNameAndCreateFileL ( RFs &, TPtr8 , RFile &, TDes &)
HBufC8 *&	NameBuf ()
void	ReadBinaryDataL (const CBufSeg , HBufC8 *)
IMPORT_C void	Reserved ()

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

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

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.

Parameters

CArrayPtr < CParserParam > * aArrayOfParams

Pointer to the property parameters.

CParserProperty(CParserPropertyValue &, CArrayPtr< CParserParam > *)

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

Parameters

CParserPropertyValue & aPropertyValue
CArrayPtr < CParserParam > * aArrayOfParams

~CParserProperty()

IMPORT_C

~CParserProperty

(

)

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

Member Functions 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.

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.

ConstructSelfL(CParserProperty &, const TDesC8 &)

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

Parameters

CParserProperty & aSelf
const TDesC8 & aName

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.

Parameters

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

Parameters

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

GenerateNameAndCreateFileL(RFs &, TPtr8, RFile &, TDes &)

void	GenerateNameAndCreateFileL	(	RFs &	aFileSession,
			TPtr8	aPropertyName,
			RFile &	aFile,
			TDes &	aFileName
		)	[private]

Parameters

RFs & aFileSession
TPtr8 aPropertyName
RFile & aFile
TDes & aFileName

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

Parameters

RFs & aFileSession

The file server session used to open the files.

Name()

IMPORT_C TPtrC8

Name

(

)

const

Gets the property name.

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

NameBuf()

HBufC8 *&

NameBuf

(

)

[private, inline]

NameUid()

TUid

NameUid

(

)

const [inline]

Gets the property name UID.

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.

Parameters

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

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.

Parameters

const TDesC8 & aParamName

The name of the parameter to search for.

ParamArray()

IMPORT_C CArrayPtr < CParserParam > *

ParamArray

(

)

const

Returns a pointer to the array of property parameters.

ReadBinaryDataL(const CBufSeg *, HBufC8 **)

void	ReadBinaryDataL	(	const CBufSeg *	aBufseg_ptr,
			HBufC8 **	aBuffer
		)	[private]

Parameters

const CBufSeg * aBufseg_ptr
HBufC8 ** aBuffer

Reserved()

IMPORT_C void

Reserved

(

)

[private, virtual]

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

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.

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.

Parameters

const TDesC8 & 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.

Parameters

TUid 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

Parameters

CArrayPtr < CParserParam > * aArrayOfParams

Array of property parameters.

SetValue(CParserPropertyValue *)

void

SetValue

(

CParserPropertyValue *

aPropertyValue

)

[inline]

Sets the property value.

The property takes ownership of the property value.

Parameters

CParserPropertyValue * 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.

Parameters

const TUid &

Uid()

TUid

Uid

(

)

const [inline]

Gets the 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.

Member Data Documentation

CArrayPtr< CParserParam > * iArrayOfParams

CArrayPtr < CParserParam > *

iArrayOfParams

[protected]

HBufC8 * iPropertyName

HBufC8 *

iPropertyName

[protected]

TUid iPropertyNameUid

TUid

iPropertyNameUid

[protected]

CParserPropertyValue * iPropertyValue

CParserPropertyValue *

iPropertyValue

[protected]