1.1 --- a/epoc32/include/mw/senxmlutils.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/senxmlutils.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,361 @@
1.4 -senxmlutils.h
1.5 +/*
1.6 +* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: This class offers a set of utility functions for XML data
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +
1.29 +
1.30 +#ifndef SEN_XML_UTILS_H
1.31 +#define SEN_XML_UTILS_H
1.32 +
1.33 +// INCLUDES
1.34 +#include <e32base.h>
1.35 +#include <stringpool.h>
1.36 +
1.37 +
1.38 +namespace Xml
1.39 + {
1.40 + // FORWARD DECLARES
1.41 + class RAttribute;
1.42 +
1.43 + // TYPE DEFINITIONS
1.44 + typedef RArray<RAttribute> RAttributeArray;
1.45 + }
1.46 +
1.47 +using namespace Xml;
1.48 +
1.49 +class CSenElement;
1.50 +class CSenBaseAttribute;
1.51 +
1.52 +
1.53 +// CONSTANTS
1.54 +namespace
1.55 + {
1.56 + const TInt KMaxEscapedLength = 8;
1.57 +
1.58 +/*
1.59 + // Moved to SenXmlConstants.hß
1.60 +
1.61 + // Five basic entities as descriptors
1.62 + _LIT8(KSenEscapedApos, "'");
1.63 + _LIT8(KSenEscapedDblQuot, """);
1.64 + _LIT8(KSenEscapedGt, ">");
1.65 + _LIT8(KSenEscapedLt, "<");
1.66 + _LIT8(KSenEscapedAmp, "&");
1.67 +
1.68 + // XML-escaping chars as descriptors
1.69 + _LIT8(KSenAmpersandDesC8, "&");
1.70 + _LIT8(KSenAposDesC8, "\'");
1.71 + _LIT8(KSenDblQuotDesC8, "\"");
1.72 + _LIT8(KSenGtDesC8, ">");
1.73 + _LIT8(KSenLtDesC8, "<");
1.74 +*/
1.75 + }
1.76 +
1.77 +// CLASS DECLARATION
1.78 +
1.79 +/**
1.80 +* This class offers a set of utility functions for XML data
1.81 +* The helper methods include Unicode (UCS2) and UTF-8 encoding
1.82 +* and decoding as well as convenience methods to encode and
1.83 +* decode the five basic XML entities. There are functions
1.84 +* for extracting XML prefixes and building of qualifiedname
1.85 +* and a functionality for checking if an element name value
1.86 +* is illegal or not.
1.87 +* @lib SenXML.dll
1.88 +* @since Series60 3.0
1.89 +*/
1.90 +class SenXmlUtils
1.91 + {
1.92 + public: // New functions
1.93 + /**
1.94 + * Helper function to convert unicode string to UTF-8 encoded.
1.95 + * @since Series60 3.0
1.96 + * @param aUnicodeString string to be converted.
1.97 + * @return buffer as UTF-8, caller takes ownership.
1.98 + */
1.99 + IMPORT_C static HBufC8* ToUtf8LC(const TDesC16& aUnicodeString);
1.100 +
1.101 + /**
1.102 + * Helper function to convert UTF-8 string to unicode encoded.
1.103 + * @since Series60 3.0
1.104 + * @param aUtf8String string to be converted.
1.105 + * @return buffer as unicode, caller takes ownership.
1.106 + */
1.107 + IMPORT_C static HBufC16* ToUnicodeLC(const TDesC8& aUtf8String);
1.108 +
1.109 + /**
1.110 + * Helper function to determine if a string starts with another string.
1.111 + * @since Series60 3.0
1.112 + * @param aDes string to be searched from.
1.113 + * @param aPrefix the prefix to be searched.
1.114 + * @return ETrue if given string starts with given prefix,
1.115 + * otherwise EFalse.
1.116 + */
1.117 + IMPORT_C static TBool StartsWith(const TDesC8& aDes,
1.118 + const TDesC8& aPrefix);
1.119 +
1.120 + /**
1.121 + * Helper function to determine if a string ends with another string.
1.122 + * @since Series60 3.0
1.123 + * @param aDes string to be searched from.
1.124 + * @param aPrefix the prefix to be searched.
1.125 + * @return ETrue if given string ends with given prefix,
1.126 + * otherwise EFalse.
1.127 + */
1.128 + IMPORT_C static TBool EndsWith(const TDesC8& aDes, const TDesC8& aPostfix);
1.129 +
1.130 + /**
1.131 + * Helper function to find a value of a given attribute.
1.132 + * @since Series60 3.0
1.133 + * @param aAttributes Array which contains the attributes.
1.134 + * @param aAttrName The name of the attribute which value is asked.
1.135 + * @return The value of the wanted attribute, or KNullDesC8 if given
1.136 + * attribute name was not found.
1.137 + */
1.138 + IMPORT_C static TPtrC8 AttrValue( const RAttributeArray& aAttributes,
1.139 + const TDesC8& aAttrName);
1.140 +
1.141 + /**
1.142 + * Get a newly allocated copy of the attribute.
1.143 + * @since Series60 3.0
1.144 + * @param apAttrs Array which contains the attributes.
1.145 + * @param aAttrName The name of the attribute which value is asked.
1.146 + * @return A buffer containing the value of the wanted attribute.
1.147 + * Buffer is newly allocated and ownership is transferred
1.148 + * to the caller. Can be NULL if attribute was not found.
1.149 + */
1.150 + IMPORT_C static HBufC8* AllocAttrValueL(const RAttributeArray& apAttrs,
1.151 + const TDesC8& aAttrName);
1.152 +
1.153 + /**
1.154 + * Helper function to construct a qualified name.
1.155 + * @since Series60 3.0
1.156 + * @param aPrefix the prefix to be used.
1.157 + * @param aLocalName the local name to be used.
1.158 + * @param aQName a ref-to-pointer which will contain the allocated
1.159 + * qualified name. This param should be NULL when
1.160 + * passed, otherwise memory leak will occur.
1.161 + * Caller has the ownership of this buffer.
1.162 + */
1.163 + IMPORT_C static void BuildQNameL( const TDesC8& aPrefix,
1.164 + const TDesC8& aLocalName,
1.165 + HBufC8*& aQName);
1.166 +
1.167 + /**
1.168 + * Encodes XML-escaping characters found from aOriginal
1.169 + * to XML Basic Entities.
1.170 + * Note, that aEncoded is not re-assigned IF there were NO
1.171 + * XML-escaping characters - '&', ''', '"', '<' or '>' -found.
1.172 + * Otherwise, when encoding has been done, the aEncoded points
1.173 + * to newly allocated descriptor, which ownership belongs to
1.174 + * the caller (who should have given aEncoded pointer as NULL
1.175 + * in any case).
1.176 + * @since Series60 3.0
1.177 + * @param aOriginal the original descriptor.
1.178 + * @param aEncoded a ref-to-pointer which will contain the allocated
1.179 + * encoded string. This param should be NULL when
1.180 + * passed, otherwise memory leak will occur.
1.181 + * Caller has the ownership of this buffer.
1.182 + */
1.183 + IMPORT_C static TBool EncodeHttpCharactersL(const TDesC8& aOriginal,
1.184 + HBufC8*& aEncoded);
1.185 + /**
1.186 + * Method leaves if aCandidate contains illegal, XML-escaping characters.
1.187 + * Those characters, which will cause a leave are:
1.188 + * '&', ''', '"', '<' and '>'
1.189 + * @since Series60 3.0
1.190 + * @param aCandidate string to be checked.
1.191 + * Leave codes:
1.192 + * KErrSenInvalidCharacters if contains invalid characters.
1.193 + */
1.194 + IMPORT_C static void LeaveOnXmlEscapesL(const TDesC8& aCandidate);
1.195 +
1.196 + /**
1.197 + * Method leaves if aCandidate contains illegal, XML-escaping characters
1.198 + * or is an empty descriptor.
1.199 + * Those characters, which will cause a leave are:
1.200 + * '&', ''', '"', '<' and '>'
1.201 + * @since Series60 3.0
1.202 + * @param aCandidate string to be checked.
1.203 + * Leave codes:
1.204 + * KErrSenInvalidCharacters if contains invalid characters.
1.205 + * KErrSenZeroLengthDescriptor if aCandidate is zero length
1.206 + */
1.207 + static void LeaveOnInvalidElementNameL(const TDesC8& aCandidate);
1.208 +
1.209 + /**
1.210 + * Encodes XML-escaping characters found from aOriginal
1.211 + * to XML Basic Entities.
1.212 + * Example: '&' -> '&'
1.213 + * Note! Function returns a copy of aOriginal descriptor,
1.214 + * even if not a single illegal, XML-escaping character
1.215 + * was encoded.
1.216 + * The returned pointer to heap allocated descriptor is
1.217 + * pushed to the cleanup stack.
1.218 + * @since Series60 3.0
1.219 + * @param aOriginal the string to be encoded.
1.220 + * @return a buffer containing the encoded string.
1.221 + * Ownership is transferred to the caller.
1.222 + */
1.223 + IMPORT_C static HBufC8* EncodeHttpCharactersLC(const TDesC8& aOriginal);
1.224 +
1.225 + /**
1.226 + * Method to provide functionality for decoding HTTP characters into
1.227 + * XML escaping characters.
1.228 + * @since Series60 3.0
1.229 + * @param aOriginal the string to be decoded.
1.230 + * @param aDecoded the buffer that will contain the decoded string
1.231 + * on return. Caller has the ownership of this.
1.232 + * Will be similar as aOriginal if nothing was
1.233 + * replaced.
1.234 + * @return ETrue if any XML escaping (some Basic Entity)
1.235 + * character-sequence was decoded.
1.236 + */
1.237 + IMPORT_C static TBool DecodeHttpCharactersL(const TDesC8& aOriginal,
1.238 + HBufC8*& aDecoded);
1.239 +
1.240 + /**
1.241 + * Same as DecodeHttpCharactersL(), but the decoded string OR
1.242 + * exact copy of the aOriginal descriptor is returned and pushed
1.243 + * to cleanup stack.
1.244 + * @since Series60 3.0
1.245 + * @param aOriginal the string to be decoded.
1.246 + * @return buffer located in the cleanup stack containing the decoded
1.247 + * string
1.248 + */
1.249 + IMPORT_C static HBufC8* DecodeHttpCharactersLC(const TDesC8& aOriginal);
1.250 +
1.251 + /**
1.252 + * Helper function to get a prefix from a qualified name.
1.253 + * @since Series60 3.0
1.254 + * @param aQName the qualified name
1.255 + * @return the namespace prefix for the element, e.g. 'soap' for
1.256 + * 'soap:Body'. The returned pointer is empty if there is no prefix.
1.257 + */
1.258 + IMPORT_C static TPtrC8 NsPrefix(const TDesC8& aQName);
1.259 +
1.260 + /**
1.261 + * Helper function to get a local name from a qualified name.
1.262 + * @since Series60 3.0
1.263 + * @param aQName the qualified name
1.264 + * @return the local name for the element, e.g. 'Body' for
1.265 + * 'soap:Body'.
1.266 + */
1.267 + IMPORT_C static TPtrC8 LocalName(const TDesC8& aQName);
1.268 +
1.269 + /**
1.270 + * Removes certain attribute from given element. May also be used when
1.271 + * removing namespaces from the element.
1.272 + * @param aElement Element from which attribute will be removed.
1.273 + * @param aAttrName Attribute's local name
1.274 + * @return pointer to removed attribute, which ownership is transferred to
1.275 + * caller or NULL, if no matching attribute was found from this element.
1.276 + */
1.277 + IMPORT_C static CSenBaseAttribute* RemoveAttributeL(CSenElement& aElement,
1.278 + const TDesC8& aAttrName);
1.279 +
1.280 + /**
1.281 + * Removes attribute from this element.
1.282 + * @param aElement Element from which attribute will be removed.
1.283 + * @param apAttribute is the attribute to be removed.
1.284 + * transferred to this element.
1.285 + * @return pointer to removed attribute, which ownership is transferred to
1.286 + * caller or NULL, if no matching attribute was found from this element.
1.287 + */
1.288 + IMPORT_C static CSenBaseAttribute* RemoveAttributeL(CSenElement& aElement,
1.289 + CSenBaseAttribute* apAttribute);
1.290 +
1.291 + /**
1.292 + * Adds an attribute into this element. Used also adding new namespaces
1.293 + * into the element.
1.294 + * @param aQName Attribute's qualified name
1.295 + * @param aLocalName Attribute's local name
1.296 + * @param aValue Attribute's value
1.297 + * @return value of the attribute as string (TDesC&)
1.298 + * Leave codes:
1.299 + * KErrSenInvalidCharacters if aLocalName or aQName contain illegal
1.300 + * characters.
1.301 + * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
1.302 + */
1.303 + IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
1.304 + const TDesC8& aQName,
1.305 + const TDesC8& aLocalName,
1.306 + const TDesC8& aValue);
1.307 +
1.308 + /**
1.309 + * Adds an attribute into this element. Used also adding new namespaces
1.310 + * into the element.
1.311 + * @param aLocalName Attribute's local name
1.312 + * @param aValue Attribute's value
1.313 + * @return value of the attribute as string (TDesC&)
1.314 + * Leave codes:
1.315 + * KErrSenInvalidCharacters if aLocalName contains illegal characters.
1.316 + * KErrSenZeroLengthDescriptor if aAttrName is zero length, or
1.317 + * if the local name part of it is zero length.
1.318 + */
1.319 + IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
1.320 + const TDesC8& aAttrName,
1.321 + const TDesC8& aValue);
1.322 + /**
1.323 + * Adds an attribute into this element.
1.324 + * @param apAttribute Attribute to be added. Ownership is transferred
1.325 + * to this element.
1.326 + * @return attribute value as a string (TDesC8&)
1.327 + */
1.328 + IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
1.329 + CSenBaseAttribute* apAttribute);
1.330 +
1.331 + private:
1.332 +
1.333 + /**
1.334 + * C++ default constructor.
1.335 + */
1.336 + SenXmlUtils() { }
1.337 +
1.338 + /**
1.339 + * Prohibit copy constructor if not deriving from CBase.
1.340 + */
1.341 + SenXmlUtils( const SenXmlUtils& );
1.342 +
1.343 + /**
1.344 + * Prohibit assignment operator if not deriving from CBase.
1.345 + */
1.346 + SenXmlUtils& operator=( const SenXmlUtils& );
1.347 +
1.348 + /**
1.349 + * Replaces the destination with the given values
1.350 + */
1.351 + static TBool ReplaceAll( TPtr8 aDestination,
1.352 + const TDesC8& aFrom,
1.353 + const TDesC8& aTo );
1.354 +
1.355 + /**
1.356 + * Finds the attribute with the given name
1.357 + */
1.358 + static CSenBaseAttribute* FindAttrL( CSenElement& aElement,
1.359 + const TDesC8& aName );
1.360 + };
1.361 +
1.362 +#endif // SEN_XML_UTILS_H
1.363 +
1.364 +// End of File
1.365 +