SenXmlUtils Class Reference

Link against: SenXml.LIB

Capability Information

Required Capabilities

None

#include <SenXmlUtils.h>

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.

Dll SenXML.dll

Since:: Series60 3.0


Static Public Member Functions
static IMPORT_C HBufC8 *	ToUtf8LC (const TDesC16 &aUnicodeString)
	Helper function to convert unicode string to UTF-8 encoded.
static IMPORT_C HBufC16 *	ToUnicodeLC (const TDesC8 &aUtf8String)
	Helper function to convert UTF-8 string to unicode encoded.
static IMPORT_C TBool	StartsWith (const TDesC8 &aDes, const TDesC8 &aPrefix)
	Helper function to determine if a string starts with another string.
static IMPORT_C TBool	EndsWith (const TDesC8 &aDes, const TDesC8 &aPostfix)
	Helper function to determine if a string ends with another string.
static IMPORT_C TPtrC8	AttrValue (const RAttributeArray &aAttributes, const TDesC8 &aAttrName)
	Helper function to find a value of a given attribute.
static IMPORT_C HBufC8 *	AllocAttrValueL (const RAttributeArray &apAttrs, const TDesC8 &aAttrName)
	Get a newly allocated copy of the attribute.
static IMPORT_C void	BuildQNameL (const TDesC8 &aPrefix, const TDesC8 &aLocalName, HBufC8 *&aQName)
	Helper function to construct a qualified name.
static IMPORT_C TBool	EncodeHttpCharactersL (const TDesC8 &aOriginal, HBufC8 *&aEncoded)
	Encodes XML-escaping characters found from aOriginal to XML Basic Entities.
static IMPORT_C void	LeaveOnXmlEscapesL (const TDesC8 &aCandidate)
	Method leaves if aCandidate contains illegal, XML-escaping characters.
static void	LeaveOnInvalidElementNameL (const TDesC8 &aCandidate)
	Method leaves if aCandidate contains illegal, XML-escaping characters or is an empty descriptor.
static IMPORT_C HBufC8 *	EncodeHttpCharactersLC (const TDesC8 &aOriginal)
	Encodes XML-escaping characters found from aOriginal to XML Basic Entities.
static IMPORT_C TBool	DecodeHttpCharactersL (const TDesC8 &aOriginal, HBufC8 *&aDecoded)
	Method to provide functionality for decoding HTTP characters into XML escaping characters.
static IMPORT_C HBufC8 *	DecodeHttpCharactersLC (const TDesC8 &aOriginal)
	Same as DecodeHttpCharactersL(), but the decoded string OR exact copy of the aOriginal descriptor is returned and pushed to cleanup stack.
static IMPORT_C TPtrC8	NsPrefix (const TDesC8 &aQName)
	Helper function to get a prefix from a qualified name.
static IMPORT_C TPtrC8	LocalName (const TDesC8 &aQName)
	Helper function to get a local name from a qualified name.
static IMPORT_C CSenBaseAttribute *	RemoveAttributeL (CSenElement &aElement, const TDesC8 &aAttrName)
	Removes certain attribute from given element.
static IMPORT_C CSenBaseAttribute *	RemoveAttributeL (CSenElement &aElement, CSenBaseAttribute *apAttribute)
	Removes attribute from this element.
static IMPORT_C const TDesC8 &	AddAttributeL (CSenElement &aElement, const TDesC8 &aQName, const TDesC8 &aLocalName, const TDesC8 &aValue)
	Adds an attribute into this element.
static IMPORT_C const TDesC8 &	AddAttributeL (CSenElement &aElement, const TDesC8 &aAttrName, const TDesC8 &aValue)
	Adds an attribute into this element.
static IMPORT_C const TDesC8 &	AddAttributeL (CSenElement &aElement, CSenBaseAttribute *apAttribute)
	Adds an attribute into this element.

Member Function Documentation

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

Adds an attribute into this element.

Parameters:

apAttribute

Attribute to be added. Ownership is transferred to this element.

Returns:: attribute value as a string (TDesC8&)

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

Adds an attribute into this element.

Used also adding new namespaces into the element.

Parameters:

	aLocalName	Attribute's local name
	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.

static IMPORT_C const TDesC8& SenXmlUtils::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.

Parameters:

	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.

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

Get a newly allocated copy of the attribute.

Since:: Series60 3.0

Parameters:

	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.

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

Helper function to find a value of a given attribute.

Since:: Series60 3.0

Parameters:

	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.

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

Helper function to construct a qualified name.

Since:: Series60 3.0

Parameters:

	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.

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

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

Since:: Series60 3.0

Parameters:

	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.

static IMPORT_C HBufC8* SenXmlUtils::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

Parameters:

aOriginal

the string to be decoded.

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

static IMPORT_C TBool SenXmlUtils::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

Parameters:

	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.

static IMPORT_C HBufC8* SenXmlUtils::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

Parameters:

aOriginal

the string to be encoded.

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

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

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

Since:: Series60 3.0

Parameters:

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

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

static void SenXmlUtils::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

Parameters:

aCandidate

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

static IMPORT_C void SenXmlUtils::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

Parameters:

aCandidate

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

static IMPORT_C TPtrC8 SenXmlUtils::LocalName ( const TDesC8 & aQName ) [static]

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

Since:: Series60 3.0

Parameters:

aQName

the qualified name

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

static IMPORT_C TPtrC8 SenXmlUtils::NsPrefix ( const TDesC8 & aQName ) [static]

Helper function to get a prefix from a qualified name.

Since:: Series60 3.0

Parameters:

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.

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

Removes attribute from this element.

Parameters:

	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.

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

Removes certain attribute from given element.

May also be used when removing namespaces from the element.

Parameters:

	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.

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

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

Since:: Series60 3.0

Parameters:

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

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

static IMPORT_C HBufC16* SenXmlUtils::ToUnicodeLC ( const TDesC8 & aUtf8String ) [static]

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

Since:: Series60 3.0

Parameters:

aUtf8String

string to be converted.

Returns:: buffer as unicode, caller takes ownership.

static IMPORT_C HBufC8* SenXmlUtils::ToUtf8LC ( const TDesC16 & aUnicodeString ) [static]

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

Since:: Series60 3.0

Parameters:

aUnicodeString

string to be converted.

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

The documentation for this class was generated from the following file:

SenXmlUtils.h

SenXmlUtils Class Reference

Capability Information

Required Capabilities

Detailed Description

Static Public Member Functions

Member Function Documentation