1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/uriloader/base/nsIURIContentListener.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,135 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIRequest;
1.12 +interface nsIStreamListener;
1.13 +interface nsIURI;
1.14 +
1.15 +/**
1.16 + * nsIURIContentListener is an interface used by components which
1.17 + * want to know (and have a chance to handle) a particular content type.
1.18 + * Typical usage scenarios will include running applications which register
1.19 + * a nsIURIContentListener for each of its content windows with the uri
1.20 + * dispatcher service.
1.21 + */
1.22 +[scriptable, uuid(94928AB3-8B63-11d3-989D-001083010E9B)]
1.23 +interface nsIURIContentListener : nsISupports
1.24 +{
1.25 + /**
1.26 + * Gives the original content listener first crack at stopping a load before
1.27 + * it happens.
1.28 + *
1.29 + * @param aURI URI that is being opened.
1.30 + *
1.31 + * @return <code>false</code> if the load can continue;
1.32 + * <code>true</code> if the open should be aborted.
1.33 + */
1.34 + boolean onStartURIOpen(in nsIURI aURI);
1.35 +
1.36 + /**
1.37 + * Notifies the content listener to hook up an nsIStreamListener capable of
1.38 + * consuming the data stream.
1.39 + *
1.40 + * @param aContentType Content type of the data.
1.41 + * @param aIsContentPreferred Indicates whether the content should be
1.42 + * preferred by this listener.
1.43 + * @param aRequest Request that is providing the data.
1.44 + * @param aContentHandler nsIStreamListener that will consume the data.
1.45 + * This should be set to <code>nullptr</code> if
1.46 + * this content listener can't handle the content
1.47 + * type; in this case, doContent should also fail
1.48 + * (i.e., return failure nsresult).
1.49 + *
1.50 + * @return <code>true</code> if the load should
1.51 + * be aborted and consumer wants to
1.52 + * handle the load completely by itself. This
1.53 + * causes the URI Loader do nothing else...
1.54 + * <code>false</code> if the URI Loader should
1.55 + * continue handling the load and call the
1.56 + * returned streamlistener's methods.
1.57 + */
1.58 + boolean doContent(in string aContentType,
1.59 + in boolean aIsContentPreferred,
1.60 + in nsIRequest aRequest,
1.61 + out nsIStreamListener aContentHandler);
1.62 +
1.63 + /**
1.64 + * When given a uri to dispatch, if the URI is specified as 'preferred
1.65 + * content' then the uri loader tries to find a preferred content handler
1.66 + * for the content type. The thought is that many content listeners may
1.67 + * be able to handle the same content type if they have to. i.e. the mail
1.68 + * content window can handle text/html just like a browser window content
1.69 + * listener. However, if the user clicks on a link with text/html content,
1.70 + * then the browser window should handle that content and not the mail
1.71 + * window where the user may have clicked the link. This is the difference
1.72 + * between isPreferred and canHandleContent.
1.73 + *
1.74 + * @param aContentType Content type of the data.
1.75 + * @param aDesiredContentType Indicates that aContentType must be converted
1.76 + * to aDesiredContentType before processing the
1.77 + * data. This causes a stream converted to be
1.78 + * inserted into the nsIStreamListener chain.
1.79 + * This argument can be <code>nullptr</code> if
1.80 + * the content should be consumed directly as
1.81 + * aContentType.
1.82 + *
1.83 + * @return <code>true</code> if this is a preferred
1.84 + * content handler for aContentType;
1.85 + * <code>false<code> otherwise.
1.86 + */
1.87 + boolean isPreferred(in string aContentType, out string aDesiredContentType);
1.88 +
1.89 + /**
1.90 + * When given a uri to dispatch, if the URI is not specified as 'preferred
1.91 + * content' then the uri loader calls canHandleContent to see if the content
1.92 + * listener is capable of handling the content.
1.93 + *
1.94 + * @param aContentType Content type of the data.
1.95 + * @param aIsContentPreferred Indicates whether the content should be
1.96 + * preferred by this listener.
1.97 + * @param aDesiredContentType Indicates that aContentType must be converted
1.98 + * to aDesiredContentType before processing the
1.99 + * data. This causes a stream converted to be
1.100 + * inserted into the nsIStreamListener chain.
1.101 + * This argument can be <code>nullptr</code> if
1.102 + * the content should be consumed directly as
1.103 + * aContentType.
1.104 + *
1.105 + * @return <code>true</code> if the data can be consumed.
1.106 + * <code>false</code> otherwise.
1.107 + *
1.108 + * Note: I really envision canHandleContent as a method implemented
1.109 + * by the docshell as the implementation is generic to all doc
1.110 + * shells. The isPreferred decision is a decision made by a top level
1.111 + * application content listener that sits at the top of the docshell
1.112 + * hierarchy.
1.113 + */
1.114 + boolean canHandleContent(in string aContentType,
1.115 + in boolean aIsContentPreferred,
1.116 + out string aDesiredContentType);
1.117 +
1.118 + /**
1.119 + * The load context associated with a particular content listener.
1.120 + * The URI Loader stores and accesses this value as needed.
1.121 + */
1.122 + attribute nsISupports loadCookie;
1.123 +
1.124 + /**
1.125 + * The parent content listener if this particular listener is part of a chain
1.126 + * of content listeners (i.e. a docshell!)
1.127 + *
1.128 + * @note If this attribute is set to an object that implements
1.129 + * nsISupportsWeakReference, the implementation should get the
1.130 + * nsIWeakReference and hold that. Otherwise, the implementation
1.131 + * should not refcount this interface; it should assume that a non
1.132 + * null value is always valid. In that case, the caller is
1.133 + * responsible for explicitly setting this value back to null if the
1.134 + * parent content listener is destroyed.
1.135 + */
1.136 + attribute nsIURIContentListener parentContentListener;
1.137 +};
1.138 +
