/*
* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: This class offers a set of utility functions for XML data
*
*/
#ifndef SEN_XML_UTILS_H
#define SEN_XML_UTILS_H
// INCLUDES
#include <e32base.h>
#include <stringpool.h>
namespace Xml
{
// FORWARD DECLARES
class RAttribute;
// TYPE DEFINITIONS
typedef RArray<RAttribute> RAttributeArray;
}
using namespace Xml;
class CSenElement;
class CSenBaseAttribute;
// CONSTANTS
namespace
{
const TInt KMaxEscapedLength = 8;
/*
// Moved to SenXmlConstants.hß
// Five basic entities as descriptors
_LIT8(KSenEscapedApos, "'");
_LIT8(KSenEscapedDblQuot, """);
_LIT8(KSenEscapedGt, ">");
_LIT8(KSenEscapedLt, "<");
_LIT8(KSenEscapedAmp, "&");
// XML-escaping chars as descriptors
_LIT8(KSenAmpersandDesC8, "&");
_LIT8(KSenAposDesC8, "\'");
_LIT8(KSenDblQuotDesC8, "\"");
_LIT8(KSenGtDesC8, ">");
_LIT8(KSenLtDesC8, "<");
*/
}
// CLASS DECLARATION
/**
* 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.
* @lib SenXML.dll
* @since Series60 3.0
*/
class SenXmlUtils
{
public: // New functions
/**
* Helper function to convert unicode string to UTF-8 encoded.
* @since Series60 3.0
* @param aUnicodeString string to be converted.
* @return buffer as UTF-8, caller takes ownership.
*/
IMPORT_C static HBufC8* ToUtf8LC(const TDesC16& aUnicodeString);
/**
* Helper function to convert UTF-8 string to unicode encoded.
* @since Series60 3.0
* @param aUtf8String string to be converted.
* @return buffer as unicode, caller takes ownership.
*/
IMPORT_C static HBufC16* ToUnicodeLC(const TDesC8& aUtf8String);
/**
* Helper function to determine if a string starts with another string.
* @since Series60 3.0
* @param aDes string to be searched from.
* @param aPrefix the prefix to be searched.
* @return ETrue if given string starts with given prefix,
* otherwise EFalse.
*/
IMPORT_C static TBool StartsWith(const TDesC8& aDes,
const TDesC8& aPrefix);
/**
* Helper function to determine if a string ends with another string.
* @since Series60 3.0
* @param aDes string to be searched from.
* @param aPrefix the prefix to be searched.
* @return ETrue if given string ends with given prefix,
* otherwise EFalse.
*/
IMPORT_C static TBool EndsWith(const TDesC8& aDes, const TDesC8& aPostfix);
/**
* Helper function to find a value of a given attribute.
* @since Series60 3.0
* @param aAttributes Array which contains the attributes.
* @param aAttrName The name of the attribute which value is asked.
* @return The value of the wanted attribute, or KNullDesC8 if given
* attribute name was not found.
*/
IMPORT_C static TPtrC8 AttrValue( const RAttributeArray& aAttributes,
const TDesC8& aAttrName);
/**
* Get a newly allocated copy of the attribute.
* @since Series60 3.0
* @param apAttrs Array which contains the attributes.
* @param aAttrName The name of the attribute which value is asked.
* @return 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.
*/
IMPORT_C static HBufC8* AllocAttrValueL(const RAttributeArray& apAttrs,
const TDesC8& aAttrName);
/**
* Helper function to construct a qualified name.
* @since Series60 3.0
* @param aPrefix the prefix to be used.
* @param aLocalName the local name to be used.
* @param 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.
*/
IMPORT_C static void BuildQNameL( const TDesC8& aPrefix,
const TDesC8& aLocalName,
HBufC8*& aQName);
/**
* 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
* @param aOriginal the original descriptor.
* @param 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.
*/
IMPORT_C static TBool EncodeHttpCharactersL(const TDesC8& aOriginal,
HBufC8*& aEncoded);
/**
* Method leaves if aCandidate contains illegal, XML-escaping characters.
* Those characters, which will cause a leave are:
* '&', ''', '"', '<' and '>'
* @since Series60 3.0
* @param aCandidate string to be checked.
* Leave codes:
* KErrSenInvalidCharacters if contains invalid characters.
*/
IMPORT_C static void LeaveOnXmlEscapesL(const TDesC8& aCandidate);
/**
* 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
* @param aCandidate string to be checked.
* Leave codes:
* KErrSenInvalidCharacters if contains invalid characters.
* KErrSenZeroLengthDescriptor if aCandidate is zero length
*/
static void LeaveOnInvalidElementNameL(const TDesC8& aCandidate);
/**
* 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
* @param aOriginal the string to be encoded.
* @return a buffer containing the encoded string.
* Ownership is transferred to the caller.
*/
IMPORT_C static HBufC8* EncodeHttpCharactersLC(const TDesC8& aOriginal);
/**
* Method to provide functionality for decoding HTTP characters into
* XML escaping characters.
* @since Series60 3.0
* @param aOriginal the string to be decoded.
* @param 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.
* @return ETrue if any XML escaping (some Basic Entity)
* character-sequence was decoded.
*/
IMPORT_C static TBool DecodeHttpCharactersL(const TDesC8& aOriginal,
HBufC8*& aDecoded);
/**
* 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
* @param aOriginal the string to be decoded.
* @return buffer located in the cleanup stack containing the decoded
* string
*/
IMPORT_C static HBufC8* DecodeHttpCharactersLC(const TDesC8& aOriginal);
/**
* Helper function to get a prefix from a qualified name.
* @since Series60 3.0
* @param aQName the qualified name
* @return the namespace prefix for the element, e.g. 'soap' for
* 'soap:Body'. The returned pointer is empty if there is no prefix.
*/
IMPORT_C static TPtrC8 NsPrefix(const TDesC8& aQName);
/**
* Helper function to get a local name from a qualified name.
* @since Series60 3.0
* @param aQName the qualified name
* @return the local name for the element, e.g. 'Body' for
* 'soap:Body'.
*/
IMPORT_C static TPtrC8 LocalName(const TDesC8& aQName);
/**
* Removes certain attribute from given element. May also be used when
* removing namespaces from the element.
* @param aElement Element from which attribute will be removed.
* @param aAttrName Attribute's local name
* @return pointer to removed attribute, which ownership is transferred to
* caller or NULL, if no matching attribute was found from this element.
*/
IMPORT_C static CSenBaseAttribute* RemoveAttributeL(CSenElement& aElement,
const TDesC8& aAttrName);
/**
* Removes attribute from this element.
* @param aElement Element from which attribute will be removed.
* @param apAttribute is the attribute to be removed.
* transferred to this element.
* @return pointer to removed attribute, which ownership is transferred to
* caller or NULL, if no matching attribute was found from this element.
*/
IMPORT_C static CSenBaseAttribute* RemoveAttributeL(CSenElement& aElement,
CSenBaseAttribute* apAttribute);
/**
* Adds an attribute into this element. Used also adding new namespaces
* into the element.
* @param aQName Attribute's qualified name
* @param aLocalName Attribute's local name
* @param aValue Attribute's value
* @return 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.
*/
IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
const TDesC8& aQName,
const TDesC8& aLocalName,
const TDesC8& aValue);
/**
* Adds an attribute into this element. Used also adding new namespaces
* into the element.
* @param aLocalName Attribute's local name
* @param aValue Attribute's value
* @return 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.
*/
IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
const TDesC8& aAttrName,
const TDesC8& aValue);
/**
* Adds an attribute into this element.
* @param apAttribute Attribute to be added. Ownership is transferred
* to this element.
* @return attribute value as a string (TDesC8&)
*/
IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
CSenBaseAttribute* apAttribute);
private:
/**
* C++ default constructor.
*/
SenXmlUtils() { }
/**
* Prohibit copy constructor if not deriving from CBase.
*/
SenXmlUtils( const SenXmlUtils& );
/**
* Prohibit assignment operator if not deriving from CBase.
*/
SenXmlUtils& operator=( const SenXmlUtils& );
/**
* Replaces the destination with the given values
*/
static TBool ReplaceAll( TPtr8 aDestination,
const TDesC8& aFrom,
const TDesC8& aTo );
/**
* Finds the attribute with the given name
*/
static CSenBaseAttribute* FindAttrL( CSenElement& aElement,
const TDesC8& aName );
};
#endif // SEN_XML_UTILS_H
// End of File