2 * Copyright (c) 2002-2006 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: Class implements XML base fragment using libxml2 classes
26 #ifndef SEN_FRAGMENT_BASE_H
27 #define SEN_FRAGMENT_BASE_H
32 #include <xml/contenthandler.h>
33 #include <RSenDocument.h>
34 #include <SenParser.h>
35 #include <xmlengelement.h>
41 // Fragment's internal states.
42 const TInt KSenStateNotSet = -1;
43 const TInt KSenStateIgnore = 0;
44 const TInt KSenStateSave = 1;
45 const TInt KSenStateResume = 2;
46 const TInt KSenStateDelegate = 3;
48 // FORWARD DECLARATIONS
51 class CSenNamespaceData;
56 * Class implements basic functionality of an XML fragment
57 * Typically base fragment is used to parse certain part of some XML document.
58 * The element is identified by local name (or qualified name) and namespace.
59 * All child elements between start tag and and end tag defined this fragment
60 * will become content of this BaseFragment. In other words, BaseFragment has
61 * all data inside a single element.
62 * BaseFragment will parse only namespace (xmlns) attributes from a document
63 * and rest of the attributes are to be handled by subclasses, which should
64 * overwrite SetAttributesL() method to achieve this.
65 * The CSenFragmentReader class will do the actual parsing and this class will
66 * act as content handler for XML parser SAX events.
67 * @lib SenFragment.dll
70 class CSenFragmentBase : public CBase, public MContentHandler
72 friend class CSenParserImpl;
74 public: // Constructors and destructor
77 * Standard 2 phase constructor.
79 * @param aElement is the element where construction
80 * data will be copied from.
82 IMPORT_C static CSenFragmentBase* NewL(const TXmlEngElement& aElement);
85 * Standard 2 phase constructor.
87 * @param aLocalName: is the XML localname for this fragment
89 IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aLocalName);
92 * Standard 2 phase constructor.
94 * @param aNsUri: XML namespace URI
95 * @param aLocalName: XML localname
97 IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
98 const TDesC8& aLocalName);
101 * Standard 2 phase constructor.
102 * @since Series60 4.0
103 * @param aNsUri XML namespace URI
104 * @param aLocalName XML localname
105 * @param aPrefix XML prefix
107 IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
108 const TDesC8& aLocalName,
109 const TDesC8& aPrefix);
112 * Standard 2 phase constructor.
113 * @since Series60 4.0
114 * @param aNsUri XML namespace URI
115 * @param aLocalName XML localname
116 * @param aPrefix XML prefix
117 * @param apAttrs XML attributes
119 IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
120 const TDesC8& aLocalName,
121 const TDesC8& aPrefix,
122 const RAttributeArray& apAttrs);
125 * Standard 2 phase constructor.
126 * @param aParent Element to be set as fragment's parent element.
127 * @since Series60 4.0
128 * @param aNsUri XML namespace URI
129 * @param aLocalName XML localname
130 * @param aPrefix XML prefix
131 * @param apAttrs XML attributes
132 * @param aParent Parent element
134 IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
135 const TDesC8& aLocalName,
136 const TDesC8& aPrefix,
137 const RAttributeArray& apAttrs,
138 TXmlEngElement& aParent);
141 * Standard 2 phase constructor.
142 * @param aParent Element to be set as fragment's parent element.
143 * @since Series60 4.0
144 * @param aNsUri XML namespace URI
145 * @param aLocalName XML localname
146 * @param aPrefix XML prefix
147 * @param apAttrs XML attributes
148 * @param aParent Parent element
149 * @param aOwnerDocument The document which will be the owner of
150 * the elements of this fragment
152 IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
153 const TDesC8& aLocalName,
154 const TDesC8& aPrefix,
155 const RAttributeArray& apAttrs,
156 TXmlEngElement& aParent,
157 RSenDocument& aOwnerDocument);
160 * Standard 2 phase constructor.
161 * @param aParent Element to be set as fragment's parent element.
162 * @since Series60 4.0
163 * @param aRootElement The element which will be the root element
165 * @param aOwnerDocument The document which will be the owner of
166 * the elements of this fragment
168 IMPORT_C static CSenFragmentBase* NewL(TXmlEngElement& aRootElement,
169 RSenDocument& aOwnerDocument);
174 IMPORT_C virtual ~CSenFragmentBase();
176 // Functions from base classes
178 // From MContentHandler:
181 * Callback function implementing the XML content handler interface.
182 * Inheriting classes can override these.
183 * @since Series60 3.1
184 * @see MContentHandler
186 IMPORT_C virtual void OnStartElementL(const RTagInfo& aElement, const RAttributeArray& aAttributes, TInt aErrorCode);
189 * Callback function implementing the XML content handler interface.
190 * Inheriting classes can override these.
191 * @since Series60 3.1
192 * @see MContentHandler
194 IMPORT_C virtual void OnEndElementL(const RTagInfo& aElement, TInt aErrorCode);
197 * Callback function implementing the XML content handler interface.
198 * Inheriting classes can override these.
199 * @since Series60 3.1
200 * @see MContentHandler
202 IMPORT_C virtual void OnStartDocumentL(const RDocumentParameters& aDocParam, TInt aErrorCode);
205 * Callback function implementing the XML content handler interface.
206 * Inheriting classes can override these.
207 * @since Series60 3.1
208 * @see MContentHandler
210 IMPORT_C virtual void OnEndDocumentL(TInt aErrorCode);
213 * Callback function implementing the XML content handler interface.
214 * Inheriting classes can override these.
215 * @since Series60 3.1
216 * @see MContentHandler
218 IMPORT_C virtual void OnContentL(const TDesC8& aBytes, TInt aErrorCode);
221 * Callback function implementing the XML content handler interface.
222 * Inheriting classes can override these.
223 * @since Series60 3.1
224 * @see MContentHandler
226 IMPORT_C virtual void OnStartPrefixMappingL(const RString& aPrefix, const RString& aUri, TInt aErrorCode);
229 * Callback function implementing the XML content handler interface.
230 * Inheriting classes can override these.
231 * @since Series60 3.1
232 * @see MContentHandler
234 IMPORT_C virtual void OnEndPrefixMappingL(const RString& aPrefix, TInt aErrorCode);
237 * Callback function implementing the XML content handler interface.
238 * Inheriting classes can override these.
239 * @since Series60 3.1
240 * @see MContentHandler
242 IMPORT_C virtual void OnIgnorableWhiteSpaceL(const TDesC8& aBytes, TInt ErrorCode);
245 * Callback function implementing the XML content handler interface.
246 * Inheriting classes can override these.
247 * @since Series60 3.1
248 * @see MContentHandler
250 IMPORT_C virtual void OnSkippedEntityL(const RString& aName, TInt aErrorCode);
253 * Callback function implementing the XML content handler interface.
254 * Inheriting classes can override these.
255 * @since Series60 3.1
256 * @see MContentHandler
258 IMPORT_C virtual void OnProcessingInstructionL(const TDesC8& aTarget, const TDesC8& aData, TInt aErrorCode);
261 * Callback function implementing the XML content handler interface.
262 * Inheriting classes can override these.
263 * @since Series60 3.1
264 * @see MContentHandler
266 IMPORT_C virtual void OnError(TInt aErrorCode);
269 * Callback function implementing the XML content handler interface.
270 * Inheriting classes can override these.
271 * @since Series60 3.1
272 * @see MContentHandler
274 IMPORT_C virtual TAny* GetExtendedInterface(const TInt32 aUid);
279 * Getter for the content,which is returned as UTF-8 form XML.
280 * @since Series60 4.0
281 * @return content as UTF-8 form XML.
283 IMPORT_C virtual TPtrC8 ContentL();
286 * Gets the namespace object with a given prefix.
287 * @since Series60 4.0
288 * @param aPrefix: prefix that wanted namespace should have.
289 * @return namespace with the given prefix. If not found or given prefix
290 * is zero length, will return NULL.
292 IMPORT_C virtual TXmlEngNamespace Namespace(const TDesC8& aPrefix);
295 * @since Series60 4.0
296 * @return Detaches this fragment from its owner. All namespace
297 * references from possible parent fragments are declared in
298 * the scope of this fragment prior detaching.
300 // IMPORT_C virtual void DetachL();
303 * Resets the content of the fragment, and resets the namespaces.
304 * @since Series60 4.0
306 IMPORT_C virtual void ResetContentL();
309 * @since Series60 4.0
310 * @return the localname of this fragment as UTF-8 form descriptor
312 IMPORT_C virtual TPtrC8 LocalName() const;
315 * Getter for Fragment's namespace URI..
316 * @since Series60 4.0
317 * @return Namespace URI or KNullDesC if not set.
319 IMPORT_C virtual TPtrC8 NsUri() const;
322 * Getter for namespace prefix of this fragment.
323 * @since Series60 4.0
324 * @return namespace prefix or KNullDesC if not set.
326 IMPORT_C virtual TPtrC8 NsPrefix() const;
329 * Returns the current XML element of this fragment. If element
330 * has not been set, this method will initialize new, un-initialized
332 * Method leaves with if there is not enough memory (OOM)
333 * @return reference to the element of this fragment
335 IMPORT_C virtual TXmlEngElement AsElementL();
338 * Returns the current XML element of this fragment. If element
339 * has not been set, this method will initialize new, un-initialized
341 * Method leaves with if there is not enough memory (OOM)
342 * @return reference to the element of this fragment
344 IMPORT_C virtual RSenDocument& AsDocumentL();
347 * Etracts the XML element from the fragment, leaving the fragment empty.
348 * Note(!): the return value (CSenElement) STRONGLY suggests that
349 * subclasses INHERIT CSenFragment in order properly comply the
350 * requirement of the ExtractElement() implementation.
351 * @since Series60 4.0
352 * @return the current object as element. May return NULL.
353 * Ownership IS TRANSFERRED to the caller.
355 IMPORT_C virtual TXmlEngElement ExtractElement();
358 * Let the delegate MSenFragment handle the following SAX events.
359 * This fragment is made the owner of the delegate and the delegate
360 * is expected to make this MSenFragment the receiver of SAX events
361 * once it has seen the end element for itself.
362 * @since Series60 4.0
363 * @param aDelegate is the fragment to start handling the SAX events.
365 IMPORT_C virtual void OnDelegateParsingL(CSenFragmentBase& aDelegate);
368 * Creates a new fragment and lets the created MSenFragment handle the
369 * following SAX events. This fragment is made the owner of the delegate
370 * and the delegate is expected to make this MSenFragment act as receiver
371 * for SAX events (callbacks) once it has seen the end element for itself.
372 * @since Series60 4.0
373 * @param aElement The RTagInfo class holding information that
374 * describes the element.
375 * @param aAttributes The attributes of the new element
376 * @param aErrorCode Error code
378 IMPORT_C virtual void OnDelegateParsingL(const RTagInfo& aElement,
379 const RAttributeArray& aAttributes,
383 * Sets a new parent for this fragment.
384 * @since Series60 4.0
385 * @param aFragment: the new parent.
387 IMPORT_C virtual void SetOwner(CSenFragmentBase& aFragment);
391 * Resumes parsing to be handled by this fragment. Usually called by some
392 * delegate fragment which was set to be content handler because this
393 * fragment called DelegateParsingL().
394 * @since Series60 4.0
395 * @param aElement The RTagInfo class holding information that
396 * describes the element.
397 * @param aErrorCode Error code
399 IMPORT_C virtual void OnResumeParsingFromL(const RTagInfo& aElement, TInt aErrorCode);
402 * Sets the attributes for the fragment. BaseFragment parses only
403 * namespace (xmlns) attributes from the document.
404 * Subclasses should override this method if they are intrested
405 * of handling any other XML attributes and their corresponding
407 * @since Series60 4.0
408 * @param aAttrs: the array of attributes.
410 // IMPORT_C virtual void SetAttributesL(const RAttributeArray& aAttrs);
413 * Writes the start element tag to the content stream.
414 * Derivants can override the basic usage used in BaseFragment.
415 * @since Series60 4.0
416 * @param aElement The RTagInfo class holding information that
417 * describes the element.
418 * @param aAttributes The attributes of the new element
420 IMPORT_C void OnWriteStartElementL(const RTagInfo& aElement,
421 const RAttributeArray& aAttributes);
424 * Writes the end element tag to the content stream.
425 * Derivants can override the basic usage used in BaseFragment.
426 * @since Series60 4.0
427 * @param aElement The RTagInfo class holding information that
428 * describes the element.
430 IMPORT_C void OnWriteEndElementL(const RTagInfo& aElement);
433 * Gets the fragment data as an unicode XML.
434 * @since Series60 4.0
435 * @return fragment as XML. Caller takes ownership.
437 IMPORT_C virtual HBufC* AsXmlUnicodeL();
440 * Gets the fragment data as an UTF-8 form XML.
441 * @since Series60 4.0
442 * @return fragment as XML. Caller takes ownership.
444 IMPORT_C virtual HBufC8* AsXmlL();
447 * Invokes AsElement().WriteAsXMLToL(aWs);
448 * @since Series60 4.0
449 * @param aWs is the stream into which the UTF-8 form XML will
452 IMPORT_C virtual void WriteAsXMLToL(RWriteStream& aWs);
455 * Checks if fragment matches to another fragment
456 * by its content and child elements.
457 * Fragment can contain more data than the given candidate.
458 * @since Series60 4.0
459 * @param aCandidate The pattern to be matched. Must contain same or
460 * less data for match to come true.
461 * @return ETrue if content and possible children match exactly
462 * to given pattern. EFalse otherwise.
464 IMPORT_C virtual TBool ConsistsOfL(CSenFragmentBase& aCandidate);
466 //From SenParserImpl.h
467 IMPORT_C void SetContentHandler(CSenFragmentBase& aContentHandler);
470 * Sets the RSenDocument
473 IMPORT_C void SetDocument(RSenDocument& aDocument);
478 * C++ default constructor.
480 IMPORT_C CSenFragmentBase();
483 * Following BaseConstructL methods should be called from ConstructL()
484 * methods of some deriving (fragment) class.
488 * BaseConstructL, where an element is given as initializer.
489 * @since Series60 4.0
490 * @param aElement from which this fragment will be constructed from.
492 IMPORT_C void BaseConstructL(const TXmlEngElement& aSrc);
495 * BaseConstructL setting XML localname for this fragment.
496 * @since Series60 4.0
497 * @param aLocalName XML localname for this fragment
499 IMPORT_C void BaseConstructL(const TDesC8& aLocalName);
502 * BaseConstructL offering possibility to set XML namespace and localname.
503 * @since Series60 4.0
504 * @param aNsUri XML namespace URI for this fragment
505 * @param aLocalName XML localname for this fragment
507 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
508 const TDesC8& aLocalName);
512 * @since Series60 4.0
513 * @param aNsUri XML namespace URI for this fragment
514 * @param aLocalName XML localname for this fragment
515 * @param aQName XML qualifiedname for this fragment
517 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
518 const TDesC8& aLocalName,
519 const TDesC8& aPrefix);
522 * @since Series60 4.0
523 * @param aNsUri XML namespace URI for this fragment
524 * @param aLocalName XML localname for this fragment
525 * @param aQName XML qualifiedname for this fragment
526 * @param aAttrs XML attributes for this fragment
528 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
529 const TDesC8& aLocalName,
530 const TDesC8& aPrefix,
531 const RAttributeArray& aAttrs);
535 * @since Series60 4.0
536 * @param aNsUri XML namespace URI for this fragment
537 * @param aLocalName XML localname for this fragment
538 * @param aQName XML qualifiedname for this fragment
539 * @param aAttrs XML attributes for this fragment
540 * @param aParent parent to be set for this fragmemt
542 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
543 const TDesC8& aLocalName,
544 const TDesC8& aPrefix,
545 const RAttributeArray& aAttrs,
546 TXmlEngElement& aParent);
550 * @since Series60 4.0
551 * @param aNsUri XML namespace URI for this fragment
552 * @param aLocalName XML localname for this fragment
553 * @param aQName XML qualifiedname for this fragment
554 * @param aAttrs XML attributes for this fragment
555 * @param aParent Parent to be set for this fragmemt
556 * @param aOwnerDocument The document which will be the owner of
557 * the elements of this fragment
559 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
560 const TDesC8& aLocalName,
561 const TDesC8& aPrefix,
562 const RAttributeArray& aAttrs,
563 TXmlEngElement& aParent,
564 RSenDocument& aOwnerDocument);
568 * @since Series60 4.0
569 * @param aRootElement The element which will be the root element
571 * @param aOwnerDocument The document which will be the owner of
572 * the elements of this fragment
574 IMPORT_C void BaseConstructL(TXmlEngElement& aRootElement,
575 RSenDocument& aOwnerDocument);
580 * Adds new XML attributes to this fragment.
581 * Can be overridden to replace old attributes.
582 * @param aAttrs: the array of attributes.
584 IMPORT_C virtual void AddAttributesL(const RAttributeArray& apAttrs);
587 * Adds new XML attributes to specified element.
588 * Can be overridden to replace old attributes.
589 * @param aAttrs: the array of attributes.
591 IMPORT_C virtual void AddAttributesToElementL(TXmlEngElement element,
592 const RAttributeArray& apAttrs);
595 * Method renames the XML properties of this fragment.
596 * @param aLocalName XML localname for this fragment
597 * @param aPrefix XML namespace prefix for this fragment
598 * @param aNamespace XML namespace URI for this fragment
599 * Method leaves with if there is not enough memory (OOM)
601 void RenameL(const TDesC8& aLocalName, const TDesC8& aPrefix, const TDesC8& aNamespace);
604 * Method renames the XML properties of this fragment.
605 * @param aLocalName XML localname for this fragment
606 * @param aNamespace XML namespace URI for this fragment
607 * Method leaves with if there is not enough memory (OOM)
609 void RenameL(const TDesC8& aLocalName, const TDesC8& aNamespace);
612 * Renames local name for this XML fragment.
613 * @param aLocalName XML localname for this fragment
614 * Method leaves with if there is not enough memory (OOM)
616 void RenameLocalNameL(const TDesC8& aLocalName);
619 * Renames namespace URI for this XML fragment.
620 * @param aNamespace XML namespace URI for this fragment
621 * Method leaves with if there is not enough memory(OOM)
623 void RenameNamespaceL(const TDesC8& aNamespace);
626 * Renames namespace prefix for this XML fragment.
627 * @param aPrefix XML namespace prefix for this fragment
628 * Method leaves with if there is not enough memory (OOM)
630 void RenamePrefixL(const TDesC8& aPrefix);
633 * Renames namespace prefix and namespace URI for this XML fragment.
634 * @param aPrefix XML namespace prefix for this fragment
635 * @param aNamespace XML namespace URI for this fragment
636 * Method leaves with if there is not enough memory (OOM)
638 void RenameNamespaceL(const TDesC8& aPrefix, const TDesC8& aNamespace);
641 * Sets content to a child element. If no element with given local name
642 * is not found, new one is added and content is set to that one.
643 * @since Series60 4.0
644 * @param aLocalName The local name of element which content
646 * @param aContent Content to be set.
647 * @return the element where content was set.
649 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
650 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
652 IMPORT_C TXmlEngElement SetContentOfL(const TDesC8& aLocalName,
653 const TDesC8& aContent);
655 * Gets the content of a given element.
656 * @since Series60 4.0
657 * @param aLocalName The local name of the element which content is
659 * @return the content which was asked
661 IMPORT_C TPtrC8 ContentOf(const TDesC8& aLocalName);
663 IMPORT_C virtual TBool ConsistsOfL(TXmlEngElement& aElement, TXmlEngElement& aCandidate);
666 * Adds namespaces from internal array for the fragment.
667 * @since Series60 4.0
669 IMPORT_C virtual void AddNamespacesL();
672 * Sets content to a child element. If no element with given local name
673 * is not found, new one is added and content is set to that one.
674 * @since Series60 4.0
675 * @param aContent Content to be set.
677 IMPORT_C virtual void SetContentL(const TDesC8& aContent);
681 * @since Series60 4.0
682 * @param aContent Content to be set.
684 IMPORT_C virtual void AddContentL(const TDesC8& aContent);
687 * StartSavingContent changes the internal SAX parsing state of
688 * this fragment to KSenStateSave, which means that next call
689 * to OnStartElementL is treated as data, and not ignored
690 * (in DOM fragment implementation, it would be "extended"
691 * into a DOM object).
693 IMPORT_C void StartSavingContent();
696 private: // New functions
699 * Sets the XML parser to be used for parsing for the fragment.
700 * @since Series60 4.0
701 * @param aReader: the reader to be used.
702 * Ownership is NOT transferred.
704 IMPORT_C virtual void SetParser(CSenParser& aParser);
708 // State variable indicating what this fragment
709 // is currently parsing. Even states (like 0)
710 // mean that this fragment is ignoring the
711 // data, and odd states indicate, that fragment
712 // is storing the data into itself.
715 // Owned element containing this XML fragment data.
716 TXmlEngElement iElement;
718 // Owned document representing this XML fragment
719 RSenDocument iDocument;
721 // Pointer to XML parser. Not owned.
722 CSenParser* ipParser; // Not owned
724 // Possible owner fragment, if such exists. Not owned.
725 CSenFragmentBase* ipOwner; // Not owned
726 CSenFragmentBase* ipDelegate; // Owned
728 RPointerArray<CSenNamespaceData>* ipNamespaceArray; // Owned
730 CBufFlat* ipContentBuf; // Owned
731 RBufWriteStream* ipContentWriteStream; // Owned
734 class CSenNamespaceData : public CBase
737 virtual ~CSenNamespaceData();
741 HBufC8* ipNamespaceUri;
745 #endif //SEN_FRAGMENT_BASE_H