1.1 --- a/epoc32/include/mw/senelement.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/senelement.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,559 @@
1.4 -senelement.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: Central place for debug-type macros
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +
1.29 +#ifndef SEN_ELEMENT_H
1.30 +#define SEN_ELEMENT_H
1.31 +
1.32 +// INCLUDES
1.33 +#include <e32base.h>
1.34 +#include <s32strm.h>
1.35 +#include <xml/Attribute.h>
1.36 +#include <stringpool.h>
1.37 +
1.38 +#include <MSenElement.h>
1.39 +
1.40 +using namespace Xml;
1.41 +
1.42 +// CLASS DECLARATION
1.43 +
1.44 +/**
1.45 +* Abstract class definition of XML element
1.46 +* @lib SenXML.dll
1.47 +* @since Series60 3.0
1.48 +*/
1.49 +class CSenElement : public CBase, public MSenElement
1.50 + {
1.51 + public: // Functions from base classes
1.52 +
1.53 + // From MSenElement
1.54 +
1.55 + /**
1.56 + * Getter for local name.
1.57 + * @since Series60 3.0
1.58 + * @return KNullDesC if not set (argumentless constructor).
1.59 + */
1.60 + virtual const TDesC8& LocalName() const = 0;
1.61 +
1.62 + /**
1.63 + * Getter for namespace URI.
1.64 + * @since Series60 3.0
1.65 + * @return KNullDesC if not set.
1.66 + */
1.67 + virtual const TDesC8& NamespaceURI() const = 0;
1.68 +
1.69 + /**
1.70 + * Setter for Element's namespace URI.
1.71 + * @since Series60 3.0
1.72 + * @param @param aNsUri: Namespace URI
1.73 + */
1.74 + virtual void SetNamespaceL(const TDesC8& aNsUri) = 0;
1.75 +
1.76 + /**
1.77 + * Setter for Element's namespace URI.
1.78 + * @since Series60 3.0
1.79 + * @param aNsPrefix: Namespace prefix
1.80 + * @param aNsUri: Namespace URI
1.81 + */
1.82 + virtual void SetNamespaceL( const TDesC8& aNsPrefix,
1.83 + const TDesC8& aNsUri) = 0;
1.84 +
1.85 + /**
1.86 + * Method for adding a namespace for the Element.
1.87 + * @since Series60 3.0
1.88 + * @param aPrefix: Namespace prefix
1.89 + * @param aUri: Namespace URI
1.90 + * @return the added Namespace, or the equivalent pre-existing one.
1.91 + */
1.92 + virtual const CSenNamespace* AddNamespaceL( const TDesC8& aPrefix,
1.93 + const TDesC8& aUri) = 0;
1.94 +
1.95 + /**
1.96 + * Getter for Element's namespace.
1.97 + * @since Series60 3.0
1.98 + * @return const pointer to the CSenNamespace object of this Element.
1.99 + * Returns NULL, if not set.
1.100 + */
1.101 + virtual const CSenNamespace* Namespace() = 0;
1.102 +
1.103 + /**
1.104 + * @since Series60 3.0
1.105 + * @param prefix
1.106 + * @return the namespace that is declared for the given prefix
1.107 + * within the scope of this Element. If no such prefix is
1.108 + * declared return NULL.
1.109 + */
1.110 + virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix) = 0;
1.111 +
1.112 + /**
1.113 + * Get namespace that is declared for the given prefix and namespace
1.114 + * URI within the scope of this element.
1.115 + * @since Series60 3.0
1.116 + * @param aNsPrefix The prefix used to search
1.117 + * @param aUri The namespace URI used to search.
1.118 + * @return the found namespace that is declared for the given prefix
1.119 + * and namespace URI within the scope of this Element
1.120 + * or NULL if not found.
1.121 + */
1.122 + virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
1.123 + const TDesC8& aUri) = 0;
1.124 +
1.125 + /**
1.126 + * @since Series60 3.0
1.127 + * @param aNsPrefix The prefix used to search
1.128 + * @param aCheckInParent The flag indicating whether to check parent's
1.129 + * namespaces too if not found in the current
1.130 + * element.
1.131 + * ETrue to check, EFalse for not to check.
1.132 + * @return the found Namespace that is declared for the given prefix
1.133 + * and namespace URI within the scope of this Element
1.134 + * or NULL if not found
1.135 + */
1.136 + virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
1.137 + const TBool aCheckInParent) = 0;
1.138 +
1.139 + /**
1.140 + * Getter for namespace prefix of this element.
1.141 + * @since Series60 3.0
1.142 + * @return namespace prefix or KNullDesC8 if not set.
1.143 + */
1.144 + virtual const TDesC8& NsPrefix() const = 0;
1.145 +
1.146 + /**
1.147 + * Setter for namespace prefix of this element.
1.148 + * @since Series60 3.0
1.149 + * @param aPrefix: new namespace prefix for the element.
1.150 + */
1.151 + virtual void SetPrefixL(const TDesC8& aPrefix) = 0;
1.152 +
1.153 + /**
1.154 + * Method for checking if the element has any content within.
1.155 + * @since Series60 3.0
1.156 + * @return ETrue if has content, EFalse if not.
1.157 + */
1.158 + virtual TBool HasContent() const = 0;
1.159 +
1.160 + /**
1.161 + * Getter for the content of the element.
1.162 + * @since Series60 3.0
1.163 + * @return the content or KNullDesC8 if empty.
1.164 + */
1.165 + virtual TPtrC8 Content() const = 0;
1.166 +
1.167 + /**
1.168 + * Getter for the content of the element, Unicode (UCS2) version
1.169 + * @since Series60 3.0
1.170 + * @return content as Unicode. Ownership is transferred to the caller.
1.171 + */
1.172 + virtual HBufC* ContentUnicodeL() const = 0;
1.173 +
1.174 + /**
1.175 + * Sets the content to the element. Old content is overwritten.
1.176 + * @since Series60 3.0
1.177 + * @param aContent The content to be set. Can be KNullDesC8.
1.178 + * @return The content of the element or KNullDesC8 if no content was set.
1.179 + */
1.180 + virtual TPtrC8 SetContentL(const TDesC8& aContent) = 0;
1.181 +
1.182 + /**
1.183 + * Gets the write stream for the content for easy appending.
1.184 + * Writing 8-bit (UTF-8) string to the returned stream will be appended
1.185 + * to the content.
1.186 + * @since Series60 3.0
1.187 + * @return reference to the RWriteStream.
1.188 + */
1.189 + virtual RWriteStream& ContentWriteStreamL() = 0;
1.190 +
1.191 + /**
1.192 + * Checks if element matches to another element
1.193 + * by it's content and child elements. Element
1.194 + * can contain more data than the given pattern.
1.195 + * @since Series60 3.0
1.196 + * @param aCandidate The pattern to be matched. Must contain
1.197 + * same or less data for match to come true.
1.198 + * @return ETrue if content and possible children match exactly
1.199 + * to given pattern. EFalse otherwise.
1.200 + */
1.201 + virtual TBool ConsistsOfL(MSenElement& aCandidate) = 0;
1.202 +
1.203 + /**
1.204 + * Get a list of direct children element that have the given
1.205 + * name and namespace.
1.206 + * @since Series60 3.0
1.207 + * @param aElementArray RPointerArray that will hold matching elements
1.208 + * @param namespaceURI
1.209 + * @param localName
1.210 + * @return KErrNone or some system-wide error code,
1.211 + * if an error has occurred.
1.212 + */
1.213 + virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
1.214 + const TDesC8& aNsUri,
1.215 + const TDesC8& aLocalName) = 0;
1.216 +
1.217 + /**
1.218 + * Get a list of direct children element that have the given
1.219 + * name and same namespace as this parent Element.
1.220 + * @since Series60 3.0
1.221 + * @param aElementArray RPointerArray that will hold matching elements
1.222 + * @param localName
1.223 + * @return KErrNone or some system-wide error code,
1.224 + * if an error has occurred.
1.225 + */
1.226 + virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
1.227 + const TDesC8& aLocalName) = 0;
1.228 +
1.229 + /**
1.230 + * @since Series60 3.0
1.231 + * @return an array of child elements. This is an empty array if there
1.232 + * are no children. Any modifications made on the returned array modify
1.233 + * the element object.
1.234 + */
1.235 + virtual RPointerArray<CSenElement>& ElementsL() = 0;
1.236 +
1.237 + /**
1.238 + * Adds a namespace declaration.
1.239 + * If this element (or its parent if parameter aCheckInParent is ETrue)
1.240 + * already has a namespace with the same prefix and URI the given
1.241 + * namespace is not added.
1.242 + * @since Series60 3.0
1.243 + * @param aNewNamespace
1.244 + * @param aCheckInParent
1.245 + * @return the added Namespace, or the equivalent pre-existing one.
1.246 + */
1.247 + virtual const CSenNamespace* AddNamespaceL(CSenNamespace& aNewNamespace,
1.248 + TBool aCheckInParent) = 0;
1.249 +
1.250 + /**
1.251 + * Gets the value of the given attribute.
1.252 + * @since Series60 3.0
1.253 + * @param aName: Name of the attribute in question.
1.254 + * @return the value of the attribute, or NULL if not found.
1.255 + * Ownership is not transferred to caller.
1.256 + */
1.257 + virtual const TDesC8* AttrValue(const TDesC8& aName) = 0;
1.258 +
1.259 + /**
1.260 + * Adds an attribute. If attribute is already existing,
1.261 + * the value of the attribute will be replaced.
1.262 + * @since Series60 3.0
1.263 + * @param aName Name of the attribute to be added.
1.264 + * @param aValue Value of the attribute to be added.
1.265 + */
1.266 + virtual void AddAttrL(const TDesC8& aName, const TDesC8& aValue) = 0;
1.267 +
1.268 + /**
1.269 + * Gets all the attributes of this element in an array.
1.270 + * @since Series60 3.0
1.271 + * @return array of attributes. Array will be empty if element has
1.272 + * no attributes.
1.273 + */
1.274 + virtual RPointerArray<CSenBaseAttribute>& AttributesL() = 0;
1.275 +
1.276 + /**
1.277 + * Gets all the namespaces of this element in an array.
1.278 + * @since Series60 3.0
1.279 + * @return array of namespaces. Array will be empty if element has
1.280 + * no namespaces.
1.281 + */
1.282 + virtual RPointerArray<CSenNamespace>& NamespacesL() = 0;
1.283 +
1.284 + /**
1.285 + * Gets the parent element of this element.
1.286 + * @since Series60 3.0
1.287 + * @return the parent element or NULL if no parent set.
1.288 + * Ownership is NOT transferred to the caller.
1.289 + */
1.290 + virtual CSenElement* Parent() = 0;
1.291 +
1.292 + /**
1.293 + * From MSenElement Sets the parent element to this element.
1.294 + * Notice that the element is not automatically added as a
1.295 + * child of the parent. Parent's AddElementL() must be called
1.296 + * to achieve that.
1.297 + *
1.298 + * @since Series60 3.0
1.299 + * @param apParent: The wanted parent. Can be NULL.
1.300 + * @return the parent element
1.301 + */
1.302 + virtual CSenElement* SetParent(CSenElement* apParent) = 0;
1.303 +
1.304 + /**
1.305 + * Detach the element from its parent.
1.306 + * If the element, or one of its children, is dependent
1.307 + * on a namespace declared in the scope of the parent
1.308 + * copy those namespace declarations to this element.
1.309 + * @since Series60 3.0
1.310 + * @return this Element. Ownership is NOT transferred to the caller.
1.311 + * or NULL if no parent was set, and nothing was detached.
1.312 + */
1.313 + virtual CSenElement* DetachL() = 0;
1.314 +
1.315 + /**
1.316 + * Gets a child element from a specified index.
1.317 + * @since Series60 3.0
1.318 + * @param aIndex: the index what to get
1.319 + * @return child element from a current index. NULL if no child in given
1.320 + * index is found
1.321 + */
1.322 + virtual CSenElement* Child(TInt aIndex) = 0;
1.323 +
1.324 + /**
1.325 + * Gets the root element. If no parent element, returns this element.
1.326 + * @since Series60 3.0
1.327 + * @return the root of the tree. Ownership is not transferred.
1.328 + */
1.329 + virtual MSenElement& Root() = 0;
1.330 +
1.331 + /**
1.332 + * Gets the child element with the specified local name.
1.333 + * Assumes that namespace is the same as this parent element.
1.334 + * @since Series60 3.0
1.335 + * @param aLocalName is the XML localname of the requested child element
1.336 + * @return the child element or NULL if the child with the specified
1.337 + * local name is not found. Ownership is NOT transferred.
1.338 + */
1.339 + virtual CSenElement* Element(const TDesC8& aLocalName) = 0;
1.340 +
1.341 + /**
1.342 + * Gets the child element with the specified local name and namespace URI.
1.343 + * @since Series60 3.0
1.344 + * @param aNsUri is the XML namespace of the requested child element
1.345 + * @param aLocalName is the XML localname of the requested child element
1.346 + * @return the child element or NULL if the child with the specified
1.347 + * criterias is not found. Ownership is NOT transferred.
1.348 + */
1.349 + virtual CSenElement* Element(const TDesC8& aNsUri,
1.350 + const TDesC8& aLocalName) = 0;
1.351 +
1.352 + /**
1.353 + * Create a new element ready for adding or insertion.
1.354 + * If the given namespace prefix is not declared yet
1.355 + * the element will not be created and NULL will be returned.
1.356 + * @since Series60 3.0
1.357 + * @param aNsPrefix: The namespace prefix
1.358 + * @param aLocalName: The new elements localname
1.359 + * @return the new Element just created, or NULL if given prefix was not
1.360 + * declared yet. Ownership is transferred to the caller.
1.361 + * Leave codes:
1.362 + * KErrSenInvalidCharacters if aLocalName contain illegal characters.
1.363 + * KErrSenZeroLengthDescriptor if aLocalName is zero length.
1.364 + */
1.365 + virtual CSenElement* CreateElementL(const TDesC8& aNsPrefix,
1.366 + const TDesC8& aLocalName) = 0;
1.367 +
1.368 + /**
1.369 + * Insert an Element into the list of children elements
1.370 + * so that the inserted Element is placed right before the aBeforeElement.
1.371 + * If aBeforeElement is not found, element will be appended to the last
1.372 + * position.
1.373 + * Function leaves if error occurs in inserting.
1.374 + * @since Series60 3.0
1.375 + * @param aInsertedElement the element to be inserted.
1.376 + * Ownership is transferred.
1.377 + * @param aBeforeElement the element which will be right next to the
1.378 + * element just inserted.
1.379 + * @return the inserted Element
1.380 + */
1.381 + virtual CSenElement& InsertElementL(CSenElement& aInsertedElement,
1.382 + const CSenElement& aBeforeElement) = 0;
1.383 +
1.384 + /**
1.385 + * Adds an Element to the children elements.
1.386 + * Sets this element to be the new parent of the given element.
1.387 + * @since Series60 3.0
1.388 + * @param aElement: the element to be added. Ownership is transferred.
1.389 + * @return the added Element
1.390 + */
1.391 + virtual CSenElement& AddElementL(CSenElement& aElement) = 0;
1.392 +
1.393 + /**
1.394 + * Constructs and adds a new element to the children elements.
1.395 + * Sets this element to be the new parent of the given element.
1.396 + * @since Series60 3.0
1.397 + * @param aNsUri namespace URI of the new element
1.398 + * @param aLocalName local name of the new element
1.399 + * @return the added Element
1.400 + * Leave codes:
1.401 + * KErrSenInvalidCharacters if aLocalName contains illegal characters.
1.402 + * KErrSenZeroLengthDescriptor if aLocalName is zero length.
1.403 + */
1.404 + virtual CSenElement& AddElementL( const TDesC8& aNsUri,
1.405 + const TDesC8& aLocalName) = 0;
1.406 +
1.407 + /**
1.408 + * Constructs and adds a new element to the children elements.
1.409 + * Sets this element to be the new parent of the given element.
1.410 + * @since Series60 3.0
1.411 + * @param aNsUri namespace URI of the new element
1.412 + * @param aLocalName local name of the new element
1.413 + * @param aQName qualified name of the new element
1.414 + * @return the added Element
1.415 + * Leave codes:
1.416 + * KErrSenInvalidCharacters if aLocalName or aQName contain illegal
1.417 + * characters.
1.418 + *
1.419 + * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero
1.420 + * length.
1.421 + */
1.422 + virtual CSenElement& AddElementL(const TDesC8& aNsUri,
1.423 + const TDesC8& aLocalName,
1.424 + const TDesC8& aQName) = 0;
1.425 +
1.426 + /**
1.427 + * Constructs and adds a new element to the children elements.
1.428 + * Sets this element to be the new parent of the given element.
1.429 + * Note: Element is created with no specific namespace, default namespace
1.430 + * of some of the upper level elements are in effect if there is such a
1.431 + * namespace.
1.432 + * @since Series60 3.0
1.433 + * @param aLocalName local name of the new element
1.434 + * @return the added Element
1.435 + * Leave codes:
1.436 + * KErrSenInvalidCharacters if aLocalName contains illegal
1.437 + * characters.
1.438 + *
1.439 + * KErrSenZeroLengthDescriptor if aLocalName is zero length.
1.440 + */
1.441 + virtual CSenElement& AddElementL(const TDesC8& aLocalName) = 0;
1.442 +
1.443 + /**
1.444 + * Remove an element from the childs.
1.445 + * @since Series60 3.0
1.446 + * @param aElement: the element to be removed.
1.447 + * @return The removed element. May be NULL if nothing was removed
1.448 + * (if child element was not found).
1.449 + * The caller TAKES OWNERSHIP of the removed element.
1.450 + */
1.451 + virtual CSenElement* RemoveElement(CSenElement& aElement) = 0;
1.452 +
1.453 + /**
1.454 + * Remove an element from the childs.
1.455 + * @since Series60 3.0
1.456 + * @param aNsUri: the namespace URI of the element to be removed.
1.457 + * @param aLocalName: the local name of the element to be removed.
1.458 + * @return The removed element. May be NULL if nothing was removed
1.459 + * (if child element was not found).
1.460 + * The caller TAKES OWNERSHIP of the removed element.
1.461 + */
1.462 + virtual CSenElement* RemoveElement( const TDesC8& aNsUri,
1.463 + const TDesC8& aLocalName) = 0;
1.464 +
1.465 + /**
1.466 + * Remove a child element.
1.467 + * @since Series60 3.0
1.468 + * @param aLocalName: the local name of the element to be removed.
1.469 + * @return The removed element. May be NULL if nothing was removed
1.470 + * (if child element was not found).
1.471 + *
1.472 + * The caller takes ownership of the removed element.
1.473 + */
1.474 + virtual CSenElement* RemoveElement(const TDesC8& aLocalName) = 0;
1.475 +
1.476 + /**
1.477 + * Replaces a child element with another element.
1.478 + * Element's local name and namespace URI will be used to check
1.479 + * whether or not that element matches with any existing child.
1.480 + * If no matching child element is found this method will add a
1.481 + * new child element.
1.482 + *
1.483 + * @since Series60 3.0
1.484 + * @param aElement: the element to be added. Ownership is transferred.
1.485 + * @return The old element. May be NULL if nothing was replaced
1.486 + * (if element was not found from the childs).
1.487 + * The caller TAKES OWNERSHIP of the old element.
1.488 + */
1.489 + virtual CSenElement* ReplaceElementL(CSenElement& aElement) = 0;
1.490 +
1.491 + /**
1.492 + * Gets the element as an XML buffer. Buffer will
1.493 + * contain all the child elements.
1.494 + * @since Series60 3.0
1.495 + * @return element as XML. Caller takes ownership.
1.496 + */
1.497 + virtual HBufC8* AsXmlL() = 0;
1.498 +
1.499 + /**
1.500 + * Gets the element as an unicode (UCS2) XML buffer.
1.501 + * Buffer will contain all the child elements.
1.502 + * @since Series60 3.0
1.503 + * @return element as XML. Caller takes ownership.
1.504 + */
1.505 + virtual HBufC* AsXmlUnicodeL() = 0;
1.506 +
1.507 + /**
1.508 + * Element writes itself to a write stream using UTF-8
1.509 + * character-set encoding.
1.510 + * @since Series60 3.0
1.511 + * @param aWriteStream The stream to write to.
1.512 + */
1.513 + virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;
1.514 +
1.515 + /**
1.516 + * Element writes its namespaces to a write stream
1.517 + * using UTF-8 character-set encoding.
1.518 + * @since Series60 3.0
1.519 + * @param aWriteStream The stream to write to.
1.520 + */
1.521 + virtual void WriteNamespacesToL(RWriteStream& aWriteStream) = 0;
1.522 +
1.523 + /**
1.524 + * Offers the M-class interface pointer to this XML
1.525 + * element.
1.526 + * @since Series60 3.0
1.527 + * @return the current object as element. Ownership is NOT transferred.
1.528 + */
1.529 + virtual MSenElement* AsElement() = 0;
1.530 +
1.531 + /**
1.532 + * Copies content from given element to this element appending to the
1.533 + * existing content if there is any.
1.534 + * @since Series60 3.0
1.535 + * @param aSource The source element.
1.536 + */
1.537 + virtual void CopyFromL(CSenElement& aSource) = 0;
1.538 +
1.539 + /**
1.540 + * (Re-) Set the name and namespace of this Element. The element will be
1.541 + * given the localName in the the given namespace. A prefix will be
1.542 + * computed from the qualified name.
1.543 + * This method should be used with care and is mainly intended for
1.544 + * protected use in implementations.
1.545 + * @since Series60 3.0
1.546 + * @param aNamespaceURI The new namespace URI.
1.547 + * @param aLocalName The new local name.
1.548 + * @param aQName The new qualified name.
1.549 + */
1.550 + virtual void Set(const TDesC8& aNamespaceURI, const TDesC8& aLocalName, const TDesC8& aQName) = 0;
1.551 +
1.552 + /**
1.553 + * Adds new attributes to the element.
1.554 + * @since Series60 3.0
1.555 + * @param aAttrs: the array of attributes.
1.556 + */
1.557 + virtual void AddAttributesL(const RAttributeArray& apAttrs) = 0;
1.558 + };
1.559 +
1.560 +#endif //SEN_ELEMENT_H
1.561 +
1.562 +// End of File
1.563 +