SenXmlUtils Class Reference

#include <mw/SenXmlUtils.h>

Link against: SenXML.dll

class SenXmlUtils

Public Member Functions
IMPORT_C const TDesC8 &	AddAttributeL(CSenElement &, const TDesC8 &, const TDesC8 &, const TDesC8 &)
IMPORT_C const TDesC8 &	AddAttributeL(CSenElement &, const TDesC8 &, const TDesC8 &)
IMPORT_C const TDesC8 &	AddAttributeL(CSenElement &, CSenBaseAttribute *)
IMPORT_C HBufC8 *	AllocAttrValueL(const RAttributeArray &, const TDesC8 &)
IMPORT_C TPtrC8	AttrValue(const RAttributeArray &, const TDesC8 &)
IMPORT_C void	BuildQNameL(const TDesC8 &, const TDesC8 &, HBufC8 *&)
IMPORT_C TBool	DecodeHttpCharactersL(const TDesC8 &, HBufC8 *&)
IMPORT_C HBufC8 *	DecodeHttpCharactersLC(const TDesC8 &)
IMPORT_C TBool	EncodeHttpCharactersL(const TDesC8 &, HBufC8 *&)
IMPORT_C HBufC8 *	EncodeHttpCharactersLC(const TDesC8 &)
IMPORT_C TBool	EndsWith(const TDesC8 &, const TDesC8 &)
void	LeaveOnInvalidElementNameL(const TDesC8 &)
IMPORT_C void	LeaveOnXmlEscapesL(const TDesC8 &)
IMPORT_C TPtrC8	LocalName(const TDesC8 &)
IMPORT_C TPtrC8	NsPrefix(const TDesC8 &)
IMPORT_C CSenBaseAttribute *	RemoveAttributeL(CSenElement &, const TDesC8 &)
IMPORT_C CSenBaseAttribute *	RemoveAttributeL(CSenElement &, CSenBaseAttribute *)
IMPORT_C TBool	StartsWith(const TDesC8 &, const TDesC8 &)
IMPORT_C HBufC16 *	ToUnicodeLC(const TDesC8 &)
IMPORT_C HBufC8 *	ToUtf8LC(const TDesC16 &)

Detailed Description

This class offers a set of utility functions for XML data The helper methods include Unicode (UCS2) and UTF-8 encoding and decoding as well as convenience methods to encode and decode the five basic XML entities. There are functions for extracting XML prefixes and building of qualifiedname and a functionality for checking if an element name value is illegal or not.

Since: Series60 3.0

Member Function Documentation

AddAttributeL ( CSenElement &, const TDesC8 &, const TDesC8 &, const TDesC8 & )

IMPORT_C const TDesC8 &	AddAttributeL	(	CSenElement &	aElement,
			const TDesC8 &	aQName,
			const TDesC8 &	aLocalName,
			const TDesC8 &	aValue
		)	[static]

Adds an attribute into this element. Used also adding new namespaces into the element.

Parameter	Description
aQName	Attribute's qualified name
aLocalName	Attribute's local name
aValue	Attribute's value

Returns: value of the attribute as string (TDesC&) Leave codes: KErrSenInvalidCharacters if aLocalName or aQName contain illegal characters. KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.

AddAttributeL ( CSenElement &, const TDesC8 &, const TDesC8 & )

IMPORT_C const TDesC8 &	AddAttributeL	(	CSenElement &	aElement,
			const TDesC8 &	aAttrName,
			const TDesC8 &	aValue
		)	[static]

Adds an attribute into this element. Used also adding new namespaces into the element.

Parameter	Description
aValue	Attribute's value

Returns: value of the attribute as string (TDesC&) Leave codes: KErrSenInvalidCharacters if aLocalName contains illegal characters. KErrSenZeroLengthDescriptor if aAttrName is zero length, or if the local name part of it is zero length.

AddAttributeL ( CSenElement &, CSenBaseAttribute * )

IMPORT_C const TDesC8 &	AddAttributeL	(	CSenElement &	aElement,
			CSenBaseAttribute *	apAttribute
		)	[static]

Adds an attribute into this element.

Parameter	Description
apAttribute	Attribute to be added. Ownership is transferred to this element.

Returns: attribute value as a string (TDesC8&)

AllocAttrValueL ( const RAttributeArray &, const TDesC8 & )

IMPORT_C HBufC8 *	AllocAttrValueL	(	const RAttributeArray &	apAttrs,
			const TDesC8 &	aAttrName
		)	[static]

Get a newly allocated copy of the attribute.

Since: Series60 3.0

Parameter	Description
apAttrs	Array which contains the attributes.
aAttrName	The name of the attribute which value is asked.

Returns: A buffer containing the value of the wanted attribute. Buffer is newly allocated and ownership is transferred to the caller. Can be NULL if attribute was not found.

AttrValue ( const RAttributeArray &, const TDesC8 & )

IMPORT_C TPtrC8	AttrValue	(	const RAttributeArray &	aAttributes,
			const TDesC8 &	aAttrName
		)	[static]

Helper function to find a value of a given attribute.

Since: Series60 3.0

Parameter	Description
aAttributes	Array which contains the attributes.
aAttrName	The name of the attribute which value is asked.

Returns: The value of the wanted attribute, or KNullDesC8 if given attribute name was not found.

BuildQNameL ( const TDesC8 &, const TDesC8 &, HBufC8 *& )

IMPORT_C void	BuildQNameL	(	const TDesC8 &	aPrefix,
			const TDesC8 &	aLocalName,
			HBufC8 *&	aQName
		)	[static]

Helper function to construct a qualified name.

Since: Series60 3.0

Parameter	Description
aPrefix	the prefix to be used.
aLocalName	the local name to be used.
aQName	a ref-to-pointer which will contain the allocated qualified name. This param should be NULL when passed, otherwise memory leak will occur. Caller has the ownership of this buffer.

DecodeHttpCharactersL ( const TDesC8 &, HBufC8 *& )

IMPORT_C TBool	DecodeHttpCharactersL	(	const TDesC8 &	aOriginal,
			HBufC8 *&	aDecoded
		)	[static]

Method to provide functionality for decoding HTTP characters into XML escaping characters.

Since: Series60 3.0

DecodeHttpCharactersL() returns ETrue, if any XML escaping (some Basic Entity) character-sequence was decoded.

Note that aDecoded points to a copy of the original string even if there were no basic entities to decode. Otherwise, it points to a newly allocated descriptor, where some basic entity or entities has been decoded (replaced) from aOriginal descriptor.

Parameter	Description
aOriginal	the string to be decoded.
aDecoded	the buffer that will contain the decoded string on return. Caller has the ownership of this. Will be similar as aOriginal if nothing was replaced.

Returns: ETrue if any XML escaping (some Basic Entity) character-sequence was decoded.

DecodeHttpCharactersLC ( const TDesC8 & )

IMPORT_C HBufC8 *

DecodeHttpCharactersLC

(

const TDesC8 &

aOriginal

)

[static]

Same as DecodeHttpCharactersL(), but the decoded string OR exact copy of the aOriginal descriptor is returned and pushed to cleanup stack.

Since: Series60 3.0

In Symbian OS v9.1, see Location: EscapeUtils.h Link against: inetprotutil.lib

Parameter	Description
aOriginal	the string to be decoded.

Returns: buffer located in the cleanup stack containing the decoded string

EncodeHttpCharactersL ( const TDesC8 &, HBufC8 *& )

IMPORT_C TBool	EncodeHttpCharactersL	(	const TDesC8 &	aOriginal,
			HBufC8 *&	aEncoded
		)	[static]

Encodes XML-escaping characters found from aOriginal to XML Basic Entities. Note, that aEncoded is not re-assigned IF there were NO XML-escaping characters - '&', ''', '"', '<' or '>' -found. Otherwise, when encoding has been done, the aEncoded points to newly allocated descriptor, which ownership belongs to the caller (who should have given aEncoded pointer as NULL in any case).

Since: Series60 3.0

Parameter	Description
aOriginal	the original descriptor.
aEncoded	a ref-to-pointer which will contain the allocated encoded string. This param should be NULL when passed, otherwise memory leak will occur. Caller has the ownership of this buffer.

EncodeHttpCharactersLC ( const TDesC8 & )

IMPORT_C HBufC8 *

EncodeHttpCharactersLC

(

const TDesC8 &

aOriginal

)

[static]

Encodes XML-escaping characters found from aOriginal to XML Basic Entities. Example: '&' -> '&' Note! Function returns a copy of aOriginal descriptor, even if not a single illegal, XML-escaping character was encoded. The returned pointer to heap allocated descriptor is pushed to the cleanup stack.

Since: Series60 3.0

Parameter	Description
aOriginal	the string to be encoded.

Returns: a buffer containing the encoded string. Ownership is transferred to the caller.

EndsWith ( const TDesC8 &, const TDesC8 & )

IMPORT_C TBool	EndsWith	(	const TDesC8 &	aDes,
			const TDesC8 &	aPostfix
		)	[static]

Helper function to determine if a string ends with another string.

Since: Series60 3.0

Parameter	Description
aDes	string to be searched from.

Returns: ETrue if given string ends with given prefix, otherwise EFalse.

LeaveOnInvalidElementNameL ( const TDesC8 & )

void

LeaveOnInvalidElementNameL

(

const TDesC8 &

aCandidate

)

[static]

Method leaves if aCandidate contains illegal, XML-escaping characters or is an empty descriptor. Those characters, which will cause a leave are: '&', ''', '"', '<' and '>'

Since: Series60 3.0

Parameter	Description
aCandidate	string to be checked. Leave codes: KErrSenInvalidCharacters if contains invalid characters. KErrSenZeroLengthDescriptor if aCandidate is zero length

LeaveOnXmlEscapesL ( const TDesC8 & )

IMPORT_C void

LeaveOnXmlEscapesL

(

const TDesC8 &

aCandidate

)

[static]

Method leaves if aCandidate contains illegal, XML-escaping characters. Those characters, which will cause a leave are: '&', ''', '"', '<' and '>'

Since: Series60 3.0

Parameter	Description
aCandidate	string to be checked. Leave codes: KErrSenInvalidCharacters if contains invalid characters.

LocalName ( const TDesC8 & )

IMPORT_C TPtrC8

LocalName

(

const TDesC8 &

aQName

)

[static]

Helper function to get a local name from a qualified name.

Since: Series60 3.0

Parameter	Description
aQName	the qualified name

Returns: the local name for the element, e.g. 'Body' for 'soap:Body'.

NsPrefix ( const TDesC8 & )

IMPORT_C TPtrC8

NsPrefix

(

const TDesC8 &

aQName

)

[static]

Helper function to get a prefix from a qualified name.

Since: Series60 3.0

Parameter	Description
aQName	the qualified name

Returns: the namespace prefix for the element, e.g. 'soap' for 'soap:Body'. The returned pointer is empty if there is no prefix.

RemoveAttributeL ( CSenElement &, const TDesC8 & )

IMPORT_C CSenBaseAttribute *	RemoveAttributeL	(	CSenElement &	aElement,
			const TDesC8 &	aAttrName
		)	[static]

Removes certain attribute from given element. May also be used when removing namespaces from the element.

Parameter	Description
aElement	Element from which attribute will be removed.
aAttrName	Attribute's local name

Returns: pointer to removed attribute, which ownership is transferred to caller or NULL, if no matching attribute was found from this element.

RemoveAttributeL ( CSenElement &, CSenBaseAttribute * )

IMPORT_C CSenBaseAttribute *	RemoveAttributeL	(	CSenElement &	aElement,
			CSenBaseAttribute *	apAttribute
		)	[static]

Removes attribute from this element.

Parameter	Description
aElement	Element from which attribute will be removed.
apAttribute	is the attribute to be removed. transferred to this element.

Returns: pointer to removed attribute, which ownership is transferred to caller or NULL, if no matching attribute was found from this element.

StartsWith ( const TDesC8 &, const TDesC8 & )

IMPORT_C TBool	StartsWith	(	const TDesC8 &	aDes,
			const TDesC8 &	aPrefix
		)	[static]

Helper function to determine if a string starts with another string.

Since: Series60 3.0

Parameter	Description
aDes	string to be searched from.
aPrefix	the prefix to be searched.

Returns: ETrue if given string starts with given prefix, otherwise EFalse.

ToUnicodeLC ( const TDesC8 & )

IMPORT_C HBufC16 *

ToUnicodeLC

(

const TDesC8 &

aUtf8String

)

[static]

Helper function to convert UTF-8 string to unicode encoded.

Since: Series60 3.0

Parameter	Description
aUtf8String	string to be converted.

Returns: buffer as unicode, caller takes ownership.

ToUtf8LC ( const TDesC16 & )

IMPORT_C HBufC8 *

ToUtf8LC

(

const TDesC16 &

aUnicodeString

)

[static]

Helper function to convert unicode string to UTF-8 encoded.

Since: Series60 3.0

Parameter	Description
aUnicodeString	string to be converted.

Returns: buffer as UTF-8, caller takes ownership.