williamr@2: /*
williamr@2: * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:        This class offers a set of utility functions for XML data
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef SEN_XML_UTILS_H
williamr@2: #define SEN_XML_UTILS_H
williamr@2: 
williamr@2: //  INCLUDES
williamr@2: #include <e32base.h>
williamr@2: #include <stringpool.h>
williamr@2: 
williamr@2: 
williamr@2: namespace Xml
williamr@2:     {
williamr@2:     // FORWARD DECLARES
williamr@2:     class RAttribute;
williamr@2: 
williamr@2:     // TYPE DEFINITIONS
williamr@2:     typedef RArray<RAttribute> RAttributeArray;
williamr@2:     }
williamr@2: 
williamr@2: using namespace Xml;
williamr@2: 
williamr@2: class CSenElement;
williamr@2: class CSenBaseAttribute;
williamr@2: 
williamr@2: 
williamr@2: // CONSTANTS
williamr@2: namespace
williamr@2:     {
williamr@2:     const TInt KMaxEscapedLength = 8;
williamr@2: 
williamr@2: /*
williamr@2:     // Moved to SenXmlConstants.hß
williamr@2: 
williamr@2:     // Five basic entities as descriptors
williamr@2:     _LIT8(KSenEscapedApos,     "&apos;");
williamr@2:     _LIT8(KSenEscapedDblQuot,  "&quot;");
williamr@2:     _LIT8(KSenEscapedGt,       "&gt;");
williamr@2:     _LIT8(KSenEscapedLt,       "&lt;");
williamr@2:     _LIT8(KSenEscapedAmp,      "&amp;");
williamr@2: 
williamr@2:     // XML-escaping chars as descriptors
williamr@2:     _LIT8(KSenAmpersandDesC8,  "&");
williamr@2:     _LIT8(KSenAposDesC8,       "\'");
williamr@2:     _LIT8(KSenDblQuotDesC8,    "\"");
williamr@2:     _LIT8(KSenGtDesC8,         ">");
williamr@2:     _LIT8(KSenLtDesC8,         "<");
williamr@2: */    
williamr@2:     }
williamr@2:     
williamr@2: // CLASS DECLARATION
williamr@2: 
williamr@2: /**
williamr@2: *  This class offers a set of utility functions for XML data
williamr@2: *  The helper methods include Unicode (UCS2) and UTF-8 encoding
williamr@2: *  and decoding as well as convenience methods to encode and
williamr@2: *  decode the five basic XML entities. There are functions
williamr@2: *  for extracting XML prefixes and building of qualifiedname
williamr@2: *  and a functionality for checking if an element name value 
williamr@2: *  is illegal or not.
williamr@2: *  @lib SenXML.dll
williamr@2: *  @since Series60 3.0
williamr@2: */
williamr@2: class SenXmlUtils
williamr@2:     {
williamr@2:     public: // New functions
williamr@2:         /**
williamr@2:          * Helper function to convert unicode string to UTF-8 encoded.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param aUnicodeString    string to be converted.
williamr@2:          * @return buffer as UTF-8, caller takes ownership.
williamr@2:         */
williamr@2:         IMPORT_C static HBufC8* ToUtf8LC(const TDesC16& aUnicodeString);
williamr@2: 
williamr@2:         /**
williamr@2:          * Helper function to convert UTF-8 string to unicode encoded.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param aUtf8String   string to be converted.
williamr@2:          * @return buffer as unicode, caller takes ownership.
williamr@2:          */
williamr@2:         IMPORT_C static HBufC16* ToUnicodeLC(const TDesC8& aUtf8String);
williamr@2: 
williamr@2:         /**
williamr@2:          * Helper function to determine if a string starts with another string.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param aDes  string to be searched from.
williamr@2:          * @param aPrefix   the prefix to be searched.
williamr@2:          * @return ETrue if given string starts with given prefix, 
williamr@2:          *          otherwise EFalse.
williamr@2:          */
williamr@2:         IMPORT_C static TBool StartsWith(const TDesC8& aDes,
williamr@2:                                          const TDesC8& aPrefix);
williamr@2: 
williamr@2:         /**
williamr@2:          * Helper function to determine if a string ends with another string.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param aDes  string to be searched from.
williamr@2:          * @param aPrefix   the prefix to be searched.
williamr@2:          * @return ETrue if given string ends with given prefix, 
williamr@2:          *          otherwise EFalse.
williamr@2:          */
williamr@2:         IMPORT_C static TBool EndsWith(const TDesC8& aDes, const TDesC8& aPostfix);
williamr@2: 
williamr@2:         /**
williamr@2:          * Helper function to find a value of a given attribute.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param aAttributes   Array which contains the attributes.
williamr@2:          * @param aAttrName The name of the attribute which value is asked.
williamr@2:          * @return The value of the wanted attribute, or KNullDesC8 if given
williamr@2:          *          attribute name was not found.
williamr@2:          */
williamr@2:         IMPORT_C static TPtrC8  AttrValue(  const RAttributeArray& aAttributes,
williamr@2:                                             const TDesC8& aAttrName);
williamr@2: 
williamr@2:         /**
williamr@2:          * Get a newly allocated copy of the attribute.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param apAttrs       Array which contains the attributes.
williamr@2:          * @param aAttrName The name of the attribute which value is asked.
williamr@2:          * @return A buffer containing the value of the wanted attribute.
williamr@2:          *          Buffer is newly allocated and ownership is transferred 
williamr@2:          *          to the caller. Can be NULL if attribute was not found.
williamr@2:          */
williamr@2:         IMPORT_C static HBufC8* AllocAttrValueL(const RAttributeArray& apAttrs,
williamr@2:                                                 const TDesC8& aAttrName);
williamr@2: 
williamr@2:         /**
williamr@2:          * Helper function to construct a qualified name.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param aPrefix       the prefix to be used.
williamr@2:          * @param aLocalName    the local name to be used.
williamr@2:          * @param   aQName      a ref-to-pointer which will contain the allocated
williamr@2:          *                      qualified name. This param should be NULL when
williamr@2:          *                      passed, otherwise memory leak will occur.
williamr@2:          *                      Caller has the ownership of this buffer.
williamr@2:          */
williamr@2:         IMPORT_C static void BuildQNameL(   const TDesC8& aPrefix, 
williamr@2:                                             const TDesC8& aLocalName,
williamr@2:                                             HBufC8*& aQName);
williamr@2: 
williamr@2:         /**
williamr@2:          * Encodes XML-escaping characters found from aOriginal 
williamr@2:          * to XML Basic Entities. 
williamr@2:          * Note, that aEncoded is not re-assigned IF there were NO
williamr@2:          * XML-escaping characters - '&', ''', '"', '<' or '>' -found.   
williamr@2:          * Otherwise, when encoding has been done, the aEncoded points
williamr@2:          * to newly allocated descriptor, which ownership belongs to
williamr@2:          * the caller (who should have given aEncoded pointer as NULL
williamr@2:          * in any case).
williamr@2:          * @since Series60 3.0
williamr@2:          * @param aOriginal the original descriptor.
williamr@2:          * @param aEncoded      a ref-to-pointer which will contain the allocated
williamr@2:          *                      encoded string. This param should be NULL when
williamr@2:          *                      passed, otherwise memory leak will occur.
williamr@2:          *                      Caller has the ownership of this buffer.
williamr@2:          */
williamr@2:         IMPORT_C static TBool EncodeHttpCharactersL(const TDesC8& aOriginal,
williamr@2:                                                     HBufC8*& aEncoded);
williamr@2:         /**
williamr@2:          * Method leaves if aCandidate contains illegal, XML-escaping characters.
williamr@2:          * Those characters, which will cause a leave are:
williamr@2:          *                           '&', ''', '"', '<' and '>'
williamr@2:          * @since Series60 3.0
williamr@2:          * @param   aCandidate  string to be checked.
williamr@2:          * Leave codes:
williamr@2:          *      KErrSenInvalidCharacters    if contains invalid characters.
williamr@2:          */
williamr@2:         IMPORT_C static void LeaveOnXmlEscapesL(const TDesC8& aCandidate); 
williamr@2:  
williamr@2:         /**
williamr@2:          * Method leaves if aCandidate contains illegal, XML-escaping characters
williamr@2:          * or is an empty descriptor.
williamr@2:          * Those characters, which will cause a leave are:
williamr@2:          *                           '&', ''', '"', '<' and '>'
williamr@2:          * @since Series60 3.0
williamr@2:          * @param   aCandidate  string to be checked.
williamr@2:          * Leave codes:
williamr@2:          *      KErrSenInvalidCharacters    if contains invalid characters.
williamr@2:          *      KErrSenZeroLengthDescriptor if aCandidate is zero length
williamr@2:          */
williamr@2:         static void LeaveOnInvalidElementNameL(const TDesC8& aCandidate);
williamr@2:         
williamr@2:         /**
williamr@2:          * Encodes XML-escaping characters found from aOriginal 
williamr@2:          * to XML Basic Entities. 
williamr@2:          *          Example: '&' -> '&amp;'
williamr@2:          * Note! Function returns a copy of aOriginal descriptor,
williamr@2:          * even if not a single illegal, XML-escaping character
williamr@2:          * was encoded.
williamr@2:          * The returned pointer to heap allocated descriptor is
williamr@2:          * pushed to the cleanup stack.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param   aOriginal   the string to be encoded.
williamr@2:          * @return  a buffer containing the encoded string. 
williamr@2:          *          Ownership is transferred to the caller.
williamr@2:          */
williamr@2:         IMPORT_C static HBufC8* EncodeHttpCharactersLC(const TDesC8& aOriginal);
williamr@2: 
williamr@2:         /**
williamr@2:          * Method to provide functionality for decoding HTTP characters into
williamr@2:          * XML escaping characters.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param   aOriginal   the string to be decoded.
williamr@2:          * @param   aDecoded    the buffer that will contain the decoded string
williamr@2:          *                      on return. Caller has the ownership of this.
williamr@2:          *                      Will be similar as aOriginal if nothing was 
williamr@2:          *                      replaced.
williamr@2:          * @return ETrue if any XML escaping (some Basic Entity) 
williamr@2:          *                  character-sequence was decoded.
williamr@2:          */
williamr@2:         IMPORT_C static TBool DecodeHttpCharactersL(const TDesC8& aOriginal,
williamr@2:                                                 HBufC8*& aDecoded);
williamr@2:         
williamr@2:         /**
williamr@2:          * Same as DecodeHttpCharactersL(), but the decoded string OR
williamr@2:          * exact copy of the aOriginal descriptor is returned and pushed
williamr@2:          * to cleanup stack.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param   aOriginal   the string to be decoded.
williamr@2:          * @return buffer located in the cleanup stack containing the decoded 
williamr@2:          *          string
williamr@2:          */
williamr@2:         IMPORT_C static HBufC8* DecodeHttpCharactersLC(const TDesC8& aOriginal);
williamr@2: 
williamr@2:         /**
williamr@2:          * Helper function to get a prefix from a qualified name.
williamr@2:          * @since Series60 3.0
williamr@2:          * @param   aQName  the qualified name
williamr@2:          * @return the namespace prefix for the element, e.g. 'soap' for
williamr@2:          *      'soap:Body'. The returned pointer is empty if there is no prefix.
williamr@2:          */
williamr@2:         IMPORT_C static TPtrC8 NsPrefix(const TDesC8& aQName);
williamr@2: 
williamr@2:         /**
williamr@2:          *  Helper function to get a local name from a qualified name.
williamr@2:          *  @since Series60 3.0
williamr@2:          *  @param  aQName  the qualified name
williamr@2:          *  @return the local name for the element, e.g. 'Body' for
williamr@2:          *      'soap:Body'.
williamr@2:          */
williamr@2:         IMPORT_C static TPtrC8 LocalName(const TDesC8& aQName);
williamr@2: 
williamr@2:         /**
williamr@2:         * Removes certain attribute from given element. May also be used when
williamr@2:         * removing namespaces from the element.
williamr@2:         * @param aElement   Element from which attribute will be removed.
williamr@2:         * @param aAttrName  Attribute's local name
williamr@2:         * @return pointer to removed attribute, which ownership is transferred to
williamr@2:         * caller or NULL, if no matching attribute was found from this element. 
williamr@2:         */
williamr@2:         IMPORT_C static CSenBaseAttribute* RemoveAttributeL(CSenElement& aElement,
williamr@2:                                                             const TDesC8& aAttrName);
williamr@2: 
williamr@2:         /** 
williamr@2:         * Removes attribute from this element.
williamr@2:         * @param aElement       Element from which attribute will be removed.
williamr@2:         * @param apAttribute    is the attribute to be removed.
williamr@2:         * transferred to this element.
williamr@2:         * @return pointer to removed attribute, which ownership is transferred to
williamr@2:         * caller or NULL, if no matching attribute was found from this element. 
williamr@2:         */
williamr@2:         IMPORT_C static CSenBaseAttribute* RemoveAttributeL(CSenElement& aElement,
williamr@2:                                                             CSenBaseAttribute* apAttribute);
williamr@2: 
williamr@2:         /**
williamr@2:         * Adds an attribute into this element. Used also adding new namespaces
williamr@2:         * into the element.
williamr@2:         * @param aQName     Attribute's qualified name
williamr@2:         * @param aLocalName Attribute's local name
williamr@2:         * @param aValue     Attribute's value
williamr@2:         * @return value of the attribute as string (TDesC&)
williamr@2:         * Leave codes:  
williamr@2:         *       KErrSenInvalidCharacters if aLocalName or aQName contain illegal 
williamr@2:         *       characters.     
williamr@2:         *       KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
williamr@2:                                                     const TDesC8& aQName,
williamr@2:                                                     const TDesC8& aLocalName,
williamr@2:                                                     const TDesC8& aValue);
williamr@2: 
williamr@2:         /**
williamr@2:         * Adds an attribute into this element. Used also adding new namespaces
williamr@2:         * into the element.
williamr@2:         * @param aLocalName Attribute's local name
williamr@2:         * @param aValue     Attribute's value
williamr@2:         * @return value of the attribute as string (TDesC&)
williamr@2:         * Leave codes:  
williamr@2:         *       KErrSenInvalidCharacters if aLocalName contains illegal characters.     
williamr@2:         *       KErrSenZeroLengthDescriptor if aAttrName is zero length, or
williamr@2:         *       if the local name part of it is zero length.
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
williamr@2:                                                     const TDesC8& aAttrName,
williamr@2:                                                     const TDesC8& aValue);
williamr@2:         /** 
williamr@2:         * Adds an attribute into this element.
williamr@2:         * @param apAttribute    Attribute to be added. Ownership is transferred
williamr@2:         *                       to this element.
williamr@2:         * @return attribute value as a string (TDesC8&)
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC8& AddAttributeL(CSenElement& aElement,
williamr@2:                                                     CSenBaseAttribute* apAttribute);
williamr@2:         
williamr@2:     private:
williamr@2:         
williamr@2:         /**
williamr@2:         * C++ default constructor.
williamr@2:         */
williamr@2:         SenXmlUtils() { }
williamr@2: 
williamr@2:         /**
williamr@2:         * Prohibit copy constructor if not deriving from CBase.
williamr@2:         */
williamr@2:         SenXmlUtils( const SenXmlUtils& );
williamr@2:         
williamr@2:         /** 
williamr@2:         * Prohibit assignment operator if not deriving from CBase.
williamr@2:         */
williamr@2:         SenXmlUtils& operator=( const SenXmlUtils& );
williamr@2: 
williamr@2:         /**
williamr@2:         * Replaces the destination with the given values
williamr@2:         */
williamr@2:         static TBool ReplaceAll( TPtr8 aDestination, 
williamr@2:                                  const TDesC8& aFrom,
williamr@2:                                  const TDesC8& aTo );        
williamr@2: 
williamr@2: 		/**
williamr@2: 		* Finds the attribute with the given name
williamr@2: 		*/
williamr@2:         static CSenBaseAttribute* FindAttrL( CSenElement& aElement,
williamr@2:                                              const TDesC8& aName );
williamr@2:     };
williamr@2: 
williamr@2: #endif // SEN_XML_UTILS_H
williamr@2: 
williamr@2: // End of File
williamr@2: