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: This abstract class defines the interface for WSF XML
26 #ifndef M_SEN_FRAGMENT_H
27 #define M_SEN_FRAGMENT_H
32 #include <xml/Attribute.h>
33 #include <SenXmlReader.h>
34 #include <MSenElement.h>
36 // FORWARD DECLARATIONS
45 * This abstract class defines the interface for XML fragment classes.
46 * The subclasses are used to extract certain part of XML document into
47 * a separate XML subtree, called fragment. This M-class is typically used
48 * when a safe reference to some actual implementation is required.
49 * Fragment classes are content handlers for SAX callback events received
50 * from CSenXmlReader class. They typically inherit MSenContentHandlerClient
57 public: // New functions
59 * Getting the fragment as an XML element. This method will panic if
60 * element has not been initialized (EFragmentElementNotInitialized).
62 * @return the current object as element. Ownership is not transferred.
64 virtual CSenElement& AsElement() = 0;
67 * Method extracts the root element (whole data) from this fragment.
68 * After calling this method, the fragment does not have any
69 * internal element. Method is often called before fragment is
70 * destroyed, in order to fetch its content and transfer ownership
71 * to that content to some other object.
73 * @return the current object as element. May return NULL.
74 * Ownership is transferred to the caller.
76 virtual CSenElement* ExtractElement() = 0;
79 * Sets the XML reader to be used for parsing for the fragment.
81 * @param aReader: the reader to be used.
82 * Ownership is NOT transferred.
84 virtual void SetReader(CSenXmlReader& aReader) = 0;
87 * Gets the XML reader which this fragment uses for parsing.
89 * @param aReader: the reader to be used.
90 * Ownerships is not transferred.
93 virtual CSenXmlReader* Reader() = 0;
96 * Method to invoke parsing of a UTF-8 form XML data.
97 * Note that SetReader() must be called before this
99 * Parsing is dependent of preset localname or qualifiedname
100 * and possible namespace for this fragment.
101 * @since Series60 3.0
102 * @param aBuf: The XML to be parsed.
104 virtual void ParseL(const TDesC8& aBuf) = 0;
107 * Same as ParseL() except that it doesn't leave in case of an error.
108 * Instead errors are trapped and error is returned.
109 * SetReader() must be called before this method can be used.
110 * @since Series60 3.0
111 * @param aBuf: The XML to be parsed.
112 * @return KErrNone or other system-wide Symbian error codes
114 virtual TInt BuildFrom(const TDesC8& aBuf) = 0;
117 * Let the delegate MSenFragment handle the following SAX events.
118 * This fragment is made the owner of the delegate and the delegate
119 * is expected to make this MSenFragment the receiver of SAX events
120 * once it has seen the end element for itself. This is achieved by
121 * ResumeParsingFromL(), which delegate will call from his parent.
122 * The currently set XML reader is used to parse XML for the delagate,
124 * @since Series60 3.0
125 * @param aDelegate: the fragment to start handling the SAX events.
127 virtual void DelegateParsingL(MSenFragment& aDelegate) = 0;
130 * Creates a new delegate (fragment) using the given arguments
131 * and lets it handle the SAX events according
132 * to given localname (or qualifiedname) and possible namespace.
133 * This instance is made the owner of the delegate and the delegate
134 * is expected to resume parsing to this MSenFragment after it has
135 * finished handling the dedicated part of XML document in question.
136 * at the EndElementL().
137 * The currently set XML reader is used to parse XML for the delagate,
139 * @since Series60 3.0
140 * @param aNsUri: the namespace URI of the new delegate
141 * @param aLocalName: the local name of the new delegate
142 * @param aQName: the qualified name of the new delegate
143 * @param aAttrs: the attributes which to be set for the new delegate
145 virtual void DelegateParsingL( const TDesC8& aNsUri,
146 const TDesC8& aLocalName,
147 const TDesC8& aQName,
148 const RAttributeArray& aAttrs) = 0;
151 * Method sets the reader for this fragment and sets this to be the
152 * content handler for the SAX events according to preset localname
153 * (or qualifiedname) and possible namespace.
154 * @since Series60 3.0
155 * @param aReader: Reader to be used.
157 virtual void ParseWithL(CSenXmlReader& aReader) = 0;
160 * Sets a new owner (parent) for this fragment.
161 * @since Series60 3.0
162 * @param aFragment: the new parent.
164 virtual void SetOwner(MSenFragment& aFragment) = 0;
167 * Resumes the parsing. Usually called by some delegate
168 * fragment which was parsing itself through DelegateParsingL()
169 * call from this instance.
170 * @since Series60 3.0
171 * @param aNsUri The namespace URI of the current element
172 * @param aLocalName The local name of the current element
173 * @param aQName The qualified name of the current element
175 virtual void ResumeParsingFromL(const TDesC8& aNsUri,
176 const TDesC8& aLocalName,
177 const TDesC8& aQName) = 0;
180 * Sets the attributes for the fragment.
181 * @since Series60 3.0
182 * @param aAttrs: the array of attributes.
184 virtual void SetAttributesL(const RAttributeArray& aAttrs) = 0;
187 * Writes the start element tag to the content stream.
188 * Subclasses typically override this.
189 * @since Series60 3.0
190 * @param aNsUri The namespace URI of the current element
191 * @param aLocalName The local name of the current element
192 * @param aQName The qualified name of the current element
193 * @param aAttrs: the array of attributes.
195 virtual void WriteStartElementL(const TDesC8& aNsUri,
196 const TDesC8& aLocalName,
197 const TDesC8& aQName,
198 const RAttributeArray& aAttrs) = 0;
201 * Writes the end element tag to the content stream.
202 * Subclasses typically override this
203 * @since Series60 3.0
204 * @param aNsUri The namespace URI of the current element
205 * @param aLocalName The local name of the current element
206 * @param aQName The qualified name of the current element
208 virtual void WriteEndElementL(const TDesC8& aNsUri,
209 const TDesC8& aLocalName,
210 const TDesC8& aQName) = 0;
213 * Getter for fragment XML local name.
214 * @since Series60 3.0
215 * @return localname or KNullDesC8 if not set.
217 virtual const TDesC8& LocalName() const = 0;
220 * Getter for fragment XML namespace URI.
221 * @since Series60 3.0
222 * @return namespace URI or KNullDesC8 if not set.
224 virtual const TDesC8& NsUri() const = 0;
227 * Getter for XML namespace prefix of this fragment.
228 * @since Series60 3.0
229 * @return namespace prefix or KNullDesC8 if not set.
231 virtual const TDesC8& NsPrefix() const = 0;
234 * Fragment writes itself to a write stream using UTF-8 encoding.
235 * @since Series60 3.0
236 * @param aWriteStream: The stream to write to.
238 virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;
241 * Gets the fragment as Unicode (UCS-2) form XML.
242 * @since Series60 3.0
243 * @return fragment as XML. Caller takes ownership.
245 virtual HBufC* AsXmlUnicodeL() = 0;
248 * Gets the fragment as a UTF-8 form XML.
249 * @since Series60 3.0
250 * @return fragment as XML. Caller takes ownership.
252 virtual HBufC8* AsXmlL() = 0;
255 * Checks if fragment matches to another fragment by its content and
256 * child elements. Fragment can contain more data than the given
258 * @since Series60 3.0
259 * @param aCandidate The pattern to be matched. Must contain same or
260 * less data for match to come true.
261 * @return ETrue if content and possible children match exactly
262 * to given pattern. EFalse otherwise.
264 virtual TBool ConsistsOfL(MSenFragment& aCandidate) = 0;
267 #endif // M_SEN_FRAGMENT_H