parser/xml/public/nsISAXLocator.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is Robert Sayre.
  18  *
  19  * Portions created by the Initial Developer are Copyright (C) 2005
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 /**
  41  * Interface for associating a SAX event with a document location.
  42  *
  43  * Note that the results returned by the object will be valid only
  44  * during the scope of each callback method: the application will
  45  * receive unpredictable results if it attempts to use the locator at
  46  * any other time, or after parsing completes.
  47  */
  48 [scriptable, uuid(7a307c6c-6cc9-11da-be43-001422106990)]
  49 interface nsISAXLocator: nsISupports {
  50
  51   /**
  52    * Return the column number where the current document event ends.
  53    *
  54    * Warning: The return value from the method is intended only as an
  55    * approximation for the sake of diagnostics; it is not intended to
  56    * provide sufficient information to edit the character content of
  57    * the original XML document.  For example, when lines contain
  58    * combining character sequences, wide characters, surrogate pairs,
  59    * or bi-directional text, the value may not correspond to the
  60    * column in a text editor's display.
  61    *
  62    * The return value is an approximation of the column number in the
  63    * document entity or external parsed entity where the markup
  64    * triggering the event appears.
  65    *
  66    * If possible, the SAX driver should provide the line position of
  67    * the first character after the text associated with the document
  68    * event.  The first column in each line is column 1.
  69    *
  70    * @return The column number, or -1 if none is available.
  71    */
  72   readonly attribute long columnNumber;
  73
  74   /**
  75    * Return the line number where the current document event ends.
  76    * Lines are delimited by line ends, which are defined in the XML
  77    * specification.
  78    *
  79    * Warning: The return value from the method is intended only as an
  80    * approximation for the sake of diagnostics; it is not intended to
  81    * provide sufficient information to edit the character content of
  82    * the original XML document.  In some cases, these "line" numbers
  83    * match what would be displayed as columns, and in others they may
  84    * not match the source text due to internal entity expansion.
  85    *
  86    * The return value is an approximation of the line number in the
  87    * document entity or external parsed entity where the markup
  88    * triggering the event appears.
  89    *
  90    * If possible, the SAX driver should provide the line position of
  91    * the first character after the text associated with the document
  92    * event.  The first line is line 1.
  93    *
  94    * @return The line number, or -1 if none is available.
  95    */
  96   readonly attribute long lineNumber;
  97
  98   /**
  99    * Return the public identifier for the current document event.
 100    *
 101    * The return value is the public identifier of the document entity
 102    * or of the external parsed entity in which the markup triggering
 103    * the event appears.
 104    *
 105    * @return A string containing the public identifier, or
 106    *         null if none is available.
 107    */
 108   readonly attribute AString publicId;
 109
 110   /**
 111    * Return the system identifier for the current document event.
 112    *
 113    * The return value is the system identifier of the document entity
 114    * or of the external parsed entity in which the markup triggering
 115    * the event appears.
 116    *
 117    * @return A string containing the system identifier, or null
 118    *         if none is available.
 119    */
 120   readonly attribute AString systemId;
 121 };