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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Class implements basic functionality of an XML fragment
25 #ifndef SEN_BASE_FRAGMENT_H
26 #define SEN_BASE_FRAGMENT_H
29 #include <MSenContentHandlerClient.h>
30 #include <SenElement.h>
31 #include <SenFragment.h>
35 // Fragment's internal states.
36 const TInt KStateNotSet = -1;
37 const TInt KStateIgnore = 0;
38 const TInt KStateSave = 1;
39 const TInt KStateResume = 2;
41 // FORWARD DECLARATIONS
47 * Class implements basic functionality of an XML fragment
48 * Typically BaseFragment is used to parse certain part of some XML document.
49 * The element is identified by localname (or qualifiedname) and namespace.
50 * All child elements between start tag and and end tag defined this fragment
51 * will become content of this BaseFragment. In other words, BaseFragment has
52 * all data inside a single element.
53 * BaseFragment will parse only namespace (xmlns) attributes from a document
54 * and rest of the attributes are to be handled by subclasses, which should
55 * overwrite SetAttributesL() method to achieve this.
56 * The CSenXmlReader class will do the actual parsing and this class will
57 * act as content handler for XML parser SAX events.
61 class CSenBaseFragment : public CSenFragment, public MSenContentHandlerClient
63 public: // Constructors and destructor
66 * Standard 2 phase constructor.
68 * @param aElement is the element where construction
69 * data will be copied from.
71 IMPORT_C static CSenBaseFragment* NewL(const CSenElement& aElement);
74 * Standard 2 phase constructor.
76 * KErrSenInvalidCharacters if aLocalName contains
78 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
80 * @param aLocalName: is the XML localname for this fragment
82 IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aLocalName);
85 * Standard 2 phase constructor.
87 * KErrSenInvalidCharacters if aLocalName contains
89 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
91 * @param aNsUri: XML namespace URI
92 * @param aLocalName: XML localname
94 IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
95 const TDesC8& aLocalName);
98 * Standard 2 phase constructor.
100 * KErrSenInvalidCharacters if aLocalName or aQName contains
101 * illegal characters.
102 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
103 * @since Series60 3.0
104 * @param aNsUri: XML namespace URI
105 * @param aLocalName: XML localname
106 * @param aQName: XML qualifiedname
108 IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
109 const TDesC8& aLocalName,
110 const TDesC8& aQName);
113 * Standard 2 phase constructor.
115 * KErrSenInvalidCharacters if aLocalName or aQName contains
116 * illegal characters.
117 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
118 * @since Series60 3.0
119 * @param aNsUri: XML namespace URI
120 * @param aLocalName: XML localname
121 * @param aQName: XML qualifiedname
122 * @param apAttrs: XML attributes
124 IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
125 const TDesC8& aLocalName,
126 const TDesC8& aQName,
127 const RAttributeArray& apAttrs);
130 * Standard 2 phase constructor.
131 * @param aParent Element to be set as fragment's parent element.
133 * KErrSenInvalidCharacters if aLocalName or aQName contains
134 * illegal characters.
135 * KErrSenZeroLengthDescriptor if aLocalName or aQName is of
137 * @since Series60 3.0
138 * @param aNsUri: XML namespace URI
139 * @param aLocalName: XML localname
140 * @param aQName: XML qualifiedname
141 * @param apAttrs: XML attributes
142 * @param aParent: Parent element
144 IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
145 const TDesC8& aLocalName,
146 const TDesC8& aQName,
147 const RAttributeArray& apAttrs,
148 CSenElement& aParent);
153 IMPORT_C virtual ~CSenBaseFragment();
159 * Getter for the content,which is returned as UTF-8 form XML.
160 * @since Series60 3.0
161 * @return content as UTF-8 form XML.
163 IMPORT_C virtual TPtrC8 Content();
165 * Gets the namespace object with a given prefix.
166 * @since Series60 3.0
167 * @param aPrefix: prefix that wanted namespace should have.
168 * @return namespace with the given prefix. If not found or given prefix
169 * is zero length, will return NULL.
171 IMPORT_C virtual CSenNamespace* Namespace(const TDesC8& aPrefix);
174 * @since Series60 3.0
175 * @param aPrefix is the XML namespace prefix
177 IMPORT_C virtual void EnsureNamespace(const TDesC8& aPrefix);
180 * @since Series60 3.0
181 * @return Detaches this fragment from its owner. All namespace
182 * references from possible parent fragments are declared in
183 * the scope of this fragment prior detaching.
185 IMPORT_C virtual void DetachL();
188 * @since Series60 3.0
189 * @param aAttrs are the attributes from which the namespaces
191 * @param aEnsure if set to TRUE, the namespaces are copied into
192 * this fragment. If FALSE, then the namespaces are only
193 * referenced, but not copied and owned by this class.
195 IMPORT_C virtual void SaveNamespacesL(const RAttributeArray& aAttrs,
199 * Resets the content of the fragment, and resets the namespaces.
200 * @since Series60 3.0
202 IMPORT_C virtual void ResetContentL();
204 // Functions from base classes
209 * @since Series60 3.0
210 * @return the localname of this fragment as UTF-8 form descriptor
212 IMPORT_C virtual const TDesC8& LocalName() const;
215 * Getter for Fragment's namespace URI..
216 * @since Series60 3.0
217 * @return Namespace URI or KNullDesC if not set.
219 IMPORT_C virtual const TDesC8& NsUri() const;
222 * Getter for namespace prefix of this fragment.
223 * @since Series60 3.0
224 * @return namespace prefix or KNullDesC if not set.
226 IMPORT_C virtual const TDesC8& NsPrefix() const;
229 * Getting the fragment as an XML element. This method will panic if
230 * element has not been initialized for any reason.
231 * @since Series60 3.0
232 * @return the current object as element. Ownership is not transferred.
234 IMPORT_C virtual CSenElement& AsElement();
237 * Etracts the XML element from the fragment, leaving the fragment empty.
238 * Note(!): the return value (CSenElement) STRONGLY suggests that
239 * subclasses INHERIT CSenFragment in order properly comply the
240 * requirement of the ExtractElement() implementation.
241 * @since Series60 3.0
242 * @return the current object as element. May return NULL.
243 * Ownership IS TRANSFERRED to the caller.
245 IMPORT_C virtual CSenElement* ExtractElement();
248 * Gets the XML reader which this fragment uses for parsing.
249 * @since Series60 3.0
250 * @return the XML reader. Ownerships is not transferred,
251 * due even this class does not own the XML reader instance.
253 IMPORT_C virtual CSenXmlReader* Reader();
256 * Sets the XML reader to be used for parsing for the fragment.
257 * @since Series60 3.0
258 * @param aReader: the reader to be used.
259 * Ownership is NOT transferred.
261 IMPORT_C virtual void SetReader(CSenXmlReader& aReader);
265 * KErrSenXmlReaderNotSet if XML reader has not been set.
266 * Method to invoke parsing of a XML data.
267 * Note that SetReader() must be called before this method can be used.
268 * Note that CSenBaseFragment does not parse any other
269 * attributes, but XML namespace attributes only. This
270 * is due to allow subclasses to process only those attributes
271 * they are interested in, and not others.
272 * @since Series60 3.0
273 * @param aXml: The data to be parsed.
275 IMPORT_C virtual void ParseL(const TDesC8& aXml);
278 * Same as ParseL() except that it doesn't leave in case of an error.
279 * Instead errors are trapped and error is returned.
280 * SetReader() must be called before this method can be used.
281 * @since Series60 3.0
282 * @param aXml: The data to be parsed.
283 * @return KErrNone or other system-wide Symbian error codes.
285 IMPORT_C virtual TInt BuildFrom(const TDesC8& aXml);
289 * KErrSenXmlReaderNotSet if XML reader has not been set.
290 * Let the delegate MSenFragment handle the following SAX events.
291 * This fragment is made the owner of the delegate and the delegate
292 * is expected to make this MSenFragment the receiver of SAX events
293 * once it has seen the end element for itself.
294 * @since Series60 3.0
295 * @param aDelegate is the fragment to start handling the SAX events.
297 IMPORT_C virtual void DelegateParsingL(MSenFragment& aDelegate);
301 * KErrSenXmlReaderNotSet if XML reader has not been set.
302 * Creates a new fragment and lets the created MSenFragment handle the
303 * following SAX events. This fragment is made the owner of the delegate
304 * and the delegate is expected to make this MSenFragment act as receiver
305 * for SAX events (callbacks) once it has seen the end element for itself.
306 * @since Series60 3.0
307 * @param aNsUri The XML namespace URI for the delegate to be created
308 * @param aLocalName The XML localname for the delegate to be created
309 * @param aQName The XML qualifiedname for the delegate to be created
310 * @param aAttrs: The XML attributes for the delegate to be created
312 IMPORT_C virtual void DelegateParsingL(const TDesC8& aNsUri,
313 const TDesC8& aLocalName,
314 const TDesC8& aQName,
315 const RAttributeArray& aAttrs);
318 * Sets the reader for this fragment and sets this to be the
319 * content handler of the following SAX events.
320 * @since Series60 3.0
321 * @param aReader is the XML parser to be used.
323 IMPORT_C virtual void ParseWithL(CSenXmlReader& aReader);
326 * Sets a new parent for this fragment.
327 * @since Series60 3.0
328 * @param aFragment: the new parent.
330 IMPORT_C virtual void SetOwner(MSenFragment& aFragment);
334 * KErrSenXmlReaderNotSet if XML reader has not been set. Resumes
335 * parsing to be handled by this fragment. Usually called by some
336 * delegate fragment which was set to be content handler because this
337 * fragment called DelegateParsingL().
338 * @since Series60 3.0
339 * @param aNsUri The namespace URI of the current element
340 * @param aLocalName The local name of the current element
341 * @param aQName The qualified name of the current element
343 IMPORT_C virtual void ResumeParsingFromL(const TDesC8& aNsUri,
344 const TDesC8& aLocalName,
345 const TDesC8& aQName);
348 * Sets the attributes for the fragment. BaseFragment parses only
349 * namespace (xmlns) attributes from the document.
350 * Subclasses should override this method if they are intrested
351 * of handling any other XML attributes and their corresponding
353 * @since Series60 3.0
354 * @param aAttrs: the array of attributes.
356 IMPORT_C virtual void SetAttributesL(const RAttributeArray& aAttrs);
359 * Writes the start element tag to the content stream.
360 * Derivants can override the basic usage used in BaseFragment.
361 * @since Series60 3.0
362 * @param aNsUri The namespace URI of the current element
363 * @param aLocalName The local name of the current element
364 * @param aQName The qualified name of the current element
365 * @param aAttrs is the array of attributes.
367 IMPORT_C void WriteStartElementL(const TDesC8& aNsUri,
368 const TDesC8& aLocalName,
369 const TDesC8& aQName,
370 const RAttributeArray& aAttrs);
373 * Writes the end element tag to the content stream.
374 * Derivants can override the basic usage used in BaseFragment.
375 * @since Series60 3.0
376 * @param aNsUri The namespace URI of the current element
377 * @param aLocalName The local name of the current element
378 * @param aQName The qualified name of the current element
380 IMPORT_C void WriteEndElementL(const TDesC8& aNsUri,
381 const TDesC8& aLocalName,
382 const TDesC8& aQName);
385 * Gets the fragment data as an unicode XML.
386 * @since Series60 3.0
387 * @return fragment as XML. Caller takes ownership.
389 IMPORT_C virtual HBufC* AsXmlUnicodeL();
392 * Gets the fragment data as an UTF-8 form XML.
393 * @since Series60 3.0
394 * @return fragment as XML. Caller takes ownership.
396 IMPORT_C virtual HBufC8* AsXmlL();
399 * Invokes AsElement()->WriteAsXMLToL(aWs);
400 * @since Series60 3.0
401 * @param aWs is the stream into which the UTF-8 form XML will
404 IMPORT_C virtual void WriteAsXMLToL(RWriteStream& aWs);
407 * Checks if fragment matches to another fragment
408 * by its content and child elements.
409 * Fragment can contain more data than the given candidate.
410 * @since Series60 3.0
411 * @param aCandidate The pattern to be matched. Must contain same or
412 * less data for match to come true.
413 * @return ETrue if content and possible children match exactly
414 * to given pattern. EFalse otherwise.
416 IMPORT_C virtual TBool ConsistsOfL(MSenFragment& aCandidate);
421 * C++ default constructor.
423 IMPORT_C CSenBaseFragment();
426 * Following BaseConstructL methods should be called from ConstructL()
427 * methods of some deriving (fragment) class.
431 * BaseConstructL, where an element is given as initializer.
432 * @since Series60 3.0
433 * @param aElement from which this fragment will be constructed from.
435 IMPORT_C void BaseConstructL(const CSenElement& aElement);
438 * BaseConstructL setting XML localname for this fragment.
439 * @since Series60 3.0
440 * @param aLocalName XML localname for this fragment
442 IMPORT_C void BaseConstructL(const TDesC8& aLocalName);
445 * BaseConstructL offering possibility to set XML namespace and localname.
446 * @since Series60 3.0
447 * @param aNsUri XML namespace URI for this fragment
448 * @param aLocalName XML localname for this fragment
450 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
451 const TDesC8& aLocalName);
455 * @since Series60 3.0
456 * @param aNsUri XML namespace URI for this fragment
457 * @param aLocalName XML localname for this fragment
458 * @param aQName XML qualifiedname for this fragment
460 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
461 const TDesC8& aLocalName,
462 const TDesC8& aQName);
465 * @since Series60 3.0
466 * @param aNsUri XML namespace URI for this fragment
467 * @param aLocalName XML localname for this fragment
468 * @param aQName XML qualifiedname for this fragment
469 * @param aAttrs XML attributes for this fragment
471 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
472 const TDesC8& aLocalName,
473 const TDesC8& aQName,
474 const RAttributeArray& aAttrs);
478 * @since Series60 3.0
479 * @param aNsUri XML namespace URI for this fragment
480 * @param aLocalName XML localname for this fragment
481 * @param aQName XML qualifiedname for this fragment
482 * @param aAttrs XML attributes for this fragment
483 * @param aParent parent to be set for this fragmemt
485 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
486 const TDesC8& aLocalName,
487 const TDesC8& aQName,
488 const RAttributeArray& aAttrs,
489 CSenElement& aParent);
492 * BaseConstructL() setting the XML reader for this fragment
493 * @since Series60 3.0
494 * @param aReader is the XML reader for this fragment
496 IMPORT_C void BaseConstructL(CSenXmlReader& aReader);
501 * Makes the content internal stream for content saving available.
502 * @since Series60 3.0
504 IMPORT_C virtual void AllocContentSaverL();
507 * Callback function implementing the XML content handler interface.
508 * Inheriting classes can override these.
509 * @since Series60 3.0
510 * @param aNsUri The namespace URI of the new element
511 * @param aLocalName The local name of the new element
512 * @param aQName The qualified name of the new element
513 * @param aAttrs The attributes of the new element
515 IMPORT_C virtual void StartElementL(const TDesC8& aNsUri,
516 const TDesC8& aLocalName,
517 const TDesC8& aQName,
518 const RAttributeArray& aAttrs);
521 * Callback function which implement the XML content handler interface.
522 * Inheriting classes can override these.
523 * @since Series60 3.0
524 * @param aNsUri The namespace URI of the new element
525 * @param aLocalName The local name of the new element
526 * @param aQName The qualified name of the new element
528 IMPORT_C virtual void EndElementL(const TDesC8& aNsUri,
529 const TDesC8& aLocalName,
530 const TDesC8& aQName);
533 * Function which implement the XML content handler interface.
534 * Inheriting classes can override these.
535 * This one is called when content is starting.
536 * @since Series60 3.0
537 * @param aChars The content characters.
538 * @param aStart The starting index
539 * @param aLength The length of the characters.
541 IMPORT_C virtual void CharactersL(const TDesC8& aChars,
546 * Callback function which implement the XML content handler interface.
547 * Inheriting classes can override these. Note that overrides should
548 * return TRUE (1) on success and FALSE (0) on failure to parser.
550 * @since Series60 3.0
551 * @param aName The entity name
554 IMPORT_C TInt StartEntity(TDesC8& aName);
557 * Sets content to a child element. If no element with given local name
558 * is not found, new one is added and content is set to that one.
559 * @since Series60 3.0
560 * @param aLocalName The local name of element which content
562 * @param aContent Content to be set.
563 * @return the element where content was set.
565 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
566 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
568 IMPORT_C MSenElement& SetContentOfL(const TDesC8& aLocalName,
569 const TDesC8& aContent);
571 * Gets the content of a given element.
572 * @since Series60 3.0
573 * @param aLocalName The local name of the element which content is
575 * @return the content which was asked
577 IMPORT_C TPtrC8 ContentOf(const TDesC8& aLocalName);
579 private: // New functions
582 * Leaving variant which is then trapped in the non-leaving function.
586 // Functions from base classes
588 // From MSenContentHandlerClient
590 IMPORT_C virtual TInt StartDocument();
591 IMPORT_C virtual TInt EndDocument();
592 IMPORT_C virtual TInt StartElement(const TDesC8& aNsUri,
593 const TDesC8& aLocalName,
594 const TDesC8& aQName,
595 const RAttributeArray& aAttrs);
597 IMPORT_C virtual TInt EndElement(const TDesC8& aNsUri,
598 const TDesC8& aLocalName,
599 const TDesC8& aQName);
601 IMPORT_C virtual TInt Characters(const TDesC8& aChars,
605 IMPORT_C virtual TInt Error(TInt aErrorCode);
607 //IMPORT_C TInt StartEntityL(const TDesC8& aName);
612 // State variable indicating what this fragment
613 // is currently parsing. Even states (like 0)
614 // mean that this fragment is ignoring the
615 // data, and odd states indicate, that fragment
616 // is storing the data into itself.
618 // Owned element containing this XML fragment data.
619 CSenElement* ipElement;
620 // Pointer to XML parser. Not owned.
621 CSenXmlReader* iXmlReader;
622 // Possible owner fragment, if such exists. Not owned.
623 MSenFragment* ipOwner;
624 // Internal write stream, into which UTF-8 form XML is stored
629 // Owned pointer to delegate fragment
630 CSenFragment* ipDelegate;
631 // Not owned. Holds namespaces that are referred to from
632 // within the content but were not declared within this
634 RPointerArray<CSenNamespace> iNamespaces;
635 // Owned. Holds prefixes that have been declared within the
636 // scope of this BaseFragment
637 RPointerArray<HBufC8> iPrefixes;
638 // Actual flat buffer to content which includes namespaces.
639 CBufFlat* ipContentWithNamespaces;
640 // Indicating that content writing stream is initialized.
641 TBool hasContentWriteStream;
642 // Indicates whether or not ipElement member is an owned
646 #endif //SEN_BASE_FRAGMENT_H