2 * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Central place for debug-type macros
31 #include <xml/attribute.h>
32 #include <stringpool.h>
34 #include <MSenElement.h>
41 * Abstract class definition of XML element
45 class CSenElement : public CBase, public MSenElement
47 public: // Functions from base classes
52 * Getter for local name.
54 * @return KNullDesC if not set (argumentless constructor).
56 virtual const TDesC8& LocalName() const = 0;
59 * Getter for namespace URI.
61 * @return KNullDesC if not set.
63 virtual const TDesC8& NamespaceURI() const = 0;
66 * Setter for Element's namespace URI.
68 * @param @param aNsUri: Namespace URI
70 virtual void SetNamespaceL(const TDesC8& aNsUri) = 0;
73 * Setter for Element's namespace URI.
75 * @param aNsPrefix: Namespace prefix
76 * @param aNsUri: Namespace URI
78 virtual void SetNamespaceL( const TDesC8& aNsPrefix,
79 const TDesC8& aNsUri) = 0;
82 * Method for adding a namespace for the Element.
84 * @param aPrefix: Namespace prefix
85 * @param aUri: Namespace URI
86 * @return the added Namespace, or the equivalent pre-existing one.
88 virtual const CSenNamespace* AddNamespaceL( const TDesC8& aPrefix,
89 const TDesC8& aUri) = 0;
92 * Getter for Element's namespace.
94 * @return const pointer to the CSenNamespace object of this Element.
95 * Returns NULL, if not set.
97 virtual const CSenNamespace* Namespace() = 0;
100 * @since Series60 3.0
102 * @return the namespace that is declared for the given prefix
103 * within the scope of this Element. If no such prefix is
104 * declared return NULL.
106 virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix) = 0;
109 * Get namespace that is declared for the given prefix and namespace
110 * URI within the scope of this element.
111 * @since Series60 3.0
112 * @param aNsPrefix The prefix used to search
113 * @param aUri The namespace URI used to search.
114 * @return the found namespace that is declared for the given prefix
115 * and namespace URI within the scope of this Element
116 * or NULL if not found.
118 virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
119 const TDesC8& aUri) = 0;
122 * @since Series60 3.0
123 * @param aNsPrefix The prefix used to search
124 * @param aCheckInParent The flag indicating whether to check parent's
125 * namespaces too if not found in the current
127 * ETrue to check, EFalse for not to check.
128 * @return the found Namespace that is declared for the given prefix
129 * and namespace URI within the scope of this Element
130 * or NULL if not found
132 virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
133 const TBool aCheckInParent) = 0;
136 * Getter for namespace prefix of this element.
137 * @since Series60 3.0
138 * @return namespace prefix or KNullDesC8 if not set.
140 virtual const TDesC8& NsPrefix() const = 0;
143 * Setter for namespace prefix of this element.
144 * @since Series60 3.0
145 * @param aPrefix: new namespace prefix for the element.
147 virtual void SetPrefixL(const TDesC8& aPrefix) = 0;
150 * Method for checking if the element has any content within.
151 * @since Series60 3.0
152 * @return ETrue if has content, EFalse if not.
154 virtual TBool HasContent() const = 0;
157 * Getter for the content of the element.
158 * @since Series60 3.0
159 * @return the content or KNullDesC8 if empty.
161 virtual TPtrC8 Content() const = 0;
164 * Getter for the content of the element, Unicode (UCS2) version
165 * @since Series60 3.0
166 * @return content as Unicode. Ownership is transferred to the caller.
168 virtual HBufC* ContentUnicodeL() const = 0;
171 * Sets the content to the element. Old content is overwritten.
172 * @since Series60 3.0
173 * @param aContent The content to be set. Can be KNullDesC8.
174 * @return The content of the element or KNullDesC8 if no content was set.
176 virtual TPtrC8 SetContentL(const TDesC8& aContent) = 0;
179 * Gets the write stream for the content for easy appending.
180 * Writing 8-bit (UTF-8) string to the returned stream will be appended
182 * @since Series60 3.0
183 * @return reference to the RWriteStream.
185 virtual RWriteStream& ContentWriteStreamL() = 0;
188 * Checks if element matches to another element
189 * by it's content and child elements. Element
190 * can contain more data than the given pattern.
191 * @since Series60 3.0
192 * @param aCandidate The pattern to be matched. Must contain
193 * same or less data for match to come true.
194 * @return ETrue if content and possible children match exactly
195 * to given pattern. EFalse otherwise.
197 virtual TBool ConsistsOfL(MSenElement& aCandidate) = 0;
200 * Get a list of direct children element that have the given
201 * name and namespace.
202 * @since Series60 3.0
203 * @param aElementArray RPointerArray that will hold matching elements
204 * @param namespaceURI
206 * @return KErrNone or some system-wide error code,
207 * if an error has occurred.
209 virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
210 const TDesC8& aNsUri,
211 const TDesC8& aLocalName) = 0;
214 * Get a list of direct children element that have the given
215 * name and same namespace as this parent Element.
216 * @since Series60 3.0
217 * @param aElementArray RPointerArray that will hold matching elements
219 * @return KErrNone or some system-wide error code,
220 * if an error has occurred.
222 virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
223 const TDesC8& aLocalName) = 0;
226 * @since Series60 3.0
227 * @return an array of child elements. This is an empty array if there
228 * are no children. Any modifications made on the returned array modify
229 * the element object.
231 virtual RPointerArray<CSenElement>& ElementsL() = 0;
234 * Adds a namespace declaration.
235 * If this element (or its parent if parameter aCheckInParent is ETrue)
236 * already has a namespace with the same prefix and URI the given
237 * namespace is not added.
238 * @since Series60 3.0
239 * @param aNewNamespace
240 * @param aCheckInParent
241 * @return the added Namespace, or the equivalent pre-existing one.
243 virtual const CSenNamespace* AddNamespaceL(CSenNamespace& aNewNamespace,
244 TBool aCheckInParent) = 0;
247 * Gets the value of the given attribute.
248 * @since Series60 3.0
249 * @param aName: Name of the attribute in question.
250 * @return the value of the attribute, or NULL if not found.
251 * Ownership is not transferred to caller.
253 virtual const TDesC8* AttrValue(const TDesC8& aName) = 0;
256 * Adds an attribute. If attribute is already existing,
257 * the value of the attribute will be replaced.
258 * @since Series60 3.0
259 * @param aName Name of the attribute to be added.
260 * @param aValue Value of the attribute to be added.
262 virtual void AddAttrL(const TDesC8& aName, const TDesC8& aValue) = 0;
265 * Gets all the attributes of this element in an array.
266 * @since Series60 3.0
267 * @return array of attributes. Array will be empty if element has
270 virtual RPointerArray<CSenBaseAttribute>& AttributesL() = 0;
273 * Gets all the namespaces of this element in an array.
274 * @since Series60 3.0
275 * @return array of namespaces. Array will be empty if element has
278 virtual RPointerArray<CSenNamespace>& NamespacesL() = 0;
281 * Gets the parent element of this element.
282 * @since Series60 3.0
283 * @return the parent element or NULL if no parent set.
284 * Ownership is NOT transferred to the caller.
286 virtual CSenElement* Parent() = 0;
289 * From MSenElement Sets the parent element to this element.
290 * Notice that the element is not automatically added as a
291 * child of the parent. Parent's AddElementL() must be called
294 * @since Series60 3.0
295 * @param apParent: The wanted parent. Can be NULL.
296 * @return the parent element
298 virtual CSenElement* SetParent(CSenElement* apParent) = 0;
301 * Detach the element from its parent.
302 * If the element, or one of its children, is dependent
303 * on a namespace declared in the scope of the parent
304 * copy those namespace declarations to this element.
305 * @since Series60 3.0
306 * @return this Element. Ownership is NOT transferred to the caller.
307 * or NULL if no parent was set, and nothing was detached.
309 virtual CSenElement* DetachL() = 0;
312 * Gets a child element from a specified index.
313 * @since Series60 3.0
314 * @param aIndex: the index what to get
315 * @return child element from a current index. NULL if no child in given
318 virtual CSenElement* Child(TInt aIndex) = 0;
321 * Gets the root element. If no parent element, returns this element.
322 * @since Series60 3.0
323 * @return the root of the tree. Ownership is not transferred.
325 virtual MSenElement& Root() = 0;
328 * Gets the child element with the specified local name.
329 * Assumes that namespace is the same as this parent element.
330 * @since Series60 3.0
331 * @param aLocalName is the XML localname of the requested child element
332 * @return the child element or NULL if the child with the specified
333 * local name is not found. Ownership is NOT transferred.
335 virtual CSenElement* Element(const TDesC8& aLocalName) = 0;
338 * Gets the child element with the specified local name and namespace URI.
339 * @since Series60 3.0
340 * @param aNsUri is the XML namespace of the requested child element
341 * @param aLocalName is the XML localname of the requested child element
342 * @return the child element or NULL if the child with the specified
343 * criterias is not found. Ownership is NOT transferred.
345 virtual CSenElement* Element(const TDesC8& aNsUri,
346 const TDesC8& aLocalName) = 0;
349 * Create a new element ready for adding or insertion.
350 * If the given namespace prefix is not declared yet
351 * the element will not be created and NULL will be returned.
352 * @since Series60 3.0
353 * @param aNsPrefix: The namespace prefix
354 * @param aLocalName: The new elements localname
355 * @return the new Element just created, or NULL if given prefix was not
356 * declared yet. Ownership is transferred to the caller.
358 * KErrSenInvalidCharacters if aLocalName contain illegal characters.
359 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
361 virtual CSenElement* CreateElementL(const TDesC8& aNsPrefix,
362 const TDesC8& aLocalName) = 0;
365 * Insert an Element into the list of children elements
366 * so that the inserted Element is placed right before the aBeforeElement.
367 * If aBeforeElement is not found, element will be appended to the last
369 * Function leaves if error occurs in inserting.
370 * @since Series60 3.0
371 * @param aInsertedElement the element to be inserted.
372 * Ownership is transferred.
373 * @param aBeforeElement the element which will be right next to the
374 * element just inserted.
375 * @return the inserted Element
377 virtual CSenElement& InsertElementL(CSenElement& aInsertedElement,
378 const CSenElement& aBeforeElement) = 0;
381 * Adds an Element to the children elements.
382 * Sets this element to be the new parent of the given element.
383 * @since Series60 3.0
384 * @param aElement: the element to be added. Ownership is transferred.
385 * @return the added Element
387 virtual CSenElement& AddElementL(CSenElement& aElement) = 0;
390 * Constructs and adds a new element to the children elements.
391 * Sets this element to be the new parent of the given element.
392 * @since Series60 3.0
393 * @param aNsUri namespace URI of the new element
394 * @param aLocalName local name of the new element
395 * @return the added Element
397 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
398 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
400 virtual CSenElement& AddElementL( const TDesC8& aNsUri,
401 const TDesC8& aLocalName) = 0;
404 * Constructs and adds a new element to the children elements.
405 * Sets this element to be the new parent of the given element.
406 * @since Series60 3.0
407 * @param aNsUri namespace URI of the new element
408 * @param aLocalName local name of the new element
409 * @param aQName qualified name of the new element
410 * @return the added Element
412 * KErrSenInvalidCharacters if aLocalName or aQName contain illegal
415 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero
418 virtual CSenElement& AddElementL(const TDesC8& aNsUri,
419 const TDesC8& aLocalName,
420 const TDesC8& aQName) = 0;
423 * Constructs and adds a new element to the children elements.
424 * Sets this element to be the new parent of the given element.
425 * Note: Element is created with no specific namespace, default namespace
426 * of some of the upper level elements are in effect if there is such a
428 * @since Series60 3.0
429 * @param aLocalName local name of the new element
430 * @return the added Element
432 * KErrSenInvalidCharacters if aLocalName contains illegal
435 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
437 virtual CSenElement& AddElementL(const TDesC8& aLocalName) = 0;
440 * Remove an element from the childs.
441 * @since Series60 3.0
442 * @param aElement: the element to be removed.
443 * @return The removed element. May be NULL if nothing was removed
444 * (if child element was not found).
445 * The caller TAKES OWNERSHIP of the removed element.
447 virtual CSenElement* RemoveElement(CSenElement& aElement) = 0;
450 * Remove an element from the childs.
451 * @since Series60 3.0
452 * @param aNsUri: the namespace URI of the element to be removed.
453 * @param aLocalName: the local name of the element to be removed.
454 * @return The removed element. May be NULL if nothing was removed
455 * (if child element was not found).
456 * The caller TAKES OWNERSHIP of the removed element.
458 virtual CSenElement* RemoveElement( const TDesC8& aNsUri,
459 const TDesC8& aLocalName) = 0;
462 * Remove a child element.
463 * @since Series60 3.0
464 * @param aLocalName: the local name of the element to be removed.
465 * @return The removed element. May be NULL if nothing was removed
466 * (if child element was not found).
468 * The caller takes ownership of the removed element.
470 virtual CSenElement* RemoveElement(const TDesC8& aLocalName) = 0;
473 * Replaces a child element with another element.
474 * Element's local name and namespace URI will be used to check
475 * whether or not that element matches with any existing child.
476 * If no matching child element is found this method will add a
479 * @since Series60 3.0
480 * @param aElement: the element to be added. Ownership is transferred.
481 * @return The old element. May be NULL if nothing was replaced
482 * (if element was not found from the childs).
483 * The caller TAKES OWNERSHIP of the old element.
485 virtual CSenElement* ReplaceElementL(CSenElement& aElement) = 0;
488 * Gets the element as an XML buffer. Buffer will
489 * contain all the child elements.
490 * @since Series60 3.0
491 * @return element as XML. Caller takes ownership.
493 virtual HBufC8* AsXmlL() = 0;
496 * Gets the element as an unicode (UCS2) XML buffer.
497 * Buffer will contain all the child elements.
498 * @since Series60 3.0
499 * @return element as XML. Caller takes ownership.
501 virtual HBufC* AsXmlUnicodeL() = 0;
504 * Element writes itself to a write stream using UTF-8
505 * character-set encoding.
506 * @since Series60 3.0
507 * @param aWriteStream The stream to write to.
509 virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;
512 * Element writes its namespaces to a write stream
513 * using UTF-8 character-set encoding.
514 * @since Series60 3.0
515 * @param aWriteStream The stream to write to.
517 virtual void WriteNamespacesToL(RWriteStream& aWriteStream) = 0;
520 * Offers the M-class interface pointer to this XML
522 * @since Series60 3.0
523 * @return the current object as element. Ownership is NOT transferred.
525 virtual MSenElement* AsElement() = 0;
528 * Copies content from given element to this element appending to the
529 * existing content if there is any.
530 * @since Series60 3.0
531 * @param aSource The source element.
533 virtual void CopyFromL(CSenElement& aSource) = 0;
536 * (Re-) Set the name and namespace of this Element. The element will be
537 * given the localName in the the given namespace. A prefix will be
538 * computed from the qualified name.
539 * This method should be used with care and is mainly intended for
540 * protected use in implementations.
541 * @since Series60 3.0
542 * @param aNamespaceURI The new namespace URI.
543 * @param aLocalName The new local name.
544 * @param aQName The new qualified name.
546 virtual void Set(const TDesC8& aNamespaceURI, const TDesC8& aLocalName, const TDesC8& aQName) = 0;
549 * Adds new attributes to the element.
550 * @since Series60 3.0
551 * @param aAttrs: the array of attributes.
553 virtual void AddAttributesL(const RAttributeArray& apAttrs) = 0;
556 #endif //SEN_ELEMENT_H