PageRenderTime 61ms CodeModel.GetById 30ms app.highlight 3ms RepoModel.GetById 18ms app.codeStats 0ms

/gecko_sdk/idl/nsIURIContentListener.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 167 lines | 19 code | 9 blank | 139 comment | 0 complexity | 57505a8cb1232ca4591f9188106abfde MD5 | raw file
  1/* -*- Mode: IDL; 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
 18 * Netscape Communications Corporation.
 19 * Portions created by the Initial Developer are Copyright (C) 1999
 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 of the GNU General Public License Version 2 or later (the "GPL"),
 26 * or 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
 40interface nsIRequest;
 41interface nsIStreamListener;
 42interface nsIURI;
 43
 44/**
 45 * nsIURIContentListener is an interface used by components which
 46 * want to know (and have a chance to handle) a particular content type.
 47 * Typical usage scenarios will include running applications which register
 48 * a nsIURIContentListener for each of its content windows with the uri
 49 * dispatcher service. 
 50 *
 51 * @status FROZEN
 52 */
 53[scriptable, uuid(94928AB3-8B63-11d3-989D-001083010E9B)]
 54interface nsIURIContentListener : nsISupports
 55{
 56 /**
 57  * Gives the original content listener first crack at stopping a load before
 58  * it happens.
 59  *
 60  * @param aURI   URI that is being opened.
 61  *
 62  * @return       <code>false</code> if the load can continue;
 63  *               <code>true</code> if the open should be aborted.
 64  */
 65  boolean onStartURIOpen(in nsIURI aURI);
 66
 67 /**
 68  * Notifies the content listener to hook up an nsIStreamListener capable of
 69  * consuming the data stream.
 70  *
 71  * @param aContentType         Content type of the data.
 72  * @param aIsContentPreferred  Indicates whether the content should be
 73  *                             preferred by this listener.
 74  * @param aRequest             Request that is providing the data.
 75  * @param aContentHandler      nsIStreamListener that will consume the data.
 76  *                             This should be set to <code>nsnull</code> if
 77  *                             this content listener can't handle the content
 78  *                             type.
 79  *
 80  * @return                     <code>true</code> if the consumer wants to
 81  *                             handle the load completely by itself.  This
 82  *                             causes the URI Loader do nothing else...
 83  *                             <code>false</code> if the URI Loader should
 84  *                             continue handling the load and call the
 85  *                             returned streamlistener's methods. 
 86  */
 87  boolean doContent(in string aContentType,
 88                    in boolean aIsContentPreferred,
 89                    in nsIRequest aRequest,
 90                    out nsIStreamListener aContentHandler);
 91
 92 /**
 93  * When given a uri to dispatch, if the URI is specified as 'preferred 
 94  * content' then the uri loader tries to find a preferred content handler
 95  * for the content type. The thought is that many content listeners may
 96  * be able to handle the same content type if they have to. i.e. the mail
 97  * content window can handle text/html just like a browser window content
 98  * listener. However, if the user clicks on a link with text/html content,
 99  * then the browser window should handle that content and not the mail
100  * window where the user may have clicked the link.  This is the difference
101  * between isPreferred and canHandleContent.
102  *
103  * @param aContentType         Content type of the data.
104  * @param aDesiredContentType  Indicates that aContentType must be converted
105  *                             to aDesiredContentType before processing the
106  *                             data.  This causes a stream converted to be
107  *                             inserted into the nsIStreamListener chain.
108  *                             This argument can be <code>nsnull</code> if
109  *                             the content should be consumed directly as
110  *                             aContentType.
111  *
112  * @return                     <code>true</code> if this is a preferred
113  *                             content handler for aContentType;
114  *                             <code>false<code> otherwise.
115  */
116  boolean isPreferred(in string aContentType, out string aDesiredContentType);
117
118 /**
119  * When given a uri to dispatch, if the URI is not specified as 'preferred
120  * content' then the uri loader calls canHandleContent to see if the content
121  * listener is capable of handling the content.
122  *
123  * @param aContentType         Content type of the data.
124  * @param aIsContentPreferred  Indicates whether the content should be
125  *                             preferred by this listener.
126  * @param aDesiredContentType  Indicates that aContentType must be converted
127  *                             to aDesiredContentType before processing the
128  *                             data.  This causes a stream converted to be
129  *                             inserted into the nsIStreamListener chain.
130  *                             This argument can be <code>nsnull</code> if
131  *                             the content should be consumed directly as
132  *                             aContentType.
133  *
134  * @return                     <code>true</code> if the data can be consumed.
135  *                             <code>false</code> otherwise.
136  *
137  * Note: I really envision canHandleContent as a method implemented
138  * by the docshell as the implementation is generic to all doc
139  * shells. The isPreferred decision is a decision made by a top level
140  * application content listener that sits at the top of the docshell
141  * hierarchy.
142  */
143  boolean canHandleContent(in string aContentType, 
144                           in boolean aIsContentPreferred, 
145                           out string aDesiredContentType);
146
147 /**
148  * The load context associated with a particular content listener.
149  * The URI Loader stores and accesses this value as needed.
150  */
151  attribute nsISupports loadCookie;
152
153 /**
154  * The parent content listener if this particular listener is part of a chain
155  * of content listeners (i.e. a docshell!)
156  *
157  * @note If this attribute is set to an object that implements
158  *       nsISupportsWeakReference, the implementation should get the
159  *       nsIWeakReference and hold that.  Otherwise, the implementation
160  *       should not refcount this interface; it should assume that a non
161  *       null value is always valid.  In that case, the caller is
162  *       responsible for explicitly setting this value back to null if the
163  *       parent content listener is destroyed.
164  */
165  attribute nsIURIContentListener parentContentListener;
166};
167