gecko/parser/xml/public/nsISAXXMLReader.idl

223 lines
8.1 KiB
Plaintext

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is Robert Sayre.
*
* Portions created by the Initial Developer are Copyright (C) 2005
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsIStreamListener.idl"
interface nsIInputStream;
interface nsIRequestObserver;
interface nsIURI;
interface nsISAXContentHandler;
interface nsISAXDTDHandler;
interface nsISAXEntityResolver;
interface nsISAXErrorHandler;
interface nsISAXLexicalHandler;
/**
* Interface for reading an XML document using callbacks.
*
* nsISAXXMLReader is the interface that an XML parser's SAX2
* driver must implement. This interface allows an application to set
* and query features and properties in the parser, to register event
* handlers for document processing, and to initiate a document
* parse.
*/
[scriptable, uuid(5556997e-d816-4218-8b54-803d4261206e)]
interface nsISAXXMLReader : nsIStreamListener {
/**
* The base URI.
*/
attribute nsIURI baseURI;
/**
* If the application does not register a content handler, all
* content events reported by the SAX parser will be silently
* ignored.
*
* Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.
*/
attribute nsISAXContentHandler contentHandler;
/**
* If the application does not register a DTD handler, all DTD
* events reported by the SAX parser will be silently ignored.
*
* Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.
*/
attribute nsISAXDTDHandler dtdHandler;
/**
* If the application does not register an error handler, all
* error events reported by the SAX parser will be silently ignored;
* however, normal processing may not continue. It is highly
* recommended that all SAX applications implement an error handler
* to avoid unexpected bugs.
*
* Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.
*/
attribute nsISAXErrorHandler errorHandler;
/**
* If the application does not register a lexical handler, all
* lexical events (e.g. startDTD) reported by the SAX parser will be
* silently ignored.
*
* Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.
*/
attribute nsISAXLexicalHandler lexicalHandler;
/**
* Set the value of a feature flag. NOT CURRENTLY IMPLEMENTED.
*
* The feature name is any fully-qualified URI. It is possible
* for an XMLReader to expose a feature value but to be unable to
* change the current value. Some feature values may be immutable
* or mutable only in specific contexts, such as before, during, or
* after a parse.
*
* All XMLReaders are required to support setting
* http://xml.org/sax/features/namespaces to true and
* http://xml.org/sax/features/namespace-prefixes to false.
*
* @param name String flag for a parser feature.
* @param value Turn the feature on/off.
*/
void setFeature(in AString name, in boolean value);
/**
* Look up the value of a feature flag. NOT CURRENTLY IMPLEMENTED.
*
* The feature name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a feature name but
* temporarily be unable to return its value.
* Some feature values may be available only in specific
* contexts, such as before, during, or after a parse.
*
* All XMLReaders are required to recognize the
* http://xml.org/sax/features/namespaces and the
* http://xml.org/sax/features/namespace-prefixes feature names.
*
* @param name String flag for a parser feature.
*/
boolean getFeature(in AString name);
/**
* Set the value of a property. NOT CURRENTLY IMPLEMENTED.
*
* The property name is any fully-qualified URI. It is possible
* for an XMLReader to recognize a property name but to be unable to
* change the current value. Some property values may be immutable
* or mutable only in specific contexts, such as before, during, or
* after a parse.
*
* XMLReaders are not required to recognize setting any specific
* property names, though a core set is defined by SAX2.
*
* This method is also the standard mechanism for setting
* extended handlers.
*
* @param name String flag for a parser feature
* @param value Turn the feature on/off.
*/
void setProperty(in AString name, in nsISupports value);
/**
* Look up the value of a property. NOT CURRENTLY IMPLEMENTED.
*
* The property name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a property name but
* temporarily be unable to return its value.
* Some property values may be available only in specific
* contexts, such as before, during, or after a parse.
*
* XMLReaders are not required to recognize any specific
* property names, though an initial core set is documented for
* SAX2.
*
* Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.
*
* @param name The property name, which is a fully-qualified URI.
* @return The current value of the property.
*/
boolean getProperty(in AString name);
/**
*
* @param str The UTF16 string to be parsed
* @param contentType The content type of the string (see parseFromStream)
*
*/
void parseFromString(in AString str, in string contentType);
/**
*
* @param stream The byte stream whose contents are parsed
* @param charset The character set that was used to encode the byte
* stream. NULL if not specified.
* @param contentType The content type of the string - either text/xml,
* application/xml, or application/xhtml+xml.
* Must not be NULL.
*
*/
void parseFromStream(in nsIInputStream stream,
in string charset,
in string contentType);
/**
* Begin an asynchronous parse. This method initializes the parser,
* and must be called before any nsIStreamListener methods. It is
* then the caller's duty to call nsIStreamListener methods to drive
* the parser. Once this method is called, the caller must not call
* one of the other parse methods.
*
* @param observer The nsIRequestObserver to notify upon start or stop.
* Can be NULL.
*/
void parseAsync(in nsIRequestObserver observer);
};