1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* vim: set ts=2 sw=2 et tw=78: */ 3 /* This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 #ifndef NS_IPARSER___ 7 #define NS_IPARSER___ 8 9 /** 10 * This GECKO-INTERNAL interface is on track to being REMOVED (or refactored 11 * to the point of being near-unrecognizable). 12 * 13 * Please DO NOT #include this file in comm-central code, in your XULRunner 14 * app or binary extensions. 15 * 16 * Please DO NOT #include this into new files even inside Gecko. It is more 17 * likely than not that #including this header is the wrong thing to do. 18 */ 19 20 #include "nsISupports.h" 21 #include "nsIStreamListener.h" 22 #include "nsIDTD.h" 23 #include "nsString.h" 24 #include "nsTArray.h" 25 #include "nsAtom.h" 26 #include "nsParserBase.h" 27 #include "mozilla/NotNull.h" 28 29 #define NS_IPARSER_IID \ 30 { \ 31 0x2c4ad90a, 0x740e, 0x4212, { \ 32 0xba, 0x3f, 0xfe, 0xac, 0xda, 0x4b, 0x92, 0x9e \ 33 } \ 34 } 35 36 class nsIContentSink; 37 class nsIRequestObserver; 38 class nsIURI; 39 class nsIChannel; 40 namespace mozilla { 41 class Encoding; 42 } 43 44 enum eParserCommands { eViewNormal, eViewSource, eViewFragment, eViewErrors }; 45 46 enum eParserDocType { ePlainText = 0, eXML, eHTML_Quirks, eHTML_Strict }; 47 48 enum eStreamState { eNone, eOnStart, eOnDataAvail, eOnStop }; 49 50 /** 51 * This GECKO-INTERNAL interface is on track to being REMOVED (or refactored 52 * to the point of being near-unrecognizable). 53 * 54 * Please DO NOT #include this file in comm-central code, in your XULRunner 55 * app or binary extensions. 56 * 57 * Please DO NOT #include this into new files even inside Gecko. It is more 58 * likely than not that #including this header is the wrong thing to do. 59 */ 60 class nsIParser : public nsParserBase { 61 protected: 62 using Encoding = mozilla::Encoding; 63 template <typename T> 64 using NotNull = mozilla::NotNull<T>; 65 66 public: 67 NS_DECLARE_STATIC_IID_ACCESSOR(NS_IPARSER_IID) 68 69 /** 70 * Select given content sink into parser for parser output 71 * @update gess5/11/98 72 * @param aSink is the new sink to be used by parser 73 * @return 74 */ 75 NS_IMETHOD_(void) SetContentSink(nsIContentSink* aSink) = 0; 76 77 /** 78 * retrieve the sink set into the parser 79 * @update gess5/11/98 80 * @return current sink 81 */ 82 NS_IMETHOD_(nsIContentSink*) GetContentSink(void) = 0; 83 84 /** 85 * Call this method once you've created a parser, and want to instruct it 86 * about the command which caused the parser to be constructed. For example, 87 * this allows us to select a DTD which can do, say, view-source. 88 * 89 * @update gess 3/25/98 90 * @param aCommand -- ptrs to string that contains command 91 * @return nada 92 */ 93 NS_IMETHOD_(void) GetCommand(nsCString& aCommand) = 0; 94 NS_IMETHOD_(void) SetCommand(const char* aCommand) = 0; 95 NS_IMETHOD_(void) SetCommand(eParserCommands aParserCommand) = 0; 96 97 /** 98 * Call this method once you've created a parser, and want to instruct it 99 * about what charset to load 100 * 101 * @update ftang 4/23/99 102 * @param aCharset- the charest of a document 103 * @param aCharsetSource- the soure of the chares 104 * @param aChannelHadCharset- whether the channel had charset 105 * @return nada 106 */ 107 virtual void SetDocumentCharset(NotNull<const Encoding*> aCharset, 108 int32_t aSource, 109 bool aChannelHadCharset = false) = 0; 110 111 /** 112 * Get the channel associated with this parser 113 * @update harishd,gagan 07/17/01 114 * @param aChannel out param that will contain the result 115 * @return NS_OK if successful 116 */ 117 NS_IMETHOD GetChannel(nsIChannel** aChannel) override = 0; 118 119 /** 120 * Get the DTD associated with this parser 121 * @update vidur 9/29/99 122 * @param aDTD out param that will contain the result 123 * @return NS_OK if successful, NS_ERROR_FAILURE for runtime error 124 */ 125 NS_IMETHOD GetDTD(nsIDTD** aDTD) = 0; 126 127 /** 128 * Get the nsIStreamListener for this parser 129 */ 130 virtual nsIStreamListener* GetStreamListener() = 0; 131 132 /************************************************************************** 133 * Parse methods always begin with an input source, and perform 134 * conversions until you wind up being emitted to the given contentsink 135 * (which may or may not be a proxy for the NGLayout content model). 136 ************************************************************************/ 137 138 // Call this method to resume the parser from an unblocked state. 139 // This can happen, for example, if parsing was interrupted and then the 140 // consumer needed to restart the parser without waiting for more data. 141 // This also happens after loading scripts, which unblock the parser in 142 // order to process the output of document.write() and then need to 143 // continue on with the page load on an enabled parser. 144 NS_IMETHOD ContinueInterruptedParsing() = 0; 145 146 // Stops parsing temporarily. 147 NS_IMETHOD_(void) BlockParser() = 0; 148 149 // Open up the parser for tokenization, building up content 150 // model..etc. However, this method does not resume parsing 151 // automatically. It's the callers' responsibility to restart 152 // the parsing engine. 153 NS_IMETHOD_(void) UnblockParser() = 0; 154 155 /** 156 * Asynchronously continues parsing. 157 */ 158 NS_IMETHOD_(void) ContinueInterruptedParsingAsync() = 0; 159 160 NS_IMETHOD_(bool) IsParserEnabled() override = 0; 161 NS_IMETHOD_(bool) IsComplete() = 0; 162 163 NS_IMETHOD Parse(nsIURI* aURL, nsIRequestObserver* aListener = nullptr, 164 void* aKey = 0, nsDTDMode aMode = eDTDMode_autodetect) = 0; 165 166 NS_IMETHOD Terminate(void) = 0; 167 168 /** 169 * This method gets called when you want to parse a fragment of HTML or XML 170 * surrounded by the context |aTagStack|. It requires that the parser have 171 * been given a fragment content sink. 172 * 173 * @param aSourceBuffer The XML or HTML that hasn't been parsed yet. 174 * @param aTagStack The context of the source buffer. 175 * @return Success or failure. 176 */ 177 NS_IMETHOD ParseFragment(const nsAString& aSourceBuffer, 178 nsTArray<nsString>& aTagStack) = 0; 179 180 /** 181 * This method gets called when the tokens have been consumed, and it's time 182 * to build the model via the content sink. 183 * @update gess5/11/98 184 * @return error code -- 0 if model building went well . 185 */ 186 NS_IMETHOD BuildModel(void) = 0; 187 188 /** 189 * Call this method to cancel any pending parsing events. 190 * Parsing events may be pending if all of the document's content 191 * has been passed to the parser but the parser has been interrupted 192 * because processing the tokens took too long. 193 * 194 * @update kmcclusk 05/18/01 195 * @return NS_OK if succeeded else ERROR. 196 */ 197 198 NS_IMETHOD CancelParsingEvents() = 0; 199 200 virtual void Reset() = 0; 201 202 /** 203 * True if the insertion point (per HTML5) is defined. 204 */ 205 virtual bool IsInsertionPointDefined() = 0; 206 207 /** 208 * Call immediately before starting to evaluate a parser-inserted script or 209 * in general when the spec says to increment the script nesting level. 210 */ 211 virtual void IncrementScriptNestingLevel() = 0; 212 213 /** 214 * Call immediately after having evaluated a parser-inserted script or 215 * generally want to restore to the state before the last 216 * IncrementScriptNestingLevel call. 217 */ 218 virtual void DecrementScriptNestingLevel() = 0; 219 220 /** 221 * True if this is an HTML5 parser whose script nesting level (in 222 * the sense of 223 * <https://html.spec.whatwg.org/multipage/parsing.html#script-nesting-level>) 224 * is nonzero. 225 */ 226 virtual bool HasNonzeroScriptNestingLevel() const = 0; 227 228 /** 229 * Marks the HTML5 parser as not a script-created parser. 230 */ 231 virtual void MarkAsNotScriptCreated(const char* aCommand) = 0; 232 233 /** 234 * True if this is a script-created HTML5 parser. 235 */ 236 virtual bool IsScriptCreated() = 0; 237 }; 238 239 NS_DEFINE_STATIC_IID_ACCESSOR(nsIParser, NS_IPARSER_IID) 240 241 /* ===========================================================* 242 Some useful constants... 243 * ===========================================================*/ 244 245 #define NS_IPARSER_FLAG_XML 0x00000200 246 #define NS_IPARSER_FLAG_HTML 0x00000400 247 248 #endif 249